Skip to content

ChoiceFieldset

Alpha

A ChoiceFieldset is a controlled component that is used to render a related set of checkbox or radio inputs.

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

NameTypeDefaultDescription
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

ChoiceFieldset.Legend

A title for the set of choices. A ChoiceFieldset.Legend must be passed, but it may be visually hidden.

NameTypeDefaultDescription
visuallyHiddenbooleanWhether to visually hide the fieldset legend

ChoiceFieldset.List

The list choices are rendered in.

NameTypeDefaultDescription
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

ChoiceFieldset.Item

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

NameTypeDefaultDescription
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.

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

NameTypeDefaultDescription
children*React.ReactNodeThe 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

NameTypeDefaultDescription
children*React.ReactNodeThe validation message
validationKey*stringWhen this matches the validationResult prop on the parent ChoiceFieldset component, this validation component will be rendered

Status

Alpha

  • Component props 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 100% test coverage.

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 has been manually reviewed by the accessibility team and any resulting issues have been addressed.

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.