TextInput

TextInput is used to set a value that is a single line of text.

Page navigation navigation

React

readyNot reviewed for a11y

Storybook|Source

Rails

readyNot reviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

Use a TextInput to allow users to input short free-form text. It may also be used as a number input when type="number" is passed to the component.

React examples

Default

Label

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

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

Required

Label*

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

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

Custom size

Adjust input size based on context; use smaller sizes in compact spaces, larger sizes in open spaces or feels out of proportion with adjacent large elements.

Small

Medium (default)

Large

<Stack direction="horizontal">
  <FormControl>
    <FormControl.Label>Small</FormControl.Label>
    <TextInput size="small" />
  </FormControl>
  <FormControl>
    <FormControl.Label>Medium (default)</FormControl.Label>
    <TextInput />
  </FormControl>
  <FormControl>
    <FormControl.Label>Large</FormControl.Label>
    <TextInput size="large" />
  </FormControl>
</Stack>

<Stack direction="horizontal">
  <FormControl>
    <FormControl.Label>Small</FormControl.Label>
    <TextInput size="small" />
  </FormControl>
  <FormControl>
    <FormControl.Label>Medium (default)</FormControl.Label>
    <TextInput />
  </FormControl>
  <FormControl>
    <FormControl.Label>Large</FormControl.Label>
    <TextInput size="large" />
  </FormControl>
</Stack>

Monospace value

Use a monospace font for code-related inputs, like configuration tokens.

Label

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput monospace value="Value" />
</FormControl>

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput monospace value="Value" />
</FormControl>

In a loading state

When loading, the spinner replaces a visual without shifting layout. Control which side displays the loading indicator as needed.

The TextInput component has internal logic to decide which visual to replace, but it can be overridden and explicitly set to show at the start or end of the input.

Default spinner position

No leading/trailing visualLoading

Leading visual

Trailing visualLoading

Both visuals

Overridden spinner position

Leading

Trailing

<Stack gap="spacious">
  <div>
    <div>Default spinner position</div>
    <Stack>
      <FormControl>
        <FormControl.Label>No leading/trailing visual</FormControl.Label>
        <TextInput loading />
      </FormControl>
      <FormControl>
        <FormControl.Label>Leading visual</FormControl.Label>
        <TextInput leadingVisual={CalendarIcon} loading />
      </FormControl>
      <FormControl>
        <FormControl.Label>Trailing visual</FormControl.Label>
        <TextInput trailingVisual={CalendarIcon} loading />
      </FormControl>
      <FormControl>
        <FormControl.Label>Both visuals</FormControl.Label>
        <TextInput leadingVisual={CalendarIcon} trailingVisual={CalendarIcon} loading />
      </FormControl>
    </Stack>
  </div>
  <div>
    <div>Overridden spinner position</div>
    <Stack>
      <FormControl>
        <FormControl.Label>Leading</FormControl.Label>
        <TextInput leadingVisual={CalendarIcon} trailingVisual={CalendarIcon} loading loaderPosition="leading" />
      </FormControl>
      <FormControl>
        <FormControl.Label>Trailing</FormControl.Label>
        <TextInput leadingVisual={CalendarIcon} trailingVisual={CalendarIcon} loading loaderPosition="trailing" />
      </FormControl>
    </Stack>
  </div>
</Stack>

<Stack gap="spacious">
  <div>
    <div>Default spinner position</div>
    <Stack>
      <FormControl>
        <FormControl.Label>No leading/trailing visual</FormControl.Label>
        <TextInput loading />
      </FormControl>
      <FormControl>
        <FormControl.Label>Leading visual</FormControl.Label>
        <TextInput leadingVisual={CalendarIcon} loading />
      </FormControl>
      <FormControl>
        <FormControl.Label>Trailing visual</FormControl.Label>
        <TextInput trailingVisual={CalendarIcon} loading />
      </FormControl>
      <FormControl>
        <FormControl.Label>Both visuals</FormControl.Label>
        <TextInput leadingVisual={CalendarIcon} trailingVisual={CalendarIcon} loading />
      </FormControl>
    </Stack>
  </div>
  <div>
    <div>Overridden spinner position</div>
    <Stack>
      <FormControl>
        <FormControl.Label>Leading</FormControl.Label>
        <TextInput leadingVisual={CalendarIcon} trailingVisual={CalendarIcon} loading loaderPosition="leading" />
      </FormControl>
      <FormControl>
        <FormControl.Label>Trailing</FormControl.Label>
        <TextInput leadingVisual={CalendarIcon} trailingVisual={CalendarIcon} loading loaderPosition="trailing" />
      </FormControl>
    </Stack>
  </div>
</Stack>

With a caption

LabelThis is a caption

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput />
  <FormControl.Caption>This is a caption</FormControl.Caption>
</FormControl>

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput />
  <FormControl.Caption>This is a caption</FormControl.Caption>
</FormControl>

With a validation message

Label

Something went wrong

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput />
  <FormControl.Validation variant="error">Something went wrong</FormControl.Validation>
</FormControl>

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput />
  <FormControl.Validation variant="error">Something went wrong</FormControl.Validation>
</FormControl>

With a leading visual

Leading and trailing visuals, typically icons, clarify input purpose. For context, prefer icons but use text (e.g., “$” or “%”) if helpful.

Avoid overwhelming the TextInput by using both a leading and trailing visual. If you're trying to provide more context about the input, consider using text in the input caption.

Label

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput leadingVisual={CheckIcon} />
</FormControl>

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput leadingVisual={CheckIcon} />
</FormControl>

With a trailing visual

Label

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput trailingVisual={CheckIcon} />
</FormControl>

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput trailingVisual={CheckIcon} />
</FormControl>

With a trailing action

Use a trailing action button (e.g., clear button) without a label when possible. Avoid using it alongside a trailing visual.

Label

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput
    trailingAction={
      <TextInput.Action
        onClick={() => {
          alert('Fake clear the input')
        }}
        icon={XCircleFillIcon}
        aria-label="Clear input"
      />
    }
  />
</FormControl>

<FormControl>
  <FormControl.Label>Label</FormControl.Label>
  <TextInput
    trailingAction={
      <TextInput.Action
        onClick={() => {
          alert('Fake clear the input')
        }}
        icon={XCircleFillIcon}
        aria-label="Clear input"
      />
    }
  />
</FormControl>

Name	Required	Description
aria-label		`string` Gives the input an accessible name.
autoComplete		`string` Allows input to autofill based on value given.
block		`boolean` Creates a full-width input element
contrast		`boolean` Changes background color to a higher contrast color
size		`'small' \| 'medium' \| 'large'` Creates a smaller or larger input than the default.
loading		`boolean` Whether to show a loading indicator in the input
loaderPosition		`'auto' \| 'leading' \| 'trailing'` <div>Which position to render the loading indicator</div> <ul> <li> 'auto' (default): at the end of the input, unless a `leadingVisual` is passed. Then, it will render at the beginning </li> <li>'leading': at the beginning of the input</li> <li>'trailing': at the end of the input</li> </ul>
loaderText		`string` Text for screen readers to convey the loading state, should be descriptive and explain what is loading. This prop should only be used if there is visible context explaining what is loading, to ensure that context is provided to all users.
leadingVisual		`string \| React.ComponentType` Visual positioned on the left edge inside the input
monospace		`boolean` Shows input in monospace font
trailingVisual		`string \| React.ComponentType` Visual positioned on the right edge inside the input
trailingAction		`React.ReactElement<HTMLProps<HTMLButtonElement>>` A visual that renders inside the input after the typing area
validationStatus		`'error' \| 'success'` Style the input to match the status
variant Deprecated		`'small' \| 'medium' \| 'large'` (Use size) Creates a smaller or larger input than the default.
width Deprecated		`string \| number \| Array<string \| number>` (Use sx prop) Set the width of the input
maxWidth Deprecated		`string \| number \| Array<string \| number>` (Use sx prop) Set the maximum width of the input
minWidth Deprecated		`string \| number \| Array<string \| number>` (Use sx prop) Set the minimum width of the input
icon Deprecated		`React.ComponentType` (Use leadingVisual or trailingVisual) An Octicon React component. To be used inside of input. Positioned on the left edge.
sx		`SystemStyleObject`
ref		`React.RefObject<HTMLInputElement>`

TextInput.Action

Name	Required	Description
aria-label		`string` Text that appears in a tooltip. If an icon is passed, this is also used as the label used by assistive technologies.
tooltipDirection		`'n' \| 'ne' \| 'e' \| 'se' \| 's' \| 'sw' \| 'w' \| 'nw'` Sets where the tooltip renders in relation to the target.
icon		`React.FunctionComponent` The icon to render inside the button
variant Deprecated		`'default' \| 'primary' \| 'invisible' \| 'danger'` (Deprecated so that only the 'invisible' variant is used) Determine's the styles on a button
ref		`React.RefObject<HTMLButtonElement>`
as		`React.ElementType`
sx		`SystemStyleObject`