diff --git a/packages/@react-aria/checkbox/docs/useCheckboxGroup.mdx b/packages/@react-aria/checkbox/docs/useCheckboxGroup.mdx new file mode 100644 index 00000000000..d3b35bfacf0 --- /dev/null +++ b/packages/@react-aria/checkbox/docs/useCheckboxGroup.mdx @@ -0,0 +1,142 @@ + + +import {Layout} from '@react-spectrum/docs'; +export default Layout; + +import docs from 'docs:@react-aria/checkbox'; +import hiddenDocs from 'docs:@react-aria/visually-hidden'; +import focusDocs from 'docs:@react-aria/focus'; +import statelyDocs from 'docs:@react-stately/checkbox'; +import {HeaderInfo, FunctionAPI, TypeContext, InterfaceType, TypeLink} from '@react-spectrum/docs'; +import packageData from '@react-aria/checkbox/package.json'; + +```jsx import +import {useCheckboxGroup, useCheckboxGroupItem} from '@react-aria/checkbox'; +``` + +--- +category: Forms +keywords: [checkbox, input, aria] +after_version: 3.1.0 +--- + +# useCheckboxGroup + +

{docs.exports.useCheckboxGroup.description}

+ + + +## API + + + + +## Features + +Checkbox groups can be built in HTML with the +[<fieldset>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset) +and [<input>](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) elements, +however these can be difficult to style. `useCheckboxGroup` and `useCheckboxGroupItem` help achieve accessible +checkbox groups that can be styled as needed. + +* Checkbox groups are exposed to assistive technology via ARIA +* Each checkbox is built with a native HTML `` element, which can be optionally visually + hidden to allow custom styling +* Full support for browser features like form autofill +* Keyboard focus management and cross browser normalization +* Group and checkbox labeling support for assistive technology + +## Anatomy + +A checkbox group consists of a set of checkboxes, and a label. Each checkbox +includes a label and a visual selection indicator. Zero or more checkboxes +within the group can be selected at a time. Users may click or touch a checkbox +to select it, or use the Tab key to navigate to it +and the Space key to toggle it. + +`useCheckboxGroup` returns props for the group and its label, which you should spread +onto the appropriate element: + + + + + +`useCheckboxGroupItem` returns props for an individual checkbox: + + + + + +Selection state is managed by the +hook in `@react-stately/checkbox`. The state object should be passed as an option to `useCheckboxGroup` +and `useCheckboxGroupItem`. + +Individual checkboxes must have a visual label. If the checkbox group does not have a visible label, +an `aria-label` or `aria-labelledby` prop must be passed instead to identify the element to assistive +technology. + +**Note:** `useCheckboxGroupItem` should only be used when it is contained within a checkbox group. For a +standalone checkbox, use the [useCheckbox](useCheckbox.html) hook instead. + +## Example + +This example uses native input elements for the checkboxes, and React context to share state from the group +to each checkbox. An HTML `