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
Required field
With validation message and caption text
Something went wrong
Props
FormControl
| Name | Required | Description |
|---|---|---|
children | Required | FormControl.Label | FormControl.Caption | FormControl.Validation | Autocomplete | TextInput | TextInputWithTokens | Select |
disabled | booleanWhether the control allows user input | |
id | stringThe unique identifier for this control. Used to associate the label, validation text, and caption text | |
required | booleanIf true, the user must specify a value for the input before the owning form can be submitted | |
id | stringThe unique identifier for this control. Used to associate the label, validation text, and caption text | |
layout | 'vertical' | 'horizontal'The direction the content flows.
Vertical layout is used by default, and horizontal layout is used for checkbox and radio inputs. | |
className | stringClass name(s) for custom styling. | |
sx | SystemStyleObject | |
ref | React.RefObject<HTMLDivElement> |
FormControl.Label
| Name | Required | Description |
|---|---|---|
visuallyHidden | booleanWhether the label should be visually hidden | |
as | '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 | stringThe text to display when the field is required | |
requiredIndicator | booleanWhether to show or hide the required text in the accessibility tree, the required text is still shown visually. | |
htmlFor | stringThis prop may be used to override the `htmlFor` set from FormControl's React Context.
The unique identifier for the associated input | |
id | stringWhen `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 | stringClass name(s) for custom styling. | |
sx | SystemStyleObject |
FormControl.Caption
| Name | Required | Description |
|---|---|---|
id | stringCustom ID to override the ID set by FormControl's React Context | |
children | React.ReactNodeThe content (usually just text) that is rendered to give contextual info about the field | |
sx | SystemStyleObject |
FormControl.Validation
| Name | Required | Description |
|---|---|---|
children | React.ReactNodeThe 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 | stringMay be used to override the ID assigned by FormControl's React Context | |
sx | SystemStyleObject |
FormControl.LeadingVisual
| Name | Required | Description |
|---|---|---|
children | React.ReactNodeThe visual to render before the choice input's label | |
sx | SystemStyleObject |