{
  "name": "RadioGroup",
  "source": "src/components/Radio.tsx",
  "propsType": "RadioGroupProps",
  "description": "Renders a `<fieldset>` with a `<legend>` rather than a div with\n`role=\"radiogroup\"`. Both are announced correctly, but a fieldset also groups\nthe inputs for form submission and native validation, which the ARIA version\ndoes not.\n\nThe fieldset itself is Fieldset's shell, shared with CheckboxGroup, so the\ntwo choice groups take the same label, help, error and orientation props.",
  "import": "import { RadioGroup } from 'ionbase-ui';",
  "status": "stable",
  "summary": "A <fieldset>/<legend> group of mutually exclusive options. Owns the shared name and the selected value, and the group's label, help and error.",
  "useWhen": [
    "exactly one choice from a small set, all worth showing at once",
    "the options need explaining — each one can carry its own label text"
  ],
  "useInstead": [
    {
      "when": "the list is long, or space is tight",
      "use": "Select"
    },
    {
      "when": "more than one may be picked",
      "use": "CheckboxGroup"
    },
    {
      "when": "there are exactly two states and the change is immediate",
      "use": "Toggle"
    },
    {
      "when": "each option needs a sentence to be chosen well — a plan, a trigger, a schedule",
      "use": "SelectableTile",
      "why": "the same group with tiles for its options: each a real radio the size of a card, its sentence read after its name"
    }
  ],
  "variants": {
    "size": {
      "sm": {
        "use": "dense forms"
      },
      "md": {
        "use": "the default"
      },
      "lg": {
        "use": "touch targets and prominent choices"
      }
    },
    "intent": {
      "brand": {
        "use": "the default"
      },
      "neutral": {
        "use": "a choice with no positive reading — sort order, display mode"
      },
      "danger": {
        "use": "a set where the options are destructive"
      }
    },
    "orientation": {
      "vertical": {
        "use": "the default, and always when a label runs past a few words"
      },
      "horizontal": {
        "use": "two to four one-word options. Wraps rather than overflows"
      }
    }
  },
  "slots": {
    "label": {
      "accepts": "text",
      "note": "renders as the <legend> — the question the options answer"
    },
    "description": {
      "accepts": "text",
      "note": "help beneath the options; replaced by `errorMessage` while `isInvalid` is set"
    },
    "errorMessage": {
      "accepts": "text",
      "note": "shown only while `isInvalid` is set"
    },
    "children": {
      "accepts": "Radio"
    }
  },
  "a11y": {
    "role": "group, from <fieldset> and <legend>",
    "guarantees": [
      "a real fieldset rather than `role=\"radiogroup\"`: both announce correctly, but the fieldset also groups the inputs for form submission and native validation",
      "`name` is generated when omitted, so two groups on one page never collide",
      "`isDisabled` cascades to every Radio that has not set its own",
      "the fieldset is Fieldset's shell, shared with CheckboxGroup — the same label, help, error and orientation props",
      "the description or error is on every radio's `aria-describedby` as well as the fieldset's, so it is read on the radio that takes focus",
      "`isRequired` is native `required` on the radios, which the platform already reads as \"one of this name\""
    ],
    "requires": [
      "`label`, or `aria-label` when the question is already visible elsewhere"
    ]
  },
  "antiPatterns": [
    {
      "dont": "an unlabelled group",
      "why": "the options are announced with no question attached"
    },
    {
      "dont": "passing both `value` and `defaultValue`",
      "why": "controlled and uncontrolled at once; the controlled value wins and `defaultValue` silently does nothing"
    },
    {
      "dont": "no option selected by default with no \"none\" option",
      "why": "a radio group cannot be returned to empty once touched"
    }
  ],
  "deprecated": [
    {
      "prop": "disabled",
      "replacement": "isDisabled"
    }
  ],
  "stylesheet": "src/styles/radio.css",
  "tokens": [
    "--border-disabled",
    "--border-error-strong",
    "--border-focus",
    "--border-inverse",
    "--border-primary-strong",
    "--border-stronger",
    "--border-width-default",
    "--border-width-thick",
    "--font-family-sans",
    "--icon-disabled",
    "--icon-on-color",
    "--ion-duration-base",
    "--ion-ease-out",
    "--ion-radio-border",
    "--ion-radio-dot",
    "--ion-radio-fill",
    "--ion-radio-font-size",
    "--ion-radio-gap",
    "--ion-radio-line-height",
    "--ion-radio-raised",
    "--ion-radio-size",
    "--ion-shadow-raised-flush-lg",
    "--ion-shadow-raised-flush-sm",
    "--ion-shadow-raised-flush-xs",
    "--radius-full",
    "--spacing-12",
    "--spacing-16",
    "--spacing-2",
    "--spacing-20",
    "--spacing-24",
    "--spacing-8",
    "--surface-default",
    "--surface-disabled",
    "--surface-error",
    "--surface-inverse",
    "--surface-primary",
    "--text-disabled",
    "--text-secondary",
    "--type-body",
    "--type-body-line-height",
    "--type-body-sm",
    "--type-body-sm-line-height"
  ],
  "props": {
    "name": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Shared input name. Generated when omitted."
    },
    "value": {
      "type": "string | undefined",
      "required": false,
      "origin": "own"
    },
    "defaultValue": {
      "type": "string | undefined",
      "required": false,
      "origin": "own"
    },
    "onChange": {
      "type": "((value: string) => void) | undefined",
      "required": false,
      "origin": "own"
    },
    "label": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "The question the options answer. Renders as the `<legend>`."
    },
    "description": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Help text beneath the options. Replaced by `errorMessage` while invalid."
    },
    "errorMessage": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Shown in the description's place while `isInvalid` is set."
    },
    "isInvalid": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "Shows `errorMessage` in the description's place."
    },
    "isRequired": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "One option must be chosen before the form submits."
    },
    "orientation": {
      "type": "FieldsetOrientation | undefined",
      "required": false,
      "origin": "own",
      "values": [
        "vertical",
        "horizontal"
      ]
    },
    "size": {
      "type": "RadioSize | undefined",
      "required": false,
      "origin": "own",
      "values": [
        "sm",
        "md",
        "lg"
      ]
    },
    "intent": {
      "type": "RadioIntent | undefined",
      "required": false,
      "origin": "own",
      "values": [
        "neutral",
        "danger",
        "brand"
      ]
    },
    "isDisabled": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "Whether every radio in the group is disabled."
    },
    "disabled": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "tags": {
        "deprecated": "Use `isDisabled`. Accepted as an alias for one minor version."
      }
    },
    "children": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own"
    }
  },
  "propCounts": {
    "own": 15,
    "aria": 0,
    "dom": 276,
    "other": 0
  }
}