• Deprecated
  • Not reviewed for accessibility

A 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

Checkbox group



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



children*ChoiceFieldset.Legend, ChoiceFieldset.Description, ChoiceFieldset.List, ChoiceFieldset.ValidationThe list of choices and contextual information
disabledbooleanWhether the fieldset is NOT ready for user input
idstringThe 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
namestringThe 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[]) => voidThe callback that is called when a user toggles a choice on or off
requiredbooleanWhether this field must have a value for the user to complete their task
selectedstring[]The selected values
validationMapRecord<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
validationResultkeyof validationMapThe 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.

visuallyHiddenbooleanWhether to visually hide the fieldset legend


The list choices are rendered in.

children*ChoiceFieldset.ItemThe choices that render as a checkbox or radio field
selectionVariant'single'\|'multiple'Whether multiple items or a single item can be selected


Renders a choice to the list as a checkbox or radio field.

children*ChoiceFieldset.Caption, ChoiceFieldset.Label, ChoiceFieldset.LeadingVisual, React.ReactNodeThe 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*stringThe value that is being selected
disabledbooleanWhether the field is ready for user input
idstringThe 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.


A ChoiceFieldset.Description may be used to render hint text if this list needs additional context to guide a user to make their selection

children*React.ReactNodeThe 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*React.ReactNodeThe validation message
validationKey*stringWhen this matches the validationResult prop on the parent ChoiceFieldset component, this validation component will be rendered



  • Component props and basic example usage of the component are documented on
  • 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
  • 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.