InputField

The InputField component is used to render a labelled text input and, optionally, associated validation text and hint text.

Deprecated
Not reviewed for accessibility

On this page

Deprecation

Use FormControl instead.

Examples

Basic

<InputField>
  <InputField.Label>Name</InputField.Label>
  <TextInput />
</InputField>

<InputField>
  <InputField.Label>Name</InputField.Label>
  <TextInput />
</InputField>

Required

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

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

Disabled

<InputField disabled>
  <InputField.Label>Name</InputField.Label>
  <TextInput />
</InputField>

<InputField disabled>
  <InputField.Label>Name</InputField.Label>
  <TextInput />
</InputField>

Using different input components

const TextInputWithTokensExample = () => {
  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="flex"
      flexDirection="column"
      sx={{
        '> * + *': {
          marginTop: 4,
        },
      }}
    >
      <InputField>
        <InputField.Label>TextInputWithTokens</InputField.Label>
        <TextInputWithTokens onTokenRemove={onTokenRemove} tokens={tokens} />
      </InputField>
      <InputField>
        <InputField.Label>Autocomplete</InputField.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>
      </InputField>
      <InputField>
        <InputField.Label>Select</InputField.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>
      </InputField>
    </Box>
  )
}

render(TextInputWithTokensExample)

const TextInputWithTokensExample = () => {
  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="flex"
      flexDirection="column"
      sx={{
        '> * + *': {
          marginTop: 4,
        },
      }}
    >
      <InputField>
        <InputField.Label>TextInputWithTokens</InputField.Label>
        <TextInputWithTokens onTokenRemove={onTokenRemove} tokens={tokens} />
      </InputField>
      <InputField>
        <InputField.Label>Autocomplete</InputField.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>
      </InputField>
      <InputField>
        <InputField.Label>Select</InputField.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>
      </InputField>
    </Box>
  )
}

render(TextInputWithTokensExample)

Every input must have a corresponding label to be accessible to assistive technology. That's why you'd use InputField instead of using TextInput directly.

InputField also provides an interface for showing a hint text caption and a validation message, and associating those with the input for assistive technology.

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

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

With a caption

<InputField>
  <InputField.Label>Name</InputField.Label>
  <TextInput />
  <InputField.Caption>Hint: your first name</InputField.Caption>
</InputField>

<InputField>
  <InputField.Label>Name</InputField.Label>
  <TextInput />
  <InputField.Caption>Hint: your first name</InputField.Caption>
</InputField>

With validation

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 (
    <InputField
      validationMap={{
        noSpaces: 'error',
        validName: 'success',
      }}
      validationResult={validationResult}
    >
      <InputField.Label>GitHub handle</InputField.Label>
      <TextInput block value={value} onChange={handleInputChange} />
      <InputField.Validation validationKey="noSpaces">GitHub handles cannot contain spaces</InputField.Validation>
      <InputField.Validation validationKey="validName">Valid name</InputField.Validation>
      <InputField.Caption>With or without "@". For example "monalisa" or "@monalisa"</InputField.Caption>
    </InputField>
  )
}

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 (
    <InputField
      validationMap={{
        noSpaces: 'error',
        validName: 'success',
      }}
      validationResult={validationResult}
    >
      <InputField.Label>GitHub handle</InputField.Label>
      <TextInput block value={value} onChange={handleInputChange} />
      <InputField.Validation validationKey="noSpaces">GitHub handles cannot contain spaces</InputField.Validation>
      <InputField.Validation validationKey="validName">Valid name</InputField.Validation>
      <InputField.Caption>With or without "@". For example "monalisa" or "@monalisa"</InputField.Caption>
    </InputField>
  )
}

render(ValidationExample)

Props

InputField

The container that handles the layout and passes the relevant IDs and ARIA attributes it's children.

Name	Type	Default	Description
children Required	InputField.Label \| InputField.Caption \| InputField.Validation \| Autocomplete \| TextInput \| TextInputWithTokens \| Select
disabled	boolean	false	Whether the field is ready for user input
id	string	a generated string	The unique identifier for this field. Used to associate the label, validation text, and caption text
required	boolean	false	Whether the field is ready for user input
validationMap	Record<string, 'error'\|'success'>		A map of validation statuses and their associated validation keys. When one of the validation keys is passed to the `validationResult` prop, the associated validation message will be rendered in the correct style
validationResult	string		The key of the validation message to show

InputField.Label

A InputField.Label must be passed for the field to be accessible to assistive technology, but it may be visually hidden.

Name	Type	Default	Description
boolean	InputField.Label \| InputField.Caption \| InputField.Validation \| Autocomplete \| TextInput \| TextInputWithTokens	false	Whether the label should be visually hidden

InputField.Caption

InputField.Caption may be used to render hint text for fields that require additional context.

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

InputField.Validation

InputField.Validation may be used to render contextual validation information if the field was flagged during validation.

Name	Type	Default	Description
children	React.ReactNode		The content (usually just text) that is rendered to give contextual info about the validation result for the field
validationKey	string		The key of the property from `InputField` that corresponds to this validation message. When `InputField`'s `validationResult` prop matches `InputField.Validation`'s `validationKey` prop, this message is shown.

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.