1 | @# Tag input
|
2 |
|
3 | Tag inputs render [`Tag`](#core/components/tag)s inside an input, followed by an
|
4 | actual text input. The container is merely styled to look like a Blueprint
|
5 | input; the actual editable element appears after the last tag. Clicking anywhere
|
6 | on the container will focus the text input for seamless interaction.
|
7 |
|
8 | @reactExample TagInputExample
|
9 |
|
10 | <div class="@ns-callout @ns-intent-success @ns-icon-info-sign">
|
11 | <h4 class="@ns-heading">Looking for a dropdown menu?</h4>
|
12 |
|
13 | [`MultiSelect` in the **@blueprintjs/select** package](#select/multi-select)
|
14 | composes this component with a dropdown menu of suggestions.
|
15 |
|
16 | </div>
|
17 |
|
18 | @## Props
|
19 |
|
20 | **`TagInput` must be controlled,** meaning the `values` prop is required and
|
21 | event handlers are strongly suggested. Typing in the input and pressing
|
22 | <kbd>enter</kbd> will **add new items** by invoking callbacks. If `addOnBlur` is
|
23 | set to true, clicking out of the component will also trigger the callback to add
|
24 | new items. A `separator` prop is supported to allow multiple items to be added
|
25 | at once; the default splits on commas and newlines.
|
26 |
|
27 | **Tags can be removed** by clicking their <span class="@ns-icon-standard @ns-icon-cross"></span>
|
28 | buttons, or by pressing either <kbd>backspace</kbd> or <kbd>delete</kbd> repeatedly.
|
29 | Pressing <kbd>delete</kbd> mimics the behavior of deleting in a text editor, where trying to delete at the end of the line will do nothing.
|
30 | Arrow keys can also be used to focus on a particular tag before removing it. The
|
31 | cursor must be at the beginning of the text input for these interactions.
|
32 |
|
33 | **`Tag` appearance can be customized** with `tagProps`: supply an object to
|
34 | apply the same props to every tag, or supply a callback to apply dynamic props
|
35 | per tag. Tag `values` must be an array of strings so you may need a
|
36 | transformation step between your state and these props.
|
37 |
|
38 | `TagInput` provides granular `onAdd` and `onRemove` **event props**, which are
|
39 | passed the added or removed items in response to the user interactions above. It
|
40 | also provides `onChange`, which combines both events and is passed the updated
|
41 | `values` array, with new items appended to the end and removed items filtered
|
42 | away.
|
43 |
|
44 | The `<input>` element can be controlled directly via the `inputValue` and
|
45 | `onInputChange` props. Additional properties (such as custom event handlers) can
|
46 | be applied to the input via `inputProps`.
|
47 |
|
48 | <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
|
49 | <h4 class="@ns-heading">Handling long words</h4>
|
50 |
|
51 | Set an explicit `width` on the container element to cause long tags to wrap onto multiple lines.
|
52 | Either supply a specific pixel value, or use `<TagInput className={Classes.FILL}>`
|
53 | to fill its container's width (try this in the example above).
|
54 |
|
55 | </div>
|
56 |
|
57 | <div class="@ns-callout @ns-intent-primary @ns-icon-info-sign">
|
58 | <h4 class="@ns-heading">Disabling a tag input</h4>
|
59 |
|
60 | Disabling this component requires setting the `disabled` prop to `true`
|
61 | and separately disabling the component's `rightElement` as appropriate
|
62 | (because `TagInput` accepts any `JSX.Element` as its `rightElement`).
|
63 |
|
64 | </div>
|
65 |
|
66 | @interface ITagInputProps
|