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) => {

Primer Design System

Site navigation