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.