Form control

Use the form control component to display form inputs alongside labels, validation and more.

Experimental
Not reviewed for accessibility

On this page

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.

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

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

Alternative inputs

<Stack direction="vertical" gap="spacious">
  {/* Select */}
  <FormControl>
    <FormControl.Label>Select</FormControl.Label>
    <Select defaultValue="">
      <Select.Option value="" disabled>
        Select a handle
      </Select.Option>
      <Select.Option value="mona">Monalisa</Select.Option>
      <Select.Option value="hubot">Hubot</Select.Option>
    </Select>
  </FormControl>
  {/* Checkbox */}
  <FormControl>
    <FormControl.Label>
      Checkbox <FormControl.Hint>With an optional message</FormControl.Hint>
    </FormControl.Label>
    <Checkbox />
  </FormControl>
  {/* Radio */}
  <FormControl>
    <FormControl.Label>
      Radio <FormControl.Hint>With an optional message</FormControl.Hint>
    </FormControl.Label>
    <Radio />
  </FormControl>
  {/* Textarea */}
  <FormControl fullWidth>
    <FormControl.Label>Textarea</FormControl.Label>
    <Textarea />
  </FormControl>
</Stack>

<Stack direction="vertical" gap="spacious">
  {/* Select */}
  <FormControl>
    <FormControl.Label>Select</FormControl.Label>
    <Select defaultValue="">
      <Select.Option value="" disabled>
        Select a handle
      </Select.Option>
      <Select.Option value="mona">Monalisa</Select.Option>
      <Select.Option value="hubot">Hubot</Select.Option>
    </Select>
  </FormControl>
  {/* Checkbox */}
  <FormControl>
    <FormControl.Label>
      Checkbox <FormControl.Hint>With an optional message</FormControl.Hint>
    </FormControl.Label>
    <Checkbox />
  </FormControl>
  {/* Radio */}
  <FormControl>
    <FormControl.Label>
      Radio <FormControl.Hint>With an optional message</FormControl.Hint>
    </FormControl.Label>
    <Radio />
  </FormControl>
  {/* Textarea */}
  <FormControl fullWidth>
    <FormControl.Label>Textarea</FormControl.Label>
    <Textarea />
  </FormControl>
</Stack>

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:

<form>
  <Container
    sx={{
      alignItems: 'center',
      display: 'grid',
      gap: 16,
      margin: '0 auto ',
      maxWidth: 600,
      paddingBottom: 3,
    }}
  >
    <Container
      sx={{
        display: 'grid',
        gridTemplateColumns: '0.5fr 1fr 1fr',
        gap: 16,
      }}
    >
      <FormControl fullWidth>
        <FormControl.Label>Title</FormControl.Label>
        <Select defaultValue="">
          <Select.Option value="" disabled>
            Title
          </Select.Option>
          <Select.Option value="miss">Miss</Select.Option>
          <Select.Option value="mr">Mr</Select.Option>
          <Select.Option value="mrs">Mrs</Select.Option>
          <Select.Option value="mx">Mx</Select.Option>
        </Select>
      </FormControl>
      <FormControl fullWidth required>
        <FormControl.Label>First name</FormControl.Label>
        <TextInput required />
      </FormControl>
      <FormControl fullWidth required>
        <FormControl.Label>Last name</FormControl.Label>
        <TextInput required />
      </FormControl>
    </Container>

    <FormControl fullWidth required>
      <FormControl.Label>Enterprise name</FormControl.Label>
      <TextInput required />
    </FormControl>

    <FormControl fullWidth required>
      <FormControl.Label>Enterprise URL</FormControl.Label>
      <TextInput leadingText="github.com/" required />
    </FormControl>

    <FormControl fullWidth required>
      <FormControl.Label>Country</FormControl.Label>
      <Select defaultValue="">
        <Select.Option value="" disabled>
          Country
        </Select.Option>
        <Select.Option value="us">United States of America</Select.Option>
        <Select.Option value="uk">United Kingdom</Select.Option>
      </Select>
    </FormControl>
    <FormControl hasBorder required>
      <FormControl.Label>
        Contact me about GitHub Enterprise Server{' '}
        <FormControl.Hint>
          <Text size="200" variant="muted">
            I&apos;m interested in learning more about{' '}
            <InlineLink
              size="200"
              href="https://github.com/enterprise"
              target="_blank"
            >
              GitHub Enterprise Server
            </InlineLink>{' '}
            and would like to be contacted by GitHub’s sales team.
          </Text>
        </FormControl.Hint>
      </FormControl.Label>
      <Checkbox />
    </FormControl>
    <Container
      sx={{
        borderWidth: 1,
        borderStyle: 'solid',
        borderColor: 'var(--brand-control-color-border-default)',
        backgroundColor: 'var(--brand-color-canvas-inset)',
        height: 150,
        width: '100%',
        borderRadius: 6,
        display: 'flex',
        justifyContent: 'center',
        alignItems: 'center',
      }}
    >
      <Text size="200" variant="muted">
        Captcha
      </Text>
    </Container>
    <FormControl required>
      <FormControl.Label>
        <Text size="200" variant="muted">
          I hereby accept the{' '}
          <InlineLink
            size="200"
            href="https://github.com/customer-terms"
            target="_blank"
          >
            GitHub Customer Agreement
          </InlineLink>{' '}
          on behalf of my organization and confirm that I have the authority to
          do so. For more information about GitHub&apos;s privacy practices, see
          the{' '}
          <InlineLink
            size="200"
            href="https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement"
            target="_blank"
          >
            GitHub Privacy Statement.
          </InlineLink>{' '}
        </Text>
      </FormControl.Label>

      <Checkbox />
    </FormControl>
    <Container
      sx={{
        justifyContent: 'end',
        display: 'inline-grid',
        gap: 16,
      }}
    >
      <Button variant="primary" type="submit">
        Start trial
      </Button>
    </Container>
  </Container>
</form>

<form>
  <Container
    sx={{
      alignItems: 'center',
      display: 'grid',
      gap: 16,
      margin: '0 auto ',
      maxWidth: 600,
      paddingBottom: 3,
    }}
  >
    <Container
      sx={{
        display: 'grid',
        gridTemplateColumns: '0.5fr 1fr 1fr',
        gap: 16,
      }}
    >
      <FormControl fullWidth>
        <FormControl.Label>Title</FormControl.Label>
        <Select defaultValue="">
          <Select.Option value="" disabled>
            Title
          </Select.Option>
          <Select.Option value="miss">Miss</Select.Option>
          <Select.Option value="mr">Mr</Select.Option>
          <Select.Option value="mrs">Mrs</Select.Option>
          <Select.Option value="mx">Mx</Select.Option>
        </Select>
      </FormControl>
      <FormControl fullWidth required>
        <FormControl.Label>First name</FormControl.Label>
        <TextInput required />
      </FormControl>
      <FormControl fullWidth required>
        <FormControl.Label>Last name</FormControl.Label>
        <TextInput required />
      </FormControl>
    </Container>

    <FormControl fullWidth required>
      <FormControl.Label>Enterprise name</FormControl.Label>
      <TextInput required />
    </FormControl>

    <FormControl fullWidth required>
      <FormControl.Label>Enterprise URL</FormControl.Label>
      <TextInput leadingText="github.com/" required />
    </FormControl>

    <FormControl fullWidth required>
      <FormControl.Label>Country</FormControl.Label>
      <Select defaultValue="">
        <Select.Option value="" disabled>
          Country
        </Select.Option>
        <Select.Option value="us">United States of America</Select.Option>
        <Select.Option value="uk">United Kingdom</Select.Option>
      </Select>
    </FormControl>
    <FormControl hasBorder required>
      <FormControl.Label>
        Contact me about GitHub Enterprise Server{' '}
        <FormControl.Hint>
          <Text size="200" variant="muted">
            I&apos;m interested in learning more about{' '}
            <InlineLink
              size="200"
              href="https://github.com/enterprise"
              target="_blank"
            >
              GitHub Enterprise Server
            </InlineLink>{' '}
            and would like to be contacted by GitHub’s sales team.
          </Text>
        </FormControl.Hint>
      </FormControl.Label>
      <Checkbox />
    </FormControl>
    <Container
      sx={{
        borderWidth: 1,
        borderStyle: 'solid',
        borderColor: 'var(--brand-control-color-border-default)',
        backgroundColor: 'var(--brand-color-canvas-inset)',
        height: 150,
        width: '100%',
        borderRadius: 6,
        display: 'flex',
        justifyContent: 'center',
        alignItems: 'center',
      }}
    >
      <Text size="200" variant="muted">
        Captcha
      </Text>
    </Container>
    <FormControl required>
      <FormControl.Label>
        <Text size="200" variant="muted">
          I hereby accept the{' '}
          <InlineLink
            size="200"
            href="https://github.com/customer-terms"
            target="_blank"
          >
            GitHub Customer Agreement
          </InlineLink>{' '}
          on behalf of my organization and confirm that I have the authority to
          do so. For more information about GitHub&apos;s privacy practices, see
          the{' '}
          <InlineLink
            size="200"
            href="https://docs.github.com/en/site-policy/privacy-policies/github-privacy-statement"
            target="_blank"
          >
            GitHub Privacy Statement.
          </InlineLink>{' '}
        </Text>
      </FormControl.Label>

      <Checkbox />
    </FormControl>
    <Container
      sx={{
        justifyContent: 'end',
        display: 'inline-grid',
        gap: 16,
      }}
    >
      <Button variant="primary" type="submit">
        Start trial
      </Button>
    </Container>
  </Container>
</form>

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

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

Validation

The following example demonstrates declarative form validation in controlled mode.

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

const App = () => {
  const [value, setValue] = React.useState()
  const [validationState, setValidationState] = React.useState()

  React.useEffect(() => {
    const defaultHandle = 'mona lisa'
    setValue(defaultHandle)
    validate(defaultHandle)
  }, [])

  const validate = (inputValue) => {
    if (/\s/g.test(inputValue)) {
      setValidationState('error')
    } else {
      setValidationState('success')
    }
  }

  const handleChange = (event) => {
    event.preventDefault()
    if (!event.target.value) {
      setValue(undefined)
      setValidationState(undefined)
      return
    }
    setValue(event.target.value)
    validate(event.target.value)
  }

  return (
    <FormControl validationStatus={validationState}>
      <FormControl.Label>GitHub handle</FormControl.Label>
      <TextInput onChange={handleChange} value={value} fullWidth />
      {validationState && validationState === 'error' && (
        <FormControl.Validation>
          GitHub handles cannot contain spaces.{' '}
          {value && `Did you mean "${value.replaceAll(' ', '')}"`}
        </FormControl.Validation>
      )}
      {validationState && validationState === 'success' && (
        <FormControl.Validation>Valid name</FormControl.Validation>
      )}
    </FormControl>
  )
}

render(App)

const App = () => {
  const [value, setValue] = React.useState()
  const [validationState, setValidationState] = React.useState()

  React.useEffect(() => {
    const defaultHandle = 'mona lisa'
    setValue(defaultHandle)
    validate(defaultHandle)
  }, [])

  const validate = (inputValue) => {
    if (/\s/g.test(inputValue)) {
      setValidationState('error')
    } else {
      setValidationState('success')
    }
  }

  const handleChange = (event) => {
    event.preventDefault()
    if (!event.target.value) {
      setValue(undefined)
      setValidationState(undefined)
      return
    }
    setValue(event.target.value)
    validate(event.target.value)
  }

  return (
    <FormControl validationStatus={validationState}>
      <FormControl.Label>GitHub handle</FormControl.Label>
      <TextInput onChange={handleChange} value={value} fullWidth />
      {validationState && validationState === 'error' && (
        <FormControl.Validation>
          GitHub handles cannot contain spaces.{' '}
          {value && `Did you mean "${value.replaceAll(' ', '')}"`}
        </FormControl.Validation>
      )}
      {validationState && validationState === 'success' && (
        <FormControl.Validation>Valid name</FormControl.Validation>
      )}
    </FormControl>
  )
}

render(App)

Hint

<FormControl>
  <FormControl.Label>Select</FormControl.Label>
  <Select>
    <Select.Option value="" disabled>
      Select a handle
    </Select.Option>
    <Select.Option value="mona">Monalisa</Select.Option>
    <Select.Option value="hubot">Hubot</Select.Option>
  </Select>
  <FormControl.Hint>With an optional message</FormControl.Hint>
</FormControl>

<FormControl>
  <FormControl.Label>Select</FormControl.Label>
  <Select>
    <Select.Option value="" disabled>
      Select a handle
    </Select.Option>
    <Select.Option value="mona">Monalisa</Select.Option>
    <Select.Option value="hubot">Hubot</Select.Option>
  </Select>
  <FormControl.Hint>With an optional message</FormControl.Hint>
</FormControl>

Full width

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

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

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

Sizes

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

<Container sx={{display: 'grid', gap: 3}}>
  <FormControl size="medium">
    <FormControl.Label>Medium</FormControl.Label>
    <TextInput />
  </FormControl>

  <FormControl size="large">
    <FormControl.Label>Large</FormControl.Label>
    <TextInput />
  </FormControl>
</Container>

<Container sx={{display: 'grid', gap: 3}}>
  <FormControl size="medium">
    <FormControl.Label>Medium</FormControl.Label>
    <TextInput />
  </FormControl>

  <FormControl size="large">
    <FormControl.Label>Large</FormControl.Label>
    <TextInput />
  </FormControl>
</Container>

Required

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

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

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

Using `refs`

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

const App = () => {
  const inputRef = React.useRef(null)

  const handleSubmit = (e) => {
    e.preventDefault()
    if (inputRef.current) {
      alert(`Name: ${inputRef.current.value}`)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <Container
        sx={{
          display: 'grid',
          gap: 'var(--base-size-16)',
          maxWidth: 400,
          marginX: 'auto',
        }}
      >
        <FormControl fullWidth>
          <FormControl.Label>Name</FormControl.Label>
          <TextInput ref={inputRef} defaultValue="Mona Lisa" />
        </FormControl>
        <Button type="submit" variant="primary">
          Submit
        </Button>
      </Container>
    </form>
  )
}

render(App)

const App = () => {
  const inputRef = React.useRef(null)

  const handleSubmit = (e) => {
    e.preventDefault()
    if (inputRef.current) {
      alert(`Name: ${inputRef.current.value}`)
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <Container
        sx={{
          display: 'grid',
          gap: 'var(--base-size-16)',
          maxWidth: 400,
          marginX: 'auto',
        }}
      >
        <FormControl fullWidth>
          <FormControl.Label>Name</FormControl.Label>
          <TextInput ref={inputRef} defaultValue="Mona Lisa" />
        </FormControl>
        <Button type="submit" variant="primary">
          Submit
        </Button>
      </Container>
    </form>
  )
}

render(App)

Component props

FormControl Required

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

Name	Type	Description
`children`	`'FormControl.Label'` `'Checkbox'` `'Select'` `'TextInput'` `'FormControl.Validation'` `'React.ReactElement'` ,	Valid child nodes
`className`	`string`	Sets a custom class
`id`	`string`	Sets a custom id
`fullWidth`	`boolean`	Stretches elements visually to the edges of its parent container.
`ref`	`React.RefObject`	Forward 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.

Name	Type	Default	Description
`children`	`string`		Label text
`className`	`string`		Applies a custom class
`id`	`string`		Sets a custom id
`ref`	`React.RefObject`		Forward a Ref to the underlying DOM node
`size`	`'medium'` `'large'`	`'medium'`	Set visual dimensions
`visuallyHidden`	`boolean`	`false`	Hide 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

Name	Type	Description
`children`	`string`	Validation message
`className`	`string`	FormControl.Validation custom class
`id`	`string`	Sets a custom id
`ref`	`React.RefObject`	Forward a Ref to the underlying DOM node
`validationStatus`	`'error'` `'success'`	Applies a visual and semantic validation state to the underlying elements

Primer Design System

Site navigation