Form control

Use the form control component to display form inputs alongside labels, validation and more.
  • Experimental
  • Not reviewed for accessibility
import {FormControl} from '@primer/react-brand'

Examples

Basic

FormControl is responsible for layout and ensuring that relevant IDs and ARIA attributes are passed to its children.

Alternative inputs

Layout

FormControl can help compose form layouts quickly, while ensuring the inputs are accessible for assistive technologies.

An example of a typical layout composed using FormControl:

Visually hidden label

Labels should only be visually hidden when the context is clear from the input itself. For example, a search input with a search icon. The majority of the time, labels should be visible.

Validation

The following example demonstrates declarative form validation in controlled mode.

Try changing the input value to to monalisa to show the success state.

Hint

FormControl.Hint can be used to provide additional context or guidance to the user. FormControl.Hint must be a direct child of FormControl.

Full width

Pass the fullWidth prop to FormControl to provide additional behavior and state context to all children, rather than the input only.

Sizes

FormControl can appear in medium and large dimensions using the size prop.

Required

Pass the required prop to FormControl to provide additional behavior and state context to all children, rather than the input only.

Using refs

FormControl inputs can be used in uncontrolled mode by forwarding a ref to the underlying element.

Component props

FormControl Required

FormControl passes contextual data to its child inputs, labels, validation messaging and more.

NameTypeDefaultDescription
children'FormControl.Label'
'Checkbox'
'Select'
'TextInput'
'FormControl.Validation'
'React.ReactElement'
,
Valid child nodes
classNamestringSets a custom class
idstringSets a custom id
fullWidthbooleanStretches elements visually to the edges of its parent container.
refReact.RefObjectForward a Ref to the underlying DOM node
size'medium'
'large'
Visual dimensions for input and label
validationStatus'error'
'success'
Applies visual and semantic state to the underlying elements

FormControl.Label Required

FormControl.Label should be provided for the FormControl to be accessible to assistive technology, but it may be visually hidden.

NameTypeDefaultDescription
childrenstringLabel text
classNamestringApplies a custom class
idstringSets a custom id
refReact.RefObjectForward a Ref to the underlying DOM node
size'medium'
'large'
'medium'Set visual dimensions
visuallyHiddenbooleanfalseHide for sighted users

Additional props can be passed to the <label> element. See MDN for a list of props accepted by the <label> element.

FormControl.Validation

NameTypeDefaultDescription
childrenstringValidation message
classNamestringFormControl.Validation custom class
idstringSets a custom id
refReact.RefObjectForward a Ref to the underlying DOM node
validationStatus'error'
'success'
Applies a visual and semantic validation state to the underlying elements