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.

import React from "react";
import { TagInput } from "@commure/components-foundation";
function MyTagInput() {
const values = ["Vancomycin", "Zosyn", "Levofloxin"];
return (
<TagInput
addOnBlur
addOnPaste
fill
tagprops={{
minimal: true
}}
onChange={() => {}}
values={values}
/>
);
}
export default MyTagInput;

API Reference

TagInput

Prop NameRequired?TypeDescription
addOnBlurfalsebooleanIf true, `onAdd` will be invoked when the input loses focus. Otherwise, `onAdd` is only invoked when `enter` is pressed.
addOnPastefalsebooleanIf 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"]`
classNamefalsestringA space-delimited list of class names to pass along to a child element.
disabledfalsebooleanWhether the component is non-interactive. Note that you'll also need to disable the component's `rightElement`, if appropriate.
fillfalsebooleanWhether the tag input should take up the full width of its container.
inputPropsfalseHTMLInputPropsReact props to pass to the `<input>` element. Note that `ref` and `key` are not supported here; use `inputRef` below.
inputReffalse(input: HTMLInputElement | null) => voidRef handler for the `<input>` element.
inputValuefalsestringControlled value of the `<input>` element. This is shorthand for `inputProps={{ value }}`.
intentfalseIntentVisual intent color to apply to element.
largefalsebooleanWhether the tag input should use a large size.
leftIconfalseIconName | MaybeElementName of a Blueprint UI icon (or an icon element) to render on the left side of the input.
onAddfalse(values: string[], method: TagInputAddMethod) => boolean | voidCallback 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.
onChangefalse(values: React.ReactNode[]) => boolean | voidCallback 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"]} /> ```
onInputChangefalseReact.FormEventHandler<HTMLInputElement>Callback invoked when the value of `<input>` element is changed. This is shorthand for `inputProps={{ onChange }}`.
onKeyDownfalse(event: KeyboardEvent<HTMLElement>, index?: number) => voidCallback 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).
onKeyUpfalse(event: KeyboardEvent<HTMLElement>, index?: number) => voidCallback 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).
onRemovefalse(value: string, index: number) => voidCallback invoked when the user clicks the X button on a tag. Receives value and index of removed tag.
placeholderfalsestringInput 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.
rightElementfalseElementElement 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.
separatorfalsestring | RegExp | falseSeparator 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).
tagPropsfalseITagProps | (value: React.ReactNode, index: number) => ITagPropsReact 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.
valuestrueReact.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