Skip to content
On this page
On this page
A ChoiceFieldset is a controlled component that is used to render a related set of checkbox or radio inputs.
Deprecation
Use CheckboxGroup or RadioGroup instead.
Examples
Basic
Using an onSelect handler
Checkbox group
Disabled
Required
With pre-selected choices
With validation
A visually hidden legend
With a ChoiceFieldset.Description
With one disabled item
Items with a caption and a leading visual
Props
ChoiceFieldset
| Name | Type | Default | Description |
|---|---|---|---|
| children* | ChoiceFieldset.Legend, ChoiceFieldset.Description, ChoiceFieldset.List, ChoiceFieldset.Validation | – | The list of choices and contextual information |
| disabled | boolean | – | Whether the fieldset is NOT ready for user input |
| id | string | – | The unique identifier for this fieldset. Used to associate the validation text with the fieldset If an ID is not passed, one will be automatically generated |
| name | string | – | The unique identifier used to associate radio inputs with eachother If a name is not passed and the fieldset renders radio inputs, a name will be automatically generated |
| onSelect | (selectedValues?: string[]) => void | – | The callback that is called when a user toggles a choice on or off |
| required | boolean | – | Whether this field must have a value for the user to complete their task |
| selected | string[] | – | The selected values |
| validationMap | Record<string, 'error' \| 'success'> | – | A map of validation statuses and their associated validation keys. When one of the validation keys is passed to the validationResult prop, the associated validation message will be rendered in the correct style |
| validationResult | keyof validationMap | – | The key of the validation message to show |
ChoiceFieldset.Legend
A title for the set of choices. A ChoiceFieldset.Legend must be passed, but it may be visually hidden.
| Name | Type | Default | Description |
|---|---|---|---|
| visuallyHidden | boolean | – | Whether to visually hide the fieldset legend |
ChoiceFieldset.List
The list choices are rendered in.
| Name | Type | Default | Description |
|---|---|---|---|
| children* | ChoiceFieldset.Item | – | The choices that render as a checkbox or radio field |
| selectionVariant | 'single'\|'multiple' | – | Whether multiple items or a single item can be selected |
ChoiceFieldset.Item
Renders a choice to the list as a checkbox or radio field.
| Name | Type | Default | Description |
|---|---|---|---|
| children* | ChoiceFieldset.Caption, ChoiceFieldset.Label, ChoiceFieldset.LeadingVisual, React.ReactNode | – | The parts that make up the checkbox or radio field used to select the choice. If you only need a label, it's fine to pass in a string or JSX instead of wrapping it in the Item.Label component |
| value* | string | – | The value that is being selected |
| disabled | boolean | – | Whether the field is ready for user input |
| id | string | – | The unique identifier for this field. Used to associate the label, validation text, and caption text. If an ID is not provided, one will be automatically generated. |
ChoiceFieldset.Description
A ChoiceFieldset.Description may be used to render hint text if this list needs additional context to guide a user to make their selection
| Name | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode | – | The description content |
ChoiceFieldset.Validation
If the user's selection has been flagged during validation, ChoiceFieldset.Validation may be used to render contextual validation information to help the user complete their task
| Name | Type | Default | Description |
|---|---|---|---|
| children* | React.ReactNode | – | The validation message |
| validationKey* | string | – | When this matches the validationResult prop on the parent ChoiceFieldset component, this validation component will be rendered |
Status
Alpha
- Component props and basic example usage of the component are documented on primer.style/react.
- Component does not have any unnecessary third-party dependencies.
- Component can adapt to different themes.
- Component can adapt to different screen sizes.
- Component has robust unit test coverage (100% where achievable).
- Component has visual regression coverage of its default and interactive states.
- Component does not introduce any axe violations.
- Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.
Beta
- Component is used in a production application.
- Common usage examples are documented on primer.style/react.
- Common usage examples are documented in storybook stories.
- Component has been reviewed by a systems designer and any resulting issues have been addressed.
- Component does not introduce any performance regressions.
Stable
- Component API has been stable with no breaking changes for at least one month.
- Feedback on API usability has been sought from developers using the component and any resulting issues have been addressed.
- Component has corresponding design guidelines documented in the interface guidelines.
- Component has corresponding Figma component in the Primer Web library.
- Tooling (such as linters, codemods, etc.) exists to prevent further use of alternatives.
Related components
Edit this page on GitHub
2 contributors
Last edited by joshblack on January 23, 2023