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
Edit code

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.

1import React from "react";
2import { TagInput } from "@commure/components-foundation";
3
4function MyTagInput() {
5  const values = ["Vancomycin", "Zosyn", "Levofloxin"];
6  return (
7    <TagInput
8      addOnBlur
9      addOnPaste
10      fill
11      tagprops={{
12        minimal: true
13      }}
14      onChange={() => {}}
15      values={values}
16    />
17  );
18}
19
20export default MyTagInput;

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