FormControl

Renders a labelled input and, optionally, associated validation text and/or hint text.
  • Alpha
  • Not reviewed for accessibility

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

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
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.
ref
React.RefObject<HTMLDivElement>
A ref to the element rendered by this component.

FormControl.Label

NameTypeDefaultDescription
visuallyHidden
boolean
falseWhether the label should be visually hidden
as
React.ElementType
'label'The label element can be changed to a 'legend' when it's being used to label a fieldset, or a 'span' when it's being used to label an element that is not a form input. For example: when using a FormControl to render a labeled SegementedControl, the label should be a 'span'
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.

FormControl.Caption

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

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'
Changes the visual style to match the validation status
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.

FormControl.LeadingVisual

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.

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