react-tag-box
A React component for creating, selecting, and removing tags. This library focuses entirely on tagging rather than attempting to be a generic autocomplete library, because we think that single responsibility and custom built solutions are good things.
Demo
Check out our demo on gh-pages.
Usage
react-tag-box manages Tag objects in the form of { label: String, value: Any }, and supports both preloaded and asynchronous autocomplete options by providing two different components: TagBox and TagBoxAsync. Both components accept the following common properties:
| Property Name | Type | Required | Description |
|---|---|---|---|
| selected | Array<Tag> | true | The list of currently selected tags |
| onSelect | function(tag) | true | Function to be executed when a tag is selected or submitted |
| removeTag | function(tag) | true | Function called when the remove button is clicked on a tag |
| renderNewOption | function(text) | false | Function for overriding the default Add ${input} prompt |
| selectedText | string | false | Text to display when the search input is already a selected tag. 'Already Selected' by default. |
| renderTag | function(tag, remove) | false | Function to override default tag rendering |
| placeholder | string | false | Override default placeholder text |
| backspaceDelete | bool | false | Whether or not the backspace key should delete the last tag. false by default |
| search | function(tag, input) | false | Function to determine if a given tag should be included in the autocomplete suggestions for a given input. |
| exactMatch | function(tag, input) | false | Function to determine if the tag matches the input. |
TagBox
Users provide the following props in addition to the common props:
| Property Name | Type | Required | Description |
|---|---|---|---|
| tags | Array<Tag> | true | The List of all tags |
Example
import { List } from 'immutable' import React, { Component } from 'react' import { TagBox } from 'react-tag-box' import './styles.scss' const sampleTags = List( ['foo', 'bar', 'baz', 'blitz', 'quux', 'barf', 'balderdash'].map(t => ({ label: t, value: t })) ) export default class App extends Component { state = { tags: sampleTags, selected: List.of(sampleTags.first()) } render() { const { tags, selected } = this.state const onSelect = tag => { const newTag = { label: tag.label, value: tag.value || tag.label } this.setState({ selected: selected.push(newTag) }) } const remove = tag => { this.setState({ selected: selected.filter(t => t.value !== tag.value) }) } // optional // default behavior is case-sensitive search within tag label, like so: // (tag, input) => tag.label.includes(input) const search = (tag, input) => { tag.label.toLowerCase().includes(input.toLowerCase()) } // optional // default behavior is case-sensitive match against tag label, like so: // (tag, input) => tag.label === input const exactMatch = (tag, input) => { tag.label.toLowerCase() === input.toLowerCase(); } return ( <div style={{ width: '50%' }}> <TagBox tags={unselected.toJS()} selected={tags.toJS()} onSelect={onSelect} removeTag={remove} search={search} exactMatch={exactMatch} /> </div> ) } }TagBoxAsync
Users provide the following props in addition to the common props:
| Property Name | Type | Required | Description |
|---|---|---|---|
| fetch | function(text) | true | A function that returns a promise which resolves the tags to populate the autocomplete. |
| loadingText | string | false | Text to display when results are being fetched. 'Loading...' by default. |
Example
import { List } from 'immutable' import React, { Component } from 'react' import { TagBoxAsync } from 'react-tag-box' import './styles.scss' // Mock server data. This would normally be in your database. const sampleTags = List( ['foo', 'bar', 'baz', 'blitz', 'quux', 'barf', 'balderdash'].map(t => ({ label: t, value: t })) ) // Mock http request. This would normally make a request to your server to fetch matching tags. const fetch = input => { return new Promise(resolve => { setTimeout(() => { resolve(sampleTags.filter(t => t.label.includes(input)).toJS()) }, 1500) }) } export default class Async extends Component { state = { selected: sampleTags.take(1) } render() { const { selected } = this.state const onSelect = tag => { const newTag = { label: tag.label, value: tag.value || tag.label } this.setState({ selected: selected.push(newTag) }) } const remove = tag => { this.setState({ selected: selected.filter(t => t.value !== tag.value) }) } const placeholder = selected.isEmpty() ? '' : "Use the backspace key to delete the last tag" return ( <TagBoxAsync fetch={fetch} selected={selected.toJS()} onSelect={onSelect} removeTag={remove} backspaceDelete={true} placeholder={placeholder} /> ) } }
