On this page
On this page
ChoiceFieldset is a controlled component that is used to render a related set of checkbox or radio inputs.
Use CheckboxGroup or RadioGroup instead.
Using an onSelect handler
With pre-selected choices
A visually hidden legend
With a ChoiceFieldset.Description
With one disabled item
Items with a caption and a leading visual
|children*||–||The list of choices and contextual information|
|disabled||–||Whether the fieldset is NOT ready for user input|
|id||–||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||–||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||–||The callback that is called when a user toggles a choice on or off|
|required||–||Whether this field must have a value for the user to complete their task|
|selected||–||The selected values|
|validationMap||–||A map of validation statuses and their associated validation keys. When one of the validation keys is passed to the |
|validationResult||–||The key of the validation message to show|
A title for the set of choices. A
ChoiceFieldset.Legend must be passed, but it may be visually hidden.
|visuallyHidden||–||Whether to visually hide the fieldset legend|
The list choices are rendered in.
|children*||–||The choices that render as a checkbox or radio field|
|selectionVariant||–||Whether multiple items or a single item can be selected|
Renders a choice to the list as a checkbox or radio field.
|children*||–||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
|value*||–||The value that is being selected|
|disabled||–||Whether the field is ready for user input|
|id||–||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 may be used to render hint text if this list needs additional context to guide a user to make their selection
|children*||–||The description content|
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
|children*||–||The validation message|
|validationKey*||–||When this matches the |
- 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.
- 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.
- 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.