Tag Input
Introduction
The TagInput is a controlled component that displays Tags that precede an editable input element. Using event handlers, Tags can be added or removed from the container through events in the editable element. They can also be removed using event handlers on the Tags themselves.
Use the TagInput component as an alternative to checkboxes, especially when there are too many options or when the user is allowed to create their own.
Examples
VancomycinZosynLevofloxin
Usage
TagInput
Setting addOnBlur
and addOnPaste
gives the user flexibility in the way they can add content. Including addOnBlur
makes the component feel more like a freeform field input, especially with tagProps that make the tags minimal.
API Reference
TagInput
Prop Name | Required? | Type | Description |
---|---|---|---|
addOnBlur | false | boolean | If true, `onAdd` will be invoked when the input loses focus. Otherwise, `onAdd` is only invoked when `enter` is pressed. |
addOnPaste | false | boolean | If true, `onAdd` will be invoked when the user pastes text containing the `separator` into the input. Otherwise, pasted text will remain in the input. __Note:__ For example, if `addOnPaste=true` and `separator="\n"` (new line), then: - Pasting `"hello"` will _not_ invoke `onAdd` - Pasting `"hello\n"` will invoke `onAdd` with `["hello"]` - Pasting `"hello\nworld"` will invoke `onAdd` with `["hello", "world"]` |
className | false | string | A space-delimited list of class names to pass along to a child element. |
disabled | false | boolean | Whether the component is non-interactive. Note that you'll also need to disable the component's `rightElement`, if appropriate. |
fill | false | boolean | Whether the tag input should take up the full width of its container. |
inputProps | false | HTMLInputProps | React props to pass to the `<input>` element. Note that `ref` and `key` are not supported here; use `inputRef` below. |
inputRef | false | (input: HTMLInputElement | null) => void | Ref handler for the `<input>` element. |
inputValue | false | string | Controlled value of the `<input>` element. This is shorthand for `inputProps={{ value }}`. |
intent | false | Intent | Visual intent color to apply to element. |
large | false | boolean | Whether the tag input should use a large size. |
leftIcon | false | IconName | MaybeElement | Name of a Blueprint UI icon (or an icon element) to render on the left side of the input. |
onAdd | false | (values: string[], method: TagInputAddMethod) => boolean | void | Callback invoked when new tags are added by the user pressing `enter` on the input. Receives the current value of the input field split by `separator` into an array. New tags are expected to be appended to the list. The input will be cleared after `onAdd` is invoked _unless_ the callback explicitly returns `false`. This is useful if the provided `value` is somehow invalid and should not be added as a tag. |
onChange | false | (values: React.ReactNode[]) => boolean | void | Callback invoked when new tags are added or removed. Receives the updated list of `values`: new tags are appended to the end of the list, removed tags are removed at their index. Like `onAdd`, the input will be cleared after this handler is invoked _unless_ the callback explicitly returns `false`. This callback essentially implements basic `onAdd` and `onRemove` functionality and merges the two handlers into one to simplify controlled usage. **Note about typed usage:** Your handler can declare a subset type of `React.ReactNode[]`, such as `string[]` or `Array<string | JSX.Element>`, to match the type of your `values` array: ```tsx <TagInput onChange={(values: string[]) => this.setState({ values })} values={["apple", "banana", "cherry"]} /> ``` |
onInputChange | false | React.FormEventHandler<HTMLInputElement> | Callback invoked when the value of `<input>` element is changed. This is shorthand for `inputProps={{ onChange }}`. |
onKeyDown | false | (event: KeyboardEvent<HTMLElement>, index?: number) => void | Callback invoked when the user depresses a keyboard key. Receives the event and the index of the active tag (or `undefined` if focused in the input). |
onKeyUp | false | (event: KeyboardEvent<HTMLElement>, index?: number) => void | Callback invoked when the user releases a keyboard key. Receives the event and the index of the active tag (or `undefined` if focused in the input). |
onRemove | false | (value: string, index: number) => void | Callback invoked when the user clicks the X button on a tag. Receives value and index of removed tag. |
placeholder | false | string | Input placeholder text which will not appear if `values` contains any items (consistent with default HTML input behavior). Use `inputProps.placeholder` if you want the placeholder text to _always_ appear. If you define both `placeholder` and `inputProps.placeholder`, then the former will appear when `values` is empty and the latter at all other times. |
rightElement | false | Element | Element to render on right side of input. For best results, use a small spinner or minimal button (button height will adjust if `TagInput` uses large styles). Other elements will likely require custom styles for correct positioning. |
separator | false | string | RegExp | false | Separator pattern used to split input text into multiple values. Default value splits on commas and newlines. Explicit `false` value disables splitting (note that `onAdd` will still receive an array of length 1). |
tagProps | false | ITagProps | (value: React.ReactNode, index: number) => ITagProps | React props to pass to each `Tag`. Provide an object to pass the same props to every tag, or a function to customize props per tag. If you define `onRemove` here then you will have to implement your own tag removal handling as `TagInput`'s own `onRemove` handler will never be invoked. |
values | true | React.ReactNode[] | Controlled tag values. Each value will be rendered inside a `Tag`, which can be customized using `tagProps`. Therefore, any valid React node can be used as a `TagInput` value; falsy values will not be rendered. __Note about typed usage:__ If you know your `values` will always be of a certain `ReactNode` subtype, such as `string` or `ReactChild`, you can use that type on all your handlers to simplify type logic. |
Related Reading
Blueprint Reference