Tag Input

Tag input presents user with a set of options and allows to select one of them.

#

#

Tag input should be disabled, when user shouldn't be allowed to interact with it.

#

Mark tag input as loading, when options are fetched on the fly and are not yet available.

#

Invalid tag input indicates that current value isn't what the system expects.

#

Options can display an additional descriptive text underneath the label. For a description that applies to all the options use the top-level description prop.

#

Options can display an additional accessory view before the label. You can show an image using an image accessory. This is useful for showing logos when selecting sources or destinations, for example.

Image accessory can also indicate a status of the related resource. For example, this would be useful for sync statuses.

Allowed values are the same as in status indicator.

Tag input, as a combobox, supports filtering options based on the input value. This state is accessible via the onSearchUpdate prop. Any change that's typed in the input will call this function.

#

Tag input allows user to create a new option on the fly, when no suitable option exists. For that, enable supportsCreatableOptions and set an onCreateOption function that will handle creation of options. Options can be created asynchronously, but you need to handle loading state yourself via isLoading prop.

#

You don't have to create objects with label and value keys as shown in the examples above. TagInput supports any objects, as long as you provide a label and value for each option via optionLabel and optionValue functions. description may be replaced with the optionDescription function.

#

There's a version of TagInput called GroupedTagInput, that supports groups of options.

#

The size prop impacts font-size and height. Default is set to md.

To set the width, use the width prop instead.

#

When rendering smaller-width tag inputs, you may end up with options that are quite tall. To make the options easier to read, pass in a specific width for the popover using popoverWidth.

It is recommended to match widths, when possible.

#

#

  • When multiple selection is allowed.
  • When user is allowed to create new options.

#

#

#

NameDefaultDescription
isDisabled

boolean

Determines if select is disabled.

isLoading

boolean

Indicates that options are being loaded.

isInvalid

boolean

Indicates that select is in invalid state.

isOptionDisabled

(option: Option) => boolean

Function to determine whether an option should be disabled.

emptyOptionsMessage"No options"string

Text to show inside a dropdown when there are no options.

supportsCreatableOptions

boolean

Determines if user is allowed to create a new option, if it's not present already.

createOptionMessage"Create "[input value]""(inputValue: string) => string

Text to show inside dropdown when creating a new option.

options

Option[]

Available options. `Option` is a generic, so type of options will be inferred.

optionLabel

(option: Option) => string

Function to extract label from an option. If it's not provided, `label` field will be used as a label.

optionDescription

(option: Option) => string

Function to extract description from an option. If it's not provided, `description` field will be used as a label.

optionValue

(option: Option) => OptionValue

Function to extract value from an option. If it's not provided, `value` field will be used as a value.

optionAccessory

(option: Option) => TagAccessory

Function to show an accessory view near the option label.

placeholder

string

Text to show inside select when no option is selected.

removePortalfalseboolean

Determines if the select dropdown should be rendered in a portal.

size"md""sm" | "md" | "lg"

Tag input size.

value

OptionValue[]

Selected options

width"xs""xs" | "sm" | "md" | "lg" | "xl" | "100%"

Tag input width.

popoverWidthundefined"xs" | "sm" | "md" | "lg" | "xl"

The dropdown width. If not provided, the select width will be used.

onChange

(value: OptionValue[]) => void

Callback for when user selects a different option or clears the selection.

onClose

() => void

Callback for when user closes the select.

onOpen

() => void

Callback for when user opens the select.

onCreateOption

(inputValue: string) => Promise<void> | void

Callback for creating a new option. It can be async.

onSearchUpdate

(inputValue: string) => void

Callback for when user changes the input value.

description

string

Description of the select options

valueLabel

(option: Option) => string

Function to format a selected option's label. If not provided, `label` field will be used as a label.

tagInputRef

RefObject<HTMLInputElement>

Reference to the tagInput element.

#

NameDefaultDescription
isDisabled

boolean

Determines if select is disabled.

isLoading

boolean

Indicates that options are being loaded.

isInvalid

boolean

Indicates that select is in invalid state.

isOptionDisabled

(option: Option) => boolean

Function to determine whether an option should be disabled.

emptyOptionsMessage"No options"string

Text to show inside a dropdown when there are no options.

optionGroups

Array<{ label: string; options: Option[]; }>

Available options. `Option` is a generic, so type of options will be inferred.

optionLabel

(option: Option) => string

Function to extract label from an option. If it's not provided, `label` field will be used as a label.

optionDescription

(option: Option) => string

Function to extract description from an option. If it's not provided, `description` field will be used as a label.

optionValue

(option: Option) => OptionValue

Function to extract value from an option. If it's not provided, `value` field will be used as a value.

optionAccessory

(option: Option) => TagAccessory

Function to show an accessory view near the option label.

placeholder

string

Text to show inside select when no option is selected.

removePortalfalseboolean

Determines if the select dropdown should be rendered in a portal.

size"md""sm" | "md" | "lg"

Tag input size.

value

OptionValue[]

Selected options

width"xs""xs" | "sm" | "md" | "lg" | "xl" | "100%"

Tag input width.

popoverWidthundefined"xs" | "sm" | "md" | "lg" | "xl"

The dropdown width. If not provided, the select width will be used.

onChange

(value: OptionValue[]) => void

Callback for when user selects a different option or clears the selection.

onSearchUpdate

(inputValue: string) => void

Callback for when user changes the input value.

valueLabel

(option: Option) => string

Function to format a selected option's label. If not provided, `label` field will be used as a label.

tagInputRef

RefObject<HTMLInputElement>

Reference to the tagInput element.

On this page

  • Usage
  • Disabled
  • Loading
  • Invalid
  • Description
  • Accessories
  • Search
  • Creatable options
  • Custom objects
  • Groups
  • Size
  • Popover width
  • Guidelines
  • When to use
  • Content
  • Props
  • TagInput
  • GroupedTagInput