Skip to content

TextInputWithTokens

Alpha
Used to show multiple values in one field

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

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

Adding and removing tokens

The array passed to the tokens prop needs to be manually updated to add and remove tokens.

The function passed to the onRemoveToken prop is called when:

  • Clicking the remove button in the token
  • Pressing the Backspace key when the input is empty
  • Selecting a token using the arrow keys or by clicking on a token and then pressing the Backspace key

There is no function that gets called to "add" a token, so the user needs to be provided with a UI to select tokens.

Status

Alpha

  • Component props 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 100% test coverage.

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 has been manually reviewed by the accessibility team and any resulting issues have been addressed.

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.