Skip to content

TextInputWithTokens

Used to show multiple values in one field
  • Alpha
  • Not reviewed for accessibility

A TextInputWithTokens component supports all of the features of a TextInput component, but it can render a list of Tokens next to the area a user types in.

Examples

Basic

Using a different token component

By default, the Token component is used to render the tokens in the input. If this component does not make sense for the kinds of tokens you're rendering, you can pass a component to the tokenComponent prop

Dealing with long lists of tokens

By default, all tokens will be visible when the component is rendered.

If the component is being used in an area where it's height needs to be constrained, there are options to limit the height of the input.

Render tokens on a single line

Set a maximum height for the input

With an error validation status

With leading and trailing visuals

With visuals and loading indicators

Props

TextInputWithTokens

NameTypeDefaultDescription
tokens Required
TokenProps[]
The array of tokens to render
onTokenRemove Required
(tokenId: string|number) => void
The function that gets called when a token is removed
tokenComponent
React.ComponentType<any>
TokenThe component used to render each token
maxHeight
React.CSSProperties['maxHeight']
The maximum height of the component. If the content in the input exceeds this height, it will scroll vertically
preventTokenWrapping
boolean
falseWhether tokens should render inline horizontally. By default, tokens wrap to new lines
size
'small' | 'medium' | 'large' | 'xlarge'
xlargeThe size of the tokens and text input
hideTokenRemoveButtons
boolean
falseWhether the remove buttons should be rendered in the tokens
validationStatus
'error' | 'success' | 'warning'
Style the input to match the status
visibleTokenCount
number
The number of tokens to display before truncating

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.