{
  "name": "CheckboxGroup",
  "source": "src/components/Checkbox.tsx",
  "propsType": "CheckboxGroupProps",
  "description": "A set of checkboxes that answers one question — \"notify me when…\", \"which\nregions\". Owns the selected values, the group's label, help text and error,\nand \"select at least one\".\n\nA row of loose Checkboxes can do none of that accessibly: the question is\nnot announced with the options, an error has nothing to attach to, and\n\"at least one\" has no native expression at all. See the `required` note in\nCheckbox for how that last one is done.",
  "import": "import { CheckboxGroup } from 'ionbase-ui';",
  "status": "stable",
  "summary": "A set of checkboxes answering one question. Owns the selected values, the group's label, help and error, and \"select at least one\".",
  "useWhen": [
    "several options may be picked and they answer one question — \"notify me when\", \"regions\", \"columns to show\"",
    "the group needs a rule of its own — at least one, or an error that belongs to the set rather than to an option"
  ],
  "useInstead": [
    {
      "when": "only one option may be picked",
      "use": "RadioGroup"
    },
    {
      "when": "the options are many, or space is tight",
      "use": "MultiSelect",
      "why": "past about seven options a list of boxes is longer than the form around it; MultiSelect filters them and shows the chosen ones as tags"
    },
    {
      "when": "there is one on/off choice",
      "use": "Checkbox",
      "why": "a group of one announces a question and then its only answer"
    },
    {
      "when": "each option takes effect immediately",
      "use": "Toggle"
    },
    {
      "when": "each option needs a sentence to be chosen well, and several can be",
      "use": "SelectableTile",
      "why": "the same group with tiles for its options: each a real checkbox the size of a card, its sentence read after its name"
    }
  ],
  "composition": {
    "order": [
      "CheckboxGroup",
      "Checkbox"
    ],
    "note": "Give every Checkbox a `value`; the group's `onChange` receives the array of ticked values. Selection lives on the group — do not also set `isSelected` on the boxes.",
    "example": "<CheckboxGroup label=\"Notify the team when\" isRequired value={notifyOn} onChange={setNotifyOn} isInvalid={!!error} errorMessage={error}><Checkbox value=\"failed\">A run fails</Checkbox><Checkbox value=\"approval\">A run needs approval</Checkbox></CheckboxGroup>"
  },
  "variants": {
    "size": {
      "sm": {
        "use": "dense forms and filter panels"
      },
      "md": {
        "use": "the default"
      },
      "lg": {
        "use": "touch targets and prominent choices"
      }
    },
    "intent": {
      "brand": {
        "use": "the default"
      },
      "neutral": {
        "use": "facts rather than approvals — the columns shown, the filters applied"
      },
      "danger": {
        "use": "a set of destructive consents"
      }
    },
    "orientation": {
      "vertical": {
        "use": "the default, and always when a label runs past a few words"
      },
      "horizontal": {
        "use": "two to four one-word options — weekdays, regions. 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": "Checkbox"
    }
  },
  "a11y": {
    "role": "group, from <fieldset> and <legend>",
    "guarantees": [
      "the legend is announced as the group's name when focus enters any box",
      "the description or error is on every box's `aria-describedby` as well as the fieldset's, so it is read on the box that takes focus",
      "`isInvalid` sets `aria-invalid` on every box",
      "`isRequired` sets native `required` on every box while none is ticked and on none once one is: the browser blocks the submit in its own language, and each box announces \"required\" exactly while the rule is unmet",
      "`isDisabled` cascades to every Checkbox that has not set its own"
    ],
    "requires": [
      "`label`, or `aria-label` when the question is already visible elsewhere",
      "a `value` on every Checkbox — the group tracks the selection by it"
    ]
  },
  "antiPatterns": [
    {
      "dont": "loose Checkboxes under a text label",
      "why": "the question is not announced with the options, an error has nothing to attach to, and \"at least one\" cannot be expressed"
    },
    {
      "dont": "`isSelected` or `checked` on a Checkbox inside a group",
      "why": "the group owns the selection; the box's own value is ignored"
    },
    {
      "dont": "`isRequired` on every Checkbox in the group",
      "why": "that means every box must be ticked; `isRequired` on the group means at least one"
    }
  ],
  "stylesheet": "src/styles/checkbox.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-checkbox-border",
    "--ion-checkbox-fill",
    "--ion-checkbox-font-size",
    "--ion-checkbox-gap",
    "--ion-checkbox-line-height",
    "--ion-checkbox-mark",
    "--ion-checkbox-radius",
    "--ion-checkbox-raised",
    "--ion-checkbox-size",
    "--ion-duration-base",
    "--ion-ease-out",
    "--ion-shadow-raised-flush-lg",
    "--ion-shadow-raised-flush-sm",
    "--ion-shadow-raised-flush-xs",
    "--radius-sm",
    "--radius-xs",
    "--spacing-12",
    "--spacing-16",
    "--spacing-20",
    "--spacing-24",
    "--spacing-4",
    "--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": {
    "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": "Marks every box invalid and shows `errorMessage`."
    },
    "isRequired": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "At least one option must be selected — enforced by native validation."
    },
    "value": {
      "type": "readonly string[] | undefined",
      "required": false,
      "origin": "own",
      "description": "The selected values (controlled)."
    },
    "defaultValue": {
      "type": "readonly string[] | undefined",
      "required": false,
      "origin": "own",
      "description": "The initially selected values (uncontrolled)."
    },
    "onChange": {
      "type": "((value: string[]) => void) | undefined",
      "required": false,
      "origin": "own",
      "description": "Receives the whole new selection, in the order the options were ticked."
    },
    "name": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "Shared input name, so a form submits every ticked value under it."
    },
    "size": {
      "type": "CheckboxSize | undefined",
      "required": false,
      "origin": "own",
      "values": [
        "sm",
        "md",
        "lg"
      ]
    },
    "intent": {
      "type": "CheckboxIntent | undefined",
      "required": false,
      "origin": "own",
      "values": [
        "neutral",
        "danger",
        "brand"
      ]
    },
    "isDisabled": {
      "type": "boolean | undefined",
      "required": false,
      "origin": "own",
      "description": "Whether every checkbox in the group is disabled."
    },
    "orientation": {
      "type": "FieldsetOrientation | undefined",
      "required": false,
      "origin": "own",
      "values": [
        "vertical",
        "horizontal"
      ]
    },
    "children": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "Checkboxes, each with a `value`."
    }
  },
  "propCounts": {
    "own": 14,
    "aria": 0,
    "dom": 276,
    "other": 0
  }
}