TextInputWithTokens

TextInputWithTokens is an input for a value that is a list.

Page navigation navigation

React

readyNot reviewed for a11y

Use a TextInputWithTokens for lists where items can be added or removed, but not edited inline. Typically paired with autocomplete for selecting items from a list.

React examples

Default

Default label

zero (press backspace or delete to remove)one (press backspace or delete to remove)two (press backspace or delete to remove)three (press backspace or delete to remove)

<FormControl>
  <FormControl.Label>Default label</FormControl.Label>
  <TextInputWithTokens
    tokens={[
      {text: 'zero', id: 0},
      {text: 'one', id: 1},
      {text: 'two', id: 2},
      {text: 'three', id: 3},
    ]}
    onTokenRemove={(tokenId: string | number) => {
      alert(`Fake remove token with id: ${tokenId}`)
    }}
  />
</FormControl>

<FormControl>
  <FormControl.Label>Default label</FormControl.Label>
  <TextInputWithTokens
    tokens={[
      {text: 'zero', id: 0},
      {text: 'one', id: 1},
      {text: 'two', id: 2},
      {text: 'three', id: 3},
    ]}
    onTokenRemove={(tokenId: string | number) => {
      alert(`Fake remove token with id: ${tokenId}`)
    }}
  />
</FormControl>

Prevent wrapping

By default, tokens wrap to multiple lines. You may override this to force tokens or stay on one line in a horizontal scrolling container.

Default label

zero (press backspace or delete to remove)one (press backspace or delete to remove)two (press backspace or delete to remove)three (press backspace or delete to remove)four (press backspace or delete to remove)five (press backspace or delete to remove)six (press backspace or delete to remove)seven (press backspace or delete to remove)eight (press backspace or delete to remove)nine (press backspace or delete to remove)

<Box sx={{maxWidth: '500px'}}>
  <FormControl>
    <FormControl.Label>Default label</FormControl.Label>
    {/* Setting max-width to prevent the input from overflowing the example box */}
    <TextInputWithTokens
      preventTokenWrapping
      tokens={[
        {text: 'zero', id: 0},
        {text: 'one', id: 1},
        {text: 'two', id: 2},
        {text: 'three', id: 3},
        {text: 'four', id: 4},
        {text: 'five', id: 5},
        {text: 'six', id: 6},
        {text: 'seven', id: 7},
        {text: 'eight', id: 8},
        {text: 'nine', id: 9},
      ]}
      onTokenRemove={(tokenId: string | number) => {
        alert(`Fake remove token with id: ${tokenId}`)
      }}
      block // `block` only needed to fill parent width without overflowing
    />
  </FormControl>
</Box>

<Box sx={{maxWidth: '500px'}}>
  <FormControl>
    <FormControl.Label>Default label</FormControl.Label>
    {/* Setting max-width to prevent the input from overflowing the example box */}
    <TextInputWithTokens
      preventTokenWrapping
      tokens={[
        {text: 'zero', id: 0},
        {text: 'one', id: 1},
        {text: 'two', id: 2},
        {text: 'three', id: 3},
        {text: 'four', id: 4},
        {text: 'five', id: 5},
        {text: 'six', id: 6},
        {text: 'seven', id: 7},
        {text: 'eight', id: 8},
        {text: 'nine', id: 9},
      ]}
      onTokenRemove={(tokenId: string | number) => {
        alert(`Fake remove token with id: ${tokenId}`)
      }}
      block // `block` only needed to fill parent width without overflowing
    />
  </FormControl>
</Box>

With a max height

When wrapping, set a max height; exceeding rows will scroll vertically.

Default label

<Box sx={{maxWidth: '300px'}}>
  <FormControl>
    <FormControl.Label>Default label</FormControl.Label>
    {/* Setting max-width to force tokens to wrap and demo `maxHeight` behavior */}
    <TextInputWithTokens
      tokens={[
        {text: 'zero', id: 0},
        {text: 'one', id: 1},
        {text: 'two', id: 2},
        {text: 'three', id: 3},
        {text: 'four', id: 4},
        {text: 'five', id: 5},
        {text: 'six', id: 6},
        {text: 'seven', id: 7},
        {text: 'eight', id: 8},
        {text: 'nine', id: 9},
      ]}
      onTokenRemove={(tokenId: string | number) => {
        alert(`Fake remove token with id: ${tokenId}`)
      }}
      maxHeight={100}
      block // `block` only needed to fill parent width without overflowing
    />
  </FormControl>
</Box>

<Box sx={{maxWidth: '300px'}}>
  <FormControl>
    <FormControl.Label>Default label</FormControl.Label>
    {/* Setting max-width to force tokens to wrap and demo `maxHeight` behavior */}
    <TextInputWithTokens
      tokens={[
        {text: 'zero', id: 0},
        {text: 'one', id: 1},
        {text: 'two', id: 2},
        {text: 'three', id: 3},
        {text: 'four', id: 4},
        {text: 'five', id: 5},
        {text: 'six', id: 6},
        {text: 'seven', id: 7},
        {text: 'eight', id: 8},
        {text: 'nine', id: 9},
      ]}
      onTokenRemove={(tokenId: string | number) => {
        alert(`Fake remove token with id: ${tokenId}`)
      }}
      maxHeight={100}
      block // `block` only needed to fill parent width without overflowing
    />
  </FormControl>
</Box>

Truncated token list

You may choose to limit the number of tokens that are visible. However, all tokens will be visible while the text input is focused.

Default label

<FormControl>
  <FormControl.Label>Default label</FormControl.Label>
  <TextInputWithTokens
    visibleTokenCount={5}
    tokens={[
      {text: 'zero', id: 0},
      {text: 'one', id: 1},
      {text: 'two', id: 2},
      {text: 'three', id: 3},
      {text: 'four', id: 4},
      {text: 'five', id: 5},
      {text: 'six', id: 6},
      {text: 'seven', id: 7},
      {text: 'eight', id: 8},
      {text: 'nine', id: 9},
    ]}
    onTokenRemove={(tokenId: string | number) => {
      alert(`Fake remove token with id: ${tokenId}`)
    }}
  />
</FormControl>

<FormControl>
  <FormControl.Label>Default label</FormControl.Label>
  <TextInputWithTokens
    visibleTokenCount={5}
    tokens={[
      {text: 'zero', id: 0},
      {text: 'one', id: 1},
      {text: 'two', id: 2},
      {text: 'three', id: 3},
      {text: 'four', id: 4},
      {text: 'five', id: 5},
      {text: 'six', id: 6},
      {text: 'seven', id: 7},
      {text: 'eight', id: 8},
      {text: 'nine', id: 9},
    ]}
    onTokenRemove={(tokenId: string | number) => {
      alert(`Fake remove token with id: ${tokenId}`)
    }}
  />
</FormControl>

Props

TextInputWithTokens

Name	Required	Description
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>` The 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` Whether tokens should render inline horizontally. By default, tokens wrap to new lines
size		`'small' \| 'medium' \| 'large' \| 'xlarge'` The size of the tokens and text input
hideTokenRemoveButtons		`boolean` Whether the remove buttons should be rendered in the tokens
validationStatus		`'error' \| 'success'` Style the input to match the status
visibleTokenCount		`number` The number of tokens to display before truncating