Skip to content

FormControl

Renders a labelled input and, optionally, associated validation text and/or hint text.
  • Alpha
  • Review pending by accessibility team

Examples

Basic

With complex inputs

With a custom input

When rendering an input other than a form component from Primer, you must manually pass the attributes that make the form control accessible:

  • The input should have an ID
  • FormControl.Label should be associated with the text input by using htmlFor
  • If there is a caption, the input should be associated with the caption by passing the message's ID to aria-describedby
  • If there is a validation message, the input should be associated with the message by passing the message's ID to aria-describedby
  • If there is both a caption and a validation message, the input should be associated with the message by passing the both the validation message's ID and the caption's ID to aria-describedby. Example: aria-describedby="caption-id validation-id"
  • If the input's value is invalid, aria-invalid={true} should be passed to the input.
  • If the input is disabled, disabled should be passed.
  • If the input is required, required should be passed.

When rendering a custom checkbox or radio component, you must also pass layout="horizontal" to the FormControl component.

With checkbox and radio inputs

Required

Checkbox and radio form controls cannot be required individually. Instead, you can require a selection from the entire group of checkboxes or radios.

Disabled

With a visually hidden label

We encourage using FormControl alongside all standalone form components like TextInput, as every input must have a corresponding label to be accessible to assistive technology.

FormControl also provides an interface for showing a hint text caption and a validation message, and associating those with the input for assistive technology.

With a caption

With validation

Validation messages are not used for an individual checkbox or radio form control.

With a leading visual

Only a checkbox or radio form control may have a leading visual.

Props

FormControl

The container that handles the layout and passes the relevant IDs and ARIA attributes its children.

NameTypeDefaultDescription
children Required
FormControl.Label | FormControl.Caption | FormControl.Validation | Autocomplete | TextInput | TextInputWithTokens | Select
disabled
boolean
falseWhether the control allows user input
id
string
a generated stringThe unique identifier for this control. Used to associate the label, validation text, and caption text
required
boolean
falseIf true, the user must specify a value for the input before the owning form can be submitted
ref
React.RefObject<HTMLDivElement>
A ref to the element rendered by this component.
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.

FormControl.Label

A FormControl.Label must be passed for the field to be accessible to assistive technology, but it may be visually hidden.

NameTypeDefaultDescription
visuallyHidden
boolean
falseWhether the label should be visually hidden
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.

FormControl.Caption

FormControl.Caption may be used to render hint text for fields that require additional context.

NameTypeDefaultDescription
children
React.ReactNode
The content (usually just text) that is rendered to give contextual info about the field
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.

FormControl.Validation

Use FormControl.Validation to render contextual validation information if necessary.

NameTypeDefaultDescription
children
React.ReactNode
The content (usually just text) that is rendered to give contextual info about the validation result for the field
variant Required
'error' | 'success' | 'warning'
Changes the visual style to match the validation status
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.

Validation messages should not be shown for an individual checkbox or radio form control, so FormControl.Validation will not be rendered when a Checkbox or Radio is not a child of FormControl. Validation messages for checkbox and radio selections should only apply to the entire group of inputs.

FormControl.LeadingVisual

Use FormControl.LeadingVisual if the selectable option is easier to understand with a visual.

NameTypeDefaultDescription
children
React.ReactNode
The visual to render before the choice input's label
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.

Only a checkbox or radio form control may have a leading visual. If you want to render a leading visual inside an input, check if that input component supports a leading visual.

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