0
# React TagsInput
1
2
React TagsInput is a highly customizable React component for creating tag input interfaces. It provides keyboard shortcuts, validation, render customization, and comprehensive event handling for building user-friendly tag selection systems.
3
4
## Package Information
5
6
- **Package Name**: react-tagsinput
7
- **Package Type**: npm
8
- **Language**: JavaScript/React
9
- **Installation**: `npm install react-tagsinput`
10
11
## Core Imports
12
13
```javascript
14
import TagsInput from 'react-tagsinput';
15
import 'react-tagsinput/react-tagsinput.css';
16
```
17
18
For CommonJS:
19
20
```javascript
21
const TagsInput = require('react-tagsinput');
22
```
23
24
## Basic Usage
25
26
```javascript
27
import React from 'react';
28
import TagsInput from 'react-tagsinput';
29
import 'react-tagsinput/react-tagsinput.css';
30
31
class Example extends React.Component {
32
constructor() {
33
super();
34
this.state = { tags: [] };
35
}
36
37
handleChange = (tags) => {
38
this.setState({ tags });
39
}
40
41
render() {
42
return (
43
<TagsInput
44
value={this.state.tags}
45
onChange={this.handleChange}
46
/>
47
);
48
}
49
}
50
```
51
52
## Architecture
53
54
React TagsInput is built around a single main component with several key architectural patterns:
55
56
- **Main Component**: `TagsInput` class component providing all tag input functionality
57
- **Render Props Pattern**: Customizable rendering through `renderTag`, `renderInput`, and `renderLayout` props
58
- **Event-Driven Architecture**: Comprehensive keyboard, mouse, and paste event handling
59
- **Validation System**: Dual validation through custom functions and regex patterns
60
- **Controlled/Uncontrolled Modes**: Supports both controlled and uncontrolled input patterns
61
62
## Capabilities
63
64
### Core TagsInput Component
65
66
The main React component for tag input functionality with extensive customization options.
67
68
```javascript { .api }
69
class TagsInput extends React.Component {
70
constructor();
71
72
// Instance methods
73
focus(): void;
74
blur(): void;
75
accept(): boolean;
76
addTag(tag: string | object): boolean;
77
clearInput(): void;
78
}
79
```
80
81
#### Required Props
82
83
```javascript { .api }
84
// Required props for TagsInput component
85
interface RequiredProps {
86
/** Array of current tags */
87
value: Array<string | object>;
88
89
/** Callback when tags change */
90
onChange(
91
tags: Array<string | object>,
92
changed: Array<string | object>,
93
changedIndexes: number[]
94
): void;
95
}
96
```
97
98
#### Optional Props - Basic Configuration
99
100
```javascript { .api }
101
interface BasicConfigProps {
102
/** CSS class for the wrapper element. Default: 'react-tagsinput' */
103
className?: string;
104
105
/** CSS class added when component is focused. Default: 'react-tagsinput--focused' */
106
focusedClassName?: string;
107
108
/** Keys that add a tag. Default: ['Tab', 'Enter'] */
109
addKeys?: Array<string | number>;
110
111
/** Keys that remove the last tag when input is empty. Default: ['Backspace'] */
112
removeKeys?: Array<string | number>;
113
114
/** Add tag when input loses focus. Default: false */
115
addOnBlur?: boolean;
116
117
/** Add tags when text is pasted. Default: false */
118
addOnPaste?: boolean;
119
120
/** Disable the component. Default: false */
121
disabled?: boolean;
122
}
123
```
124
125
#### Optional Props - Input Control
126
127
```javascript { .api }
128
interface InputControlProps {
129
/** Set initial input value (uncontrolled mode) */
130
currentValue?: string;
131
132
/** Input value for controlled mode */
133
inputValue?: string;
134
135
/** Callback for input changes in controlled mode */
136
onChangeInput?(value: string): void;
137
138
/** Props passed to the input element */
139
inputProps?: {
140
className?: string;
141
placeholder?: string;
142
onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
143
onFocus?: (event: React.FocusEvent<HTMLInputElement>) => void;
144
onBlur?: (event: React.FocusEvent<HTMLInputElement>) => void;
145
[key: string]: any;
146
};
147
}
148
```
149
150
#### Optional Props - Validation and Limits
151
152
```javascript { .api }
153
interface ValidationProps {
154
/** Allow only unique tags. Default: false */
155
onlyUnique?: boolean;
156
157
/** Maximum number of tags allowed. Default: -1 (unlimited) */
158
maxTags?: number;
159
160
/** Custom validation function. Default: () => true */
161
validate?(tag: string): boolean;
162
163
/** Regex pattern for tag validation. Default: /.*/ */
164
validationRegex?: RegExp;
165
166
/** Callback when tags are rejected by validation */
167
onValidationReject?(rejectedTags: Array<string | object>): void;
168
}
169
```
170
171
#### Optional Props - Customization
172
173
```javascript { .api }
174
interface CustomizationProps {
175
/** Props applied to each tag element */
176
tagProps?: {
177
className?: string;
178
classNameRemove?: string;
179
[key: string]: any;
180
};
181
182
/** Property name for object tags display. Default: null (string tags) */
183
tagDisplayProp?: string;
184
185
/** Custom tag rendering function */
186
renderTag?(props: {
187
tag: string | object;
188
key: number;
189
disabled: boolean;
190
onRemove: (index: number) => void;
191
classNameRemove: string;
192
getTagDisplayValue: (tag: string | object) => string;
193
[key: string]: any;
194
}): React.ReactElement;
195
196
/** Custom input rendering function */
197
renderInput?(props: {
198
onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
199
value: string;
200
addTag: (tag: string | object) => boolean;
201
[key: string]: any;
202
}): React.ReactElement;
203
204
/** Custom layout rendering function */
205
renderLayout?(
206
tagComponents: React.ReactElement[],
207
inputComponent: React.ReactElement
208
): React.ReactElement;
209
210
/** Function to split pasted text into tags */
211
pasteSplit?(data: string): string[];
212
213
/** Prevent form submission on Enter key. Default: true */
214
preventSubmit?: boolean;
215
}
216
```
217
218
### Default Render Functions
219
220
Pre-built rendering functions that can be used as references or extended.
221
222
```javascript { .api }
223
/**
224
* Default tag rendering function
225
*/
226
function defaultRenderTag(props: {
227
tag: string | object;
228
key: number;
229
disabled: boolean;
230
onRemove: (index: number) => void;
231
classNameRemove: string;
232
getTagDisplayValue: (tag: string | object) => string;
233
}): React.ReactElement;
234
235
/**
236
* Default input rendering function
237
*/
238
function defaultRenderInput(props: {
239
onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
240
value: string;
241
addTag: (tag: string | object) => boolean;
242
}): React.ReactElement;
243
244
/**
245
* Default layout rendering function
246
*/
247
function defaultRenderLayout(
248
tagComponents: React.ReactElement[],
249
inputComponent: React.ReactElement
250
): React.ReactElement;
251
252
/**
253
* Default paste splitting function - splits on spaces
254
*/
255
function defaultPasteSplit(data: string): string[];
256
```
257
258
### Instance Methods
259
260
Methods available on TagsInput component instances for programmatic control.
261
262
```javascript { .api }
263
/**
264
* Focus the input element
265
*/
266
focus(): void;
267
268
/**
269
* Blur the input element
270
*/
271
blur(): void;
272
273
/**
274
* Try to add whatever value is currently in the input element
275
* @returns true if a tag was successfully added
276
*/
277
accept(): boolean;
278
279
/**
280
* Add a specific tag programmatically
281
* @param tag - The tag to add (string or object)
282
* @returns true if the tag was successfully added
283
*/
284
addTag(tag: string | object): boolean;
285
286
/**
287
* Clear the current input value
288
*/
289
clearInput(): void;
290
```
291
292
### Event Handling
293
294
The component provides comprehensive event handling for user interactions:
295
296
- **Keyboard Events**: Customizable key bindings for adding and removing tags
297
- **Mouse Events**: Click-to-focus functionality
298
- **Paste Events**: Bulk tag addition from clipboard with custom splitting
299
- **Focus Events**: Automatic focus management and styling
300
301
### Tag Modes
302
303
The component supports two different tag storage modes:
304
305
**String Tags (Default)**:
306
```javascript
307
// Tags are stored as simple strings
308
const tags = ['react', 'javascript', 'web'];
309
```
310
311
**Object Tags**:
312
```javascript
313
// Tags are objects with a specified display property
314
const tags = [
315
{ id: 1, name: 'React', category: 'framework' },
316
{ id: 2, name: 'JavaScript', category: 'language' }
317
];
318
319
// Use tagDisplayProp to specify which property to display
320
<TagsInput
321
value={tags}
322
tagDisplayProp="name"
323
onChange={handleChange}
324
/>
325
```
326
327
### Validation System
328
329
Two-tier validation system ensures data quality:
330
331
1. **Custom Validation Function**: Use the `validate` prop to implement custom logic
332
2. **Regex Validation**: Use `validationRegex` for pattern-based validation
333
334
Both validations must pass for a tag to be accepted. Rejected tags can be handled via the `onValidationReject` callback.
335
336
### CSS Classes and Styling
337
338
The component provides several CSS classes for styling customization:
339
340
```css
341
/* Main wrapper - always present */
342
.react-tagsinput { }
343
344
/* Applied when component has focus */
345
.react-tagsinput--focused { }
346
347
/* Individual tag styling */
348
.react-tagsinput-tag { }
349
350
/* Tag remove button */
351
.react-tagsinput-remove { }
352
353
/* Input field styling */
354
.react-tagsinput-input { }
355
```
356
357
All CSS classes can be overridden through the `className`, `focusedClassName`, `tagProps`, and `inputProps` configuration options.