Primer Design System

Site navigation

FormControl

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

Alpha
Not reviewed for accessibility

On this page

This documentation is moving to a new home. Please update any link or bookmark that points to this page. The new content can be found here.

Examples

Basic

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

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

With complex inputs

const DifferentInputs = () => {
  const [tokens, setTokens] = React.useState([
    {text: 'zero', id: 0},
    {text: 'one', id: 1},
    {text: 'two', id: 2},
  ])
  const onTokenRemove = tokenId => {
    setTokens(tokens.filter(token => token.id !== tokenId))
  }

  return (
    <Box display="grid" gridGap={3}>
      <FormControl>
        <FormControl.Label>TextInputWithTokens</FormControl.Label>
        <TextInputWithTokens onTokenRemove={onTokenRemove} tokens={tokens} />
      </FormControl>
      <FormControl>
        <FormControl.Label>Autocomplete</FormControl.Label>
        <Autocomplete>
          <Autocomplete.Input block />
          <Autocomplete.Overlay>
            <Autocomplete.Menu
              items={[
                {text: 'css', id: 0},
                {text: 'css-in-js', id: 1},
                {text: 'styled-system', id: 2},
                {text: 'javascript', id: 3},
                {text: 'typescript', id: 4},
                {text: 'react', id: 5},
                {text: 'design-systems', id: 6},
              ]}
              selectedItemIds={[]}
            />
          </Autocomplete.Overlay>
        </Autocomplete>
      </FormControl>
      <FormControl>
        <FormControl.Label>Select</FormControl.Label>
        <Select>
          <Select.Option value="figma">Figma</Select.Option>
          <Select.Option value="css">Primer CSS</Select.Option>
          <Select.Option value="prc">Primer React components</Select.Option>
          <Select.Option value="pvc">Primer ViewComponents</Select.Option>
        </Select>
      </FormControl>
      <FormControl>
        <FormControl.Label>Textarea</FormControl.Label>
        <Textarea />
      </FormControl>
    </Box>
  )
}

render(DifferentInputs)

const DifferentInputs = () => {
  const [tokens, setTokens] = React.useState([
    {text: 'zero', id: 0},
    {text: 'one', id: 1},
    {text: 'two', id: 2},
  ])
  const onTokenRemove = tokenId => {
    setTokens(tokens.filter(token => token.id !== tokenId))
  }

  return (
    <Box display="grid" gridGap={3}>
      <FormControl>
        <FormControl.Label>TextInputWithTokens</FormControl.Label>
        <TextInputWithTokens onTokenRemove={onTokenRemove} tokens={tokens} />
      </FormControl>
      <FormControl>
        <FormControl.Label>Autocomplete</FormControl.Label>
        <Autocomplete>
          <Autocomplete.Input block />
          <Autocomplete.Overlay>
            <Autocomplete.Menu
              items={[
                {text: 'css', id: 0},
                {text: 'css-in-js', id: 1},
                {text: 'styled-system', id: 2},
                {text: 'javascript', id: 3},
                {text: 'typescript', id: 4},
                {text: 'react', id: 5},
                {text: 'design-systems', id: 6},
              ]}
              selectedItemIds={[]}
            />
          </Autocomplete.Overlay>
        </Autocomplete>
      </FormControl>
      <FormControl>
        <FormControl.Label>Select</FormControl.Label>
        <Select>
          <Select.Option value="figma">Figma</Select.Option>
          <Select.Option value="css">Primer CSS</Select.Option>
          <Select.Option value="prc">Primer React components</Select.Option>
          <Select.Option value="pvc">Primer ViewComponents</Select.Option>
        </Select>
      </FormControl>
      <FormControl>
        <FormControl.Label>Textarea</FormControl.Label>
        <Textarea />
      </FormControl>
    </Box>
  )
}

render(DifferentInputs)

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.

const CustomTextInput = props => <input type="text" {...props} />
const CustomCheckboxInput = props => <input type="checkbox" {...props} />
const FormControlWithCustomInput = () => {
  const [value, setValue] = React.useState('mona lisa')
  const [validationResult, setValidationResult] = React.useState()
  const doesValueContainSpaces = inputValue => /\s/g.test(inputValue)
  const handleInputChange = e => {
    setValue(e.currentTarget.value)
  }

  React.useEffect(() => {
    if (doesValueContainSpaces(value)) {
      setValidationResult('noSpaces')
    } else if (value) {
      setValidationResult('validName')
    }
  }, [value])

  return (
    <Box display="grid" gridGap={3}>
      <FormControl>
        <FormControl.Label htmlFor="custom-input">GitHub handle</FormControl.Label>
        <CustomTextInput
          id="custom-input"
          aria-describedby="custom-input-caption custom-input-validation"
          aria-invalid={validationResult === 'noSpaces'}
          onChange={handleInputChange}
        />
        {validationResult === 'noSpaces' && (
          <FormControl.Validation id="custom-input-validation" variant="error">
            GitHub handles cannot contain spaces
          </FormControl.Validation>
        )}
        {validationResult === 'validName' && (
          <FormControl.Validation id="custom-input-validation" variant="success">
            Valid name
          </FormControl.Validation>
        )}
        <FormControl.Caption id="custom-input-caption">
          With or without "@". For example "monalisa" or "@monalisa"
        </FormControl.Caption>
      </FormControl>

      <CheckboxGroup>
        <CheckboxGroup.Label>Checkboxes</CheckboxGroup.Label>
        <FormControl layout="horizontal">
          <CustomCheckboxInput id="custom-checkbox-one" value="checkOne" />
          <FormControl.Label htmlFor="custom-checkbox-one">Checkbox one</FormControl.Label>
          <FormControl.Caption id="custom-checkbox-one-caption">Hint text for checkbox one</FormControl.Caption>
        </FormControl>
        <FormControl layout="horizontal">
          <CustomCheckboxInput id="custom-checkbox-two" value="checkTwo" />
          <FormControl.Label htmlFor="custom-checkbox-two">Checkbox two</FormControl.Label>
          <FormControl.Caption id="custom-checkbox-two-caption">Hint text for checkbox two</FormControl.Caption>
        </FormControl>
      </CheckboxGroup>
    </Box>
  )
}

render(FormControlWithCustomInput)

const CustomTextInput = props => <input type="text" {...props} />
const CustomCheckboxInput = props => <input type="checkbox" {...props} />
const FormControlWithCustomInput = () => {
  const [value, setValue] = React.useState('mona lisa')
  const [validationResult, setValidationResult] = React.useState()
  const doesValueContainSpaces = inputValue => /\s/g.test(inputValue)
  const handleInputChange = e => {
    setValue(e.currentTarget.value)
  }

  React.useEffect(() => {
    if (doesValueContainSpaces(value)) {
      setValidationResult('noSpaces')
    } else if (value) {
      setValidationResult('validName')
    }
  }, [value])

  return (
    <Box display="grid" gridGap={3}>
      <FormControl>
        <FormControl.Label htmlFor="custom-input">GitHub handle</FormControl.Label>
        <CustomTextInput
          id="custom-input"
          aria-describedby="custom-input-caption custom-input-validation"
          aria-invalid={validationResult === 'noSpaces'}
          onChange={handleInputChange}
        />
        {validationResult === 'noSpaces' && (
          <FormControl.Validation id="custom-input-validation" variant="error">
            GitHub handles cannot contain spaces
          </FormControl.Validation>
        )}
        {validationResult === 'validName' && (
          <FormControl.Validation id="custom-input-validation" variant="success">
            Valid name
          </FormControl.Validation>
        )}
        <FormControl.Caption id="custom-input-caption">
          With or without "@". For example "monalisa" or "@monalisa"
        </FormControl.Caption>
      </FormControl>

      <CheckboxGroup>
        <CheckboxGroup.Label>Checkboxes</CheckboxGroup.Label>
        <FormControl layout="horizontal">
          <CustomCheckboxInput id="custom-checkbox-one" value="checkOne" />
          <FormControl.Label htmlFor="custom-checkbox-one">Checkbox one</FormControl.Label>
          <FormControl.Caption id="custom-checkbox-one-caption">Hint text for checkbox one</FormControl.Caption>
        </FormControl>
        <FormControl layout="horizontal">
          <CustomCheckboxInput id="custom-checkbox-two" value="checkTwo" />
          <FormControl.Label htmlFor="custom-checkbox-two">Checkbox two</FormControl.Label>
          <FormControl.Caption id="custom-checkbox-two-caption">Hint text for checkbox two</FormControl.Caption>
        </FormControl>
      </CheckboxGroup>
    </Box>
  )
}

render(FormControlWithCustomInput)

With checkbox and radio inputs

<Box display="grid" sx={{gap: 3}}>
  <CheckboxGroup>
    <CheckboxGroup.Label>Checkboxes</CheckboxGroup.Label>
    <FormControl>
      <Checkbox value="checkOne" />
      <FormControl.Label>Checkbox one</FormControl.Label>
    </FormControl>
    <FormControl>
      <Checkbox value="checkTwo" />
      <FormControl.Label>Checkbox two</FormControl.Label>
    </FormControl>
    <FormControl>
      <Checkbox value="checkThree" />
      <FormControl.Label>Checkbox three</FormControl.Label>
    </FormControl>
  </CheckboxGroup>

  <RadioGroup>
    <RadioGroup.Label>Radios</RadioGroup.Label>
    <FormControl>
      <Radio name="radioChoices" value="radioOne" />
      <FormControl.Label>Radio one</FormControl.Label>
    </FormControl>
    <FormControl>
      <Radio name="radioChoices" value="radioTwo" />
      <FormControl.Label>Radio two</FormControl.Label>
    </FormControl>
    <FormControl>
      <Radio name="radioChoices" value="radioThree" />
      <FormControl.Label>Radio three</FormControl.Label>
    </FormControl>
  </RadioGroup>
</Box>

<Box display="grid" sx={{gap: 3}}>
  <CheckboxGroup>
    <CheckboxGroup.Label>Checkboxes</CheckboxGroup.Label>
    <FormControl>
      <Checkbox value="checkOne" />
      <FormControl.Label>Checkbox one</FormControl.Label>
    </FormControl>
    <FormControl>
      <Checkbox value="checkTwo" />
      <FormControl.Label>Checkbox two</FormControl.Label>
    </FormControl>
    <FormControl>
      <Checkbox value="checkThree" />
      <FormControl.Label>Checkbox three</FormControl.Label>
    </FormControl>
  </CheckboxGroup>

  <RadioGroup>
    <RadioGroup.Label>Radios</RadioGroup.Label>
    <FormControl>
      <Radio name="radioChoices" value="radioOne" />
      <FormControl.Label>Radio one</FormControl.Label>
    </FormControl>
    <FormControl>
      <Radio name="radioChoices" value="radioTwo" />
      <FormControl.Label>Radio two</FormControl.Label>
    </FormControl>
    <FormControl>
      <Radio name="radioChoices" value="radioThree" />
      <FormControl.Label>Radio three</FormControl.Label>
    </FormControl>
  </RadioGroup>
</Box>

Required

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

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

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

Disabled

<Box display="grid" gridGap={3}>
  <FormControl disabled>
    <FormControl.Label>Name</FormControl.Label>
    <TextInput />
  </FormControl>

  <FormControl disabled>
    <FormControl.Label>Checkbox option</FormControl.Label>
    <Checkbox />
  </FormControl>
</Box>

<Box display="grid" gridGap={3}>
  <FormControl disabled>
    <FormControl.Label>Name</FormControl.Label>
    <TextInput />
  </FormControl>

  <FormControl disabled>
    <FormControl.Label>Checkbox option</FormControl.Label>
    <Checkbox />
  </FormControl>
</Box>

<Box display="grid" gridGap={3}>
  <FormControl>
    <FormControl.Label visuallyHidden>Name</FormControl.Label>
    <TextInput />
  </FormControl>
  <FormControl>
    <FormControl.Label visuallyHidden>Checkbox option</FormControl.Label>
    <Checkbox />
  </FormControl>
</Box>

<Box display="grid" gridGap={3}>
  <FormControl>
    <FormControl.Label visuallyHidden>Name</FormControl.Label>
    <TextInput />
  </FormControl>
  <FormControl>
    <FormControl.Label visuallyHidden>Checkbox option</FormControl.Label>
    <Checkbox />
  </FormControl>
</Box>

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

<Box display="grid" gridGap={3}>
  <FormControl>
    <FormControl.Label>Name</FormControl.Label>
    <TextInput />
    <FormControl.Caption>Hint: your first name</FormControl.Caption>
  </FormControl>
  <FormControl>
    <FormControl.Label>Option one</FormControl.Label>
    <Checkbox />
    <FormControl.Caption>Hint: the first and only option</FormControl.Caption>
  </FormControl>
</Box>

<Box display="grid" gridGap={3}>
  <FormControl>
    <FormControl.Label>Name</FormControl.Label>
    <TextInput />
    <FormControl.Caption>Hint: your first name</FormControl.Caption>
  </FormControl>
  <FormControl>
    <FormControl.Label>Option one</FormControl.Label>
    <Checkbox />
    <FormControl.Caption>Hint: the first and only option</FormControl.Caption>
  </FormControl>
</Box>

With validation

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

const ValidationExample = () => {
  const [value, setValue] = React.useState('mona lisa')
  const [validationResult, setValidationResult] = React.useState()
  const doesValueContainSpaces = inputValue => /\s/g.test(inputValue)
  const handleInputChange = e => {
    setValue(e.currentTarget.value)
  }

  React.useEffect(() => {
    if (doesValueContainSpaces(value)) {
      setValidationResult('noSpaces')
    } else if (value) {
      setValidationResult('validName')
    }
  }, [value])

  return (
    <FormControl>
      <FormControl.Label>GitHub handle</FormControl.Label>
      <TextInput block value={value} onChange={handleInputChange} />
      {validationResult === 'noSpaces' && (
        <FormControl.Validation variant="error">GitHub handles cannot contain spaces</FormControl.Validation>
      )}
      {validationResult === 'validName' && (
        <FormControl.Validation variant="success">Valid name</FormControl.Validation>
      )}
      <FormControl.Caption>With or without "@". For example "monalisa" or "@monalisa"</FormControl.Caption>
    </FormControl>
  )
}

render(ValidationExample)

const ValidationExample = () => {
  const [value, setValue] = React.useState('mona lisa')
  const [validationResult, setValidationResult] = React.useState()
  const doesValueContainSpaces = inputValue => /\s/g.test(inputValue)
  const handleInputChange = e => {
    setValue(e.currentTarget.value)
  }

  React.useEffect(() => {
    if (doesValueContainSpaces(value)) {
      setValidationResult('noSpaces')
    } else if (value) {
      setValidationResult('validName')
    }
  }, [value])

  return (
    <FormControl>
      <FormControl.Label>GitHub handle</FormControl.Label>
      <TextInput block value={value} onChange={handleInputChange} />
      {validationResult === 'noSpaces' && (
        <FormControl.Validation variant="error">GitHub handles cannot contain spaces</FormControl.Validation>
      )}
      {validationResult === 'validName' && (
        <FormControl.Validation variant="success">Valid name</FormControl.Validation>
      )}
      <FormControl.Caption>With or without "@". For example "monalisa" or "@monalisa"</FormControl.Caption>
    </FormControl>
  )
}

render(ValidationExample)

With a leading visual

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

<>
  <FormControl>
    <FormControl.Label>Option one</FormControl.Label>
    <FormControl.LeadingVisual>
      <MarkGithubIcon />
    </FormControl.LeadingVisual>
    <Checkbox />
  </FormControl>

  <FormControl>
    <FormControl.Label>Option two</FormControl.Label>
    <FormControl.LeadingVisual>
      <MarkGithubIcon />
    </FormControl.LeadingVisual>
    <Checkbox />
    <FormControl.Caption>This one has a caption</FormControl.Caption>
  </FormControl>
</>

<>
  <FormControl>
    <FormControl.Label>Option one</FormControl.Label>
    <FormControl.LeadingVisual>
      <MarkGithubIcon />
    </FormControl.LeadingVisual>
    <Checkbox />
  </FormControl>

  <FormControl>
    <FormControl.Label>Option two</FormControl.Label>
    <FormControl.LeadingVisual>
      <MarkGithubIcon />
    </FormControl.LeadingVisual>
    <Checkbox />
    <FormControl.Caption>This one has a caption</FormControl.Caption>
  </FormControl>
</>

Props

FormControl

Name	Type	Default	Description
children Required	FormControl.Label \| FormControl.Caption \| FormControl.Validation \| Autocomplete \| TextInput \| TextInputWithTokens \| Select
disabled	boolean	false	Whether the control allows user input
id	string	a generated string	The unique identifier for this control. Used to associate the label, validation text, and caption text
required	boolean	false	If true, the user must specify a value for the input before the owning form can be submitted
sx	SystemStyleObject
ref	React.RefObject<HTMLDivElement>		A ref to the element rendered by this component.

FormControl.Label

Name	Type	Default	Description
visuallyHidden	boolean	false	Whether 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'
requiredText	string	'*'	The text to display when the field is required
requiredIndicator	boolean	true	Whether to show or hide the required text in the accessibility tree, the required text is still shown visually.
sx	SystemStyleObject

FormControl.Caption

Name	Type	Default	Description
children	React.ReactNode		The content (usually just text) that is rendered to give contextual info about the field
sx	SystemStyleObject

FormControl.Validation

Name	Type	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
sx	SystemStyleObject

FormControl.LeadingVisual

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

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.