@primer/react-brand/docs/forms/TextInput/index.md

Primer Brand is a GitHub's design system for creating React-based marketing websites and digital experiences.

---
title: Text input
description: Use the text input component for single-line text field.
keywords: ['input', 'form']
figma: 'https://www.figma.com/file/BJ95AjraesmRCWsKA013GS/Primer-Brand?node-id=1377%3A30676'
source: https://github.com/primer/brand/blob/main/packages/react/src/forms/TextInput/TextInput.tsx
storybook: '/brand/storybook/?path=/story/components-forms-textinput--playground'
---

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

## Examples

### Default

```jsx
<TextInput aria-label="Demo TextInput" />
```

### Variants

```jsx
<div
  style={{
    display: 'grid',
    gridTemplateColumns: 'repeat(auto-fit, minmax(min(100%, 290px), 1fr))',
    gap: '20px',
    maxWidth: '600px',
    width: '100%',
  }}
>
  <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" autoComplete="email" placeholder="mona@github.com" />
  </FormControl>
  <FormControl fullWidth>
    <FormControl.Label>Password</FormControl.Label>
    <TextInput type="password" autoComplete="current-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" autoComplete="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" autoComplete="url" value="https://github.com" />
  </FormControl>
</div>
```

### Use with `FormControl`

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

[See FormControl for additional usage examples.](../FormControl/index.md)

```jsx
<FormControl>
  <FormControl.Label>First name</FormControl.Label>
  <TextInput autoComplete="given-name" />
</FormControl>
```

### Placeholder

```jsx
<FormControl fullWidth>
  <FormControl.Label>First name</FormControl.Label>
  <TextInput placeholder="Mona" autoComplete="given-name" />
</FormControl>
```

### Autocomplete

The `autoComplete` prop should be provided wherever possible to allow browsers to autofill the input field. See MDN for [a complete list of autocomplete values](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete).

```jsx
<FormControl fullWidth>
  <FormControl.Label>First name</FormControl.Label>
  <TextInput autoComplete="given-name" />
</FormControl>
```

### Validation

```jsx
<div style={{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>
</div>
```

### Full width

```jsx
<TextInput fullWidth aria-label="Full width TextInput" />
```

### Sizes

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

```jsx
<div style={{display: 'inline-grid', gap: 3}}>
  <TextInput size="medium" aria-label="Medium TextInput" />

  <TextInput size="large" aria-label="Large TextInput" />
</div>
```

### Required

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

```jsx
<TextInput required aria-label="Required TextInput" />
```

### Using `refs`

`TextInput` inputs can be used in [uncontrolled mode](https://reactjs.org/docs/uncontrolled-components.html) by forwarding a `ref` to the underlying element.

```jsx filename="noinline"
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}>
      <div
        style={{
          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>
      </div>
    </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 div.  |
| `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](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) accepted by the `<input>` element.

## Related components

- [FormControl](../FormControl/index.md)
- [Select](../Select/index.md)
- [TextInput](./index.md)