Main navigation navigation

Site navigation

Text input

Use the text input component for single-line text field.

Experimental
Not reviewed for accessibility

On this page

import {TextInput} from '@primer/react-brand'

Examples

Default

<TextInput />

<TextInput />

Variants

<Container
  sx={{
    display: 'grid',
    gridTemplateColumns: '1fr 1fr',
    gridTemplateRows: 'repeat(2,minmax(40px,auto))',
    gridGap: 4,
  }}
>
  <FormControl fullWidth>
    <FormControl.Label>Text (default)</FormControl.Label>
    <TextInput type="text" placeholder="alphanumeric" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Number</FormControl.Label>
    <TextInput type="number" placeholder="123" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Email</FormControl.Label>
    <TextInput type="email" placeholder="mona@github.com" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Password</FormControl.Label>
    <TextInput type="password" value="monalisa" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Month</FormControl.Label>
    <TextInput type="month" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Telephone</FormControl.Label>
    <TextInput type="tel" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Time</FormControl.Label>
    <TextInput type="time" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Date</FormControl.Label>
    <TextInput type="date" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Date (local)</FormControl.Label>
    <TextInput type="datetime-local" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>URL</FormControl.Label>
    <TextInput type="url" value="https://github.com" />
  </FormControl>
</Container>

<Container
  sx={{
    display: 'grid',
    gridTemplateColumns: '1fr 1fr',
    gridTemplateRows: 'repeat(2,minmax(40px,auto))',
    gridGap: 4,
  }}
>
  <FormControl fullWidth>
    <FormControl.Label>Text (default)</FormControl.Label>
    <TextInput type="text" placeholder="alphanumeric" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Number</FormControl.Label>
    <TextInput type="number" placeholder="123" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Email</FormControl.Label>
    <TextInput type="email" placeholder="mona@github.com" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Password</FormControl.Label>
    <TextInput type="password" value="monalisa" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Month</FormControl.Label>
    <TextInput type="month" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Telephone</FormControl.Label>
    <TextInput type="tel" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Time</FormControl.Label>
    <TextInput type="time" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Date</FormControl.Label>
    <TextInput type="date" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Date (local)</FormControl.Label>
    <TextInput type="datetime-local" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>URL</FormControl.Label>
    <TextInput type="url" value="https://github.com" />
  </FormControl>
</Container>

Placeholder

<TextInput placeholder="First name" />

<TextInput placeholder="First name" />

Use with `FormControl`

Use TextInput alongside FormControl to ensure the control always has a corresponding form label.

See FormControl for additional usage examples.

<FormControl>
  <FormControl.Label>First name</FormControl.Label>
  <TextInput />
</FormControl>

<FormControl>
  <FormControl.Label>First name</FormControl.Label>
  <TextInput />
</FormControl>

Validation

<Container sx={{display: 'inline-grid', gap: 3}}>
  <FormControl validationStatus="error">
    <FormControl.Label>Error</FormControl.Label>
    <TextInput />
    <FormControl.Validation>This is an error message</FormControl.Validation>
  </FormControl>
  <FormControl validationStatus="success">
    <FormControl.Label>Success</FormControl.Label>
    <TextInput />
    <FormControl.Validation>This is a success message</FormControl.Validation>
  </FormControl>
</Container>

<Container sx={{display: 'inline-grid', gap: 3}}>
  <FormControl validationStatus="error">
    <FormControl.Label>Error</FormControl.Label>
    <TextInput />
    <FormControl.Validation>This is an error message</FormControl.Validation>
  </FormControl>
  <FormControl validationStatus="success">
    <FormControl.Label>Success</FormControl.Label>
    <TextInput />
    <FormControl.Validation>This is a success message</FormControl.Validation>
  </FormControl>
</Container>

Full width

<TextInput fullWidth />

<TextInput fullWidth />

Sizes

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

<Container sx={{display: 'inline-grid', gap: 3}}>
  <TextInput size="medium" />

  <TextInput size="large" />
</Container>

<Container sx={{display: 'inline-grid', gap: 3}}>
  <TextInput size="medium" />

  <TextInput size="large" />
</Container>

Required

Pass the required prop to ensure that the input field must be filled out before submitting the form.

<TextInput required />

<TextInput required />

Using `refs`

TextInput 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.value) {
      alert(`Enter a value and try again.`)
      return
    }

    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} />
        </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.value) {
      alert(`Enter a value and try again.`)
      return
    }

    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} />
        </FormControl>
        <Button type="submit" variant="primary">
          Submit
        </Button>
      </Container>
    </form>
  )
}

render(App)

Component props

TextInput provides a React alternative to the native HTML <input> in single-line mode.

The component API supports all standard HTML attribute props, while providing some additional behaviour as described below.

TextInput Required

Name	Type	Default	Description
`children`	`'TextInput.Option'` `'TextInput.OptGroup'` ,		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 the input
`type`	`'text'` `'number'` `'email'` `'password'` `'search'` `'tel'` `'url'` `'date'` `'time'` `'datetime-local'`	`text`	Alternative text inputs
`validationStatus`	`'error'` `'success'`		Applies visual and semantic state to the underlying elements

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