FormControl

FormControl displays a labelled input and, optionally, associated validation text and/or hint text.

React

readyNot reviewed for a11y

Rails

readyNot reviewed for a11y

Use FormControls when requiring data input from the user. For example, creating a new repo configuring settings, and logging in.

This component is a helper component to keep layouts consistent and ensure the correct ARIA attributes are set. You can find some of Primer's form components listed in the Related links section.

React examples

Default

Label

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput />
</FormControl>

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput />
</FormControl>

Required field

Label*

<FormControl required>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput />
</FormControl>

<FormControl required>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput />
</FormControl>

With validation message and caption text

Label

Something went wrong

This is a caption

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput />
  <FormControl.Caption>This is a caption</FormControl.Caption>
  <FormControl.Validation variant="error">Something went wrong</FormControl.Validation>
</FormControl>

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput />
  <FormControl.Caption>This is a caption</FormControl.Caption>
  <FormControl.Validation variant="error">Something went wrong</FormControl.Validation>
</FormControl>

Props

FormControl

Name	Default	Description
children Required		`FormControl.Label \| FormControl.Caption \| FormControl.Validation \| Autocomplete \| TextInput \| TextInputWithTokens \| Select`
disabled	`false`	`boolean` Whether the control allows user input
id	`a generated string`	`string` The unique identifier for this control. Used to associate the label, validation text, and caption text
required	`false`	`boolean` If true, the user must specify a value for the input before the owning form can be submitted
id		`string` The unique identifier for this control. Used to associate the label, validation text, and caption text
layout	`vertical`	`'vertical' \| 'horizontal'` The direction the content flows. Vertical layout is used by default, and horizontal layout is used for checkbox and radio inputs.
className		`string` Class name(s) for custom styling.
sx		`SystemStyleObject`
ref		`React.RefObject<HTMLDivElement>`

FormControl.Label

Name	Default	Description
visuallyHidden	`false`	`boolean` Whether the label should be visually hidden
as	`'label'`	`'label' \| 'legend' \| 'span'` 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'
requiredText	`'*'`	`string` The text to display when the field is required
requiredIndicator	`true`	`boolean` Whether to show or hide the required text in the accessibility tree, the required text is still shown visually.
htmlFor		`string` This prop may be used to override the `htmlFor` set from FormControl's React Context. The unique identifier for the associated input
id		`string` When `as` prop is 'label', it may be used to override the `htmlFor` given to the <label> element by FormControl's React Context. When 'as' prop is 'legend' or 'span', it is used as the `id` for the element.
className		`string` Class name(s) for custom styling.
sx		`SystemStyleObject`

FormControl.Caption

Name	Default	Description
id		`string` Custom ID to override the ID set by FormControl's React Context
children		`React.ReactNode` The content (usually just text) that is rendered to give contextual info about the field
sx		`SystemStyleObject`

FormControl.Validation

Name	Default	Description
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
id		`string` May be used to override the ID assigned by FormControl's React Context
sx		`SystemStyleObject`

FormControl.LeadingVisual

Name	Default	Description
children		`React.ReactNode` The visual to render before the choice input's label
sx		`SystemStyleObject`