Primer/React

Design

Interface guidelines Octicons Presentations Command line Mobile Desktop

Build

CSS React React Brand ViewComponents

Contribute About

On this page

TextInput

Use text input as a form component to add default styling to the native text input.

Alpha
Not reviewed for accessibility

On this page

TextInput is a form component to add default styling to the native text input.

Note: Don't forget to set aria-label to make the TextInput accessible to screen reader users.

Examples

Basic

<TextInput aria-label="Zipcode" name="zipcode" placeholder="Zipcode" autoComplete="postal-code" />

<TextInput aria-label="Zipcode" name="zipcode" placeholder="Zipcode" autoComplete="postal-code" />

With icons

<>
  <TextInput
    leadingVisual={SearchIcon}
    aria-label="Zipcode"
    name="zipcode"
    placeholder="Zip"
    autoComplete="postal-code"
  />

  <TextInput
    trailingVisual={SearchIcon}
    aria-label="Zipcode"
    name="zipcode"
    placeholder="Zip"
    autoComplete="postal-code"
  />
</>

<>
  <TextInput
    leadingVisual={SearchIcon}
    aria-label="Zipcode"
    name="zipcode"
    placeholder="Zip"
    autoComplete="postal-code"
  />

  <TextInput
    trailingVisual={SearchIcon}
    aria-label="Zipcode"
    name="zipcode"
    placeholder="Zip"
    autoComplete="postal-code"
  />
</>

With text visuals

<>
  <TextInput leadingVisual="$" aria-label="Cost of the thing" name="cost" placeholder="23.45" />

  <TextInput sx={{width: '150px'}} trailingVisual="minutes" aria-label="Time in minutes" name="time" placeholder="25" />
</>

<>
  <TextInput leadingVisual="$" aria-label="Cost of the thing" name="cost" placeholder="23.45" />

  <TextInput sx={{width: '150px'}} trailingVisual="minutes" aria-label="Time in minutes" name="time" placeholder="25" />
</>

With visuals and loading indicators

const WithIconAndLoadingIndicator = () => {
  const [loading, setLoading] = React.useState(true)

  const toggleLoadingState = () => {
    setLoading(!loading)
  }

  return (
    <>
      <Box mb={6}>
        <button type="button" onClick={toggleLoadingState}>
          Toggle loading state {loading ? 'off' : 'on'}
        </button>
      </Box>

      <Text fontSize={3} mb={1} display="block">
        No visual
      </Text>
      <Box mb={3}>
        <TextInput loading={loading} />
      </Box>

      <Text fontSize={3} mb={1} display="block">
        Leading visual
      </Text>
      <Box mb={3}>
        <TextInput leadingVisual={SearchIcon} loading={loading} />
      </Box>

      <Text fontSize={3} mb={1} display="block">
        Trailing visual
      </Text>
      <Box mb={3}>
        <TextInput trailingVisual={SearchIcon} loading={loading} />
      </Box>

      <Text fontSize={3} mb={1} display="block">
        Both visuals
      </Text>
      <Box mb={3}>
        <TextInput leadingVisual={SearchIcon} trailingVisual={SearchIcon} loading={loading} />
      </Box>

      <Text fontSize={3} mb={2} display="block">
        Both visuals, position overriden
      </Text>
      <Box mb={3}>
        <TextInput loaderPosition="trailing" leadingVisual={SearchIcon} trailingVisual={SearchIcon} loading={loading} />
      </Box>
    </>
  )
}

render(<WithIconAndLoadingIndicator />)

const WithIconAndLoadingIndicator = () => {
  const [loading, setLoading] = React.useState(true)

  const toggleLoadingState = () => {
    setLoading(!loading)
  }

  return (
    <>
      <Box mb={6}>
        <button type="button" onClick={toggleLoadingState}>
          Toggle loading state {loading ? 'off' : 'on'}
        </button>
      </Box>

      <Text fontSize={3} mb={1} display="block">
        No visual
      </Text>
      <Box mb={3}>
        <TextInput loading={loading} />
      </Box>

      <Text fontSize={3} mb={1} display="block">
        Leading visual
      </Text>
      <Box mb={3}>
        <TextInput leadingVisual={SearchIcon} loading={loading} />
      </Box>

      <Text fontSize={3} mb={1} display="block">
        Trailing visual
      </Text>
      <Box mb={3}>
        <TextInput trailingVisual={SearchIcon} loading={loading} />
      </Box>

      <Text fontSize={3} mb={1} display="block">
        Both visuals
      </Text>
      <Box mb={3}>
        <TextInput leadingVisual={SearchIcon} trailingVisual={SearchIcon} loading={loading} />
      </Box>

      <Text fontSize={3} mb={2} display="block">
        Both visuals, position overriden
      </Text>
      <Box mb={3}>
        <TextInput loaderPosition="trailing" leadingVisual={SearchIcon} trailingVisual={SearchIcon} loading={loading} />
      </Box>
    </>
  )
}

render(<WithIconAndLoadingIndicator />)

With trailing action

<FormControl>
  <FormControl.Label>Icon action</FormControl.Label>
  <TextInput
    trailingAction={
      <TextInput.Action
        onClick={() => {
          alert('clear input')
        }}
        icon={XIcon}
        aria-label="Clear input"
        sx={{color: 'fg.subtle'}}
      />
    }
  />
</FormControl>

<FormControl>
  <FormControl.Label>Icon action</FormControl.Label>
  <TextInput
    trailingAction={
      <TextInput.Action
        onClick={() => {
          alert('clear input')
        }}
        icon={XIcon}
        aria-label="Clear input"
        sx={{color: 'fg.subtle'}}
      />
    }
  />
</FormControl>

With error and warning states

<>
  <TextInput
    validationStatus="error"
    aria-label="Zipcode"
    name="zipcode"
    placeholder="Error"
    autoComplete="postal-code"
  />

  <TextInput
    validationStatus="warning"
    aria-label="Zipcode"
    name="zipcode"
    placeholder="Warning"
    autoComplete="postal-code"
  />
</>

<>
  <TextInput
    validationStatus="error"
    aria-label="Zipcode"
    name="zipcode"
    placeholder="Error"
    autoComplete="postal-code"
  />

  <TextInput
    validationStatus="warning"
    aria-label="Zipcode"
    name="zipcode"
    placeholder="Warning"
    autoComplete="postal-code"
  />
</>

Block text input

<TextInput block aria-label="Zipcode" name="zipcode" placeholder="560076" autoComplete="postal-code" />

<TextInput block aria-label="Zipcode" name="zipcode" placeholder="560076" autoComplete="postal-code" />

Contrast text input

<TextInput contrast aria-label="Zipcode" name="zipcode" placeholder="Find user" autoComplete="postal-code" />

<TextInput contrast aria-label="Zipcode" name="zipcode" placeholder="Find user" autoComplete="postal-code" />

Monospace text input

<TextInput
  monospace
  aria-label="personal access token"
  name="pat"
  leadingVisual={CheckIcon}
  placeholder="github_pat_abcdefg123456789"
/>

<TextInput
  monospace
  aria-label="personal access token"
  name="pat"
  leadingVisual={CheckIcon}
  placeholder="github_pat_abcdefg123456789"
/>

Props

TextInput

Name	Type	Default	Description
aria-label	string		Allows input to be accessible.
block	boolean	false	Creates a full-width input element
contrast	boolean	false	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>
leadingVisual	string \| React.ComponentType		Visual positioned on the left edge inside the input
monospace	boolean	false	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' \| 'warning'		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		Style overrides to apply to the component. See also overriding styles.
ref	React.RefObject<HTMLInputElement>		A ref to the element rendered by this component.

TextInput.Action

Name	Type	Default	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.
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>		A ref to the element rendered by this component. Because this component is polymorphic, the type will vary based on the value of the `as` prop.
as	React.ElementType	"button"	The underlying element to render — either a HTML element name or a React component.
sx	SystemStyleObject		Style overrides to apply to the component. See also overriding styles.
Additional props are passed to the `<button>` element. See button docs for a list of props accepted by the `<button>` element.

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.

Edit this page on GitHub

7 contributors

Last edited by langermank on March 6, 2023