react-tag-input

React-Tags

React tags is a simple tagging component ready to drop in your React projects. The component is inspired by GMail's To field in the compose window.

Features

• Autocomplete based on a suggestion list
• Keyboard friendly and mouse support
• Reorder tags using drag and drop

Why

Because I was looking for an excuse to build a standalone component and publish it in the wild? To be honest, I needed a tagging component that provided the above features for my React-Surveyman project. Since I was unable to find one which met my requirements (and the fact that I generally enjoy re-inventing the wheel) this is what I came up with.

Demo

Check it out here

Installation

The preferred way of using the component is via NPM

npm install --save react-tag-input

It is, however, also available to be used separately (dist/ReactTags.min.js). If you prefer this method remember to include ReactDND as a dependancy. Refer to the demo to see how this works.

Usage

Here's a sample implementation that initializes the component with a list of initial tags and suggestions list. Apart from this, there are multiple events, handlers for which need to be set. For more details, go through the API.

var ReactTags = require('react-tag-input').WithContext;

var App = React.createClass({
    getInitialState: function() {
        return {
            tags: [ {id: 1, text: "Apples"} ],
            suggestions: ["Banana", "Mango", "Pear", "Apricot"]
        }
    },
    handleDelete: function(i) {
        var tags = this.state.tags;
        tags.splice(i, 1);
        this.setState({tags: tags});
    },
    handleAddition: function(tag) {
        var tags = this.state.tags;
        tags.push({
            id: tags.length + 1,
            text: tag
        });
        this.setState({tags: tags});
    },
    handleDrag: function(tag, currPos, newPos) {
        var tags = this.state.tags;

        // mutate array
        tags.splice(currPos, 1);
        tags.splice(newPos, 0, tag);

        // re-render
        this.setState({ tags: tags });
    },
    render: function() {
        var tags = this.state.tags;
        var suggestions = this.state.suggestions;
        return (
            <div>
                <ReactTags tags={tags}
                    suggestions={suggestions}
                    handleDelete={this.handleDelete}
                    handleAddition={this.handleAddition}
                    handleDrag={this.handleDrag} />
            </div>
        )
    }
});

React.render(<App />, document.getElementById('app'));

A note about Contexts One of the dependancies of this component is the react-dnd library. Since the 1.0 version, the original author has changed the API and requires the application using any draggable components to have a top-level backend context. So if you're using this component in an existing Application that uses React-DND you will already have a backend defined, in which case, you should require the component without the context.

var { ReactTags } = require('react-tag-input').WithOutContext;

Otherwise, you can simply import along with the backend itself (as shown above). If you have ideas to make this API better, I'd love to hear.

Options

• tags
• suggestions
• delimeters
• placeholder
• labelField
• handleAddition
• handleDelete
• handleDrag
• autofocus
• allowDeleteFromEmptyInput
• handleInputChange
• minQueryLength
• removeComponent
• autocomplete
• readOnly

tags (optional)

An array of tags that are displayed as pre-selected. Each tag should have an id and a text property which is used to display.

var tags =  [ {id: 1, text: "Apples"} ]

suggestions (optional)

An array of suggestions that are used as basis for showing suggestions. At the moment, this should be an array of strings.

var suggestions = ["mango", "pineapple", "orange", "pear"];

delimeters (optional)

Specifies which characters should terminate tags input (default: enter and tab). A list of character codes.

placeholder (optional)

The placeholder shown for the input. Defaults to Add new tag.

var placeholder = "Add new country"

labelField (optional)

Provide an alternative label property for the tags. Defaults to text.

<ReactTags tags={tags}
    suggestions={}
    labelField={'name'}
    handleDrag={} />

This is useful if your data uses the text property for something else.

handleAddition (required)

Function called when the user wants to add a tag (either a click, a tab press or carriage return)

function(tag) {
    // add the tag to the tag list
}

handleDelete (required)

Function called when the user wants to delete a tag

function(i) {
    // delete the tag at index i
}

handleDrag (required)

Function called when the user drags a tag.

function(tag, currPos, newPos) {
    // remove tag from currPos and add in newPos
}

autofocus (optional)

Optional boolean param to control whether the text-input should be autofocused on mount.

<ReactTags
    autofocus={false}
    ...>        

allowDeleteFromEmptyInput (optional)

Optional boolean param to control whether tags should be deleted when the 'Delete' key is pressed in an empty Input Box.

<ReactTags
    allowDeleteFromEmptyInput={false}
    ...>

handleInputChange (optional)

Optional event handler for input onChange

<ReactTags
    handleInputChange={this.handleInputChange}
    ...>

minQueryLength (optional)

How many characters are needed for suggestions to appear (default: 2).

removeComponent (optional)

If you'd like to supply your own tag delete/remove element, create a React component and pass it as a property to ReactTags using the removeComponent option. By default, a simple anchor link with an "x" text node as its only child is rendered, but if you'd like to, say, replace this with a <button> element that uses an image instead of text, your markup may look something like this:

import {WithContext as ReactTags} from 'react-tag-input'

class Foo extends React.Component {
   render() {
      return <ReactTags removeComponent={RemoveComponent}/>
   }
}

class RemoveComponent extends React.Component {
   render() {
      return (
         <button {...this.props}>
            <img src="my-icon.png" />
         </button>
      )
   }
}

The "ReactTags__remove" className and onClick handler properties can be automatically included on the <button> by using the JSX spread attribute, as illustrated above.

autocomplete (optional)

Useful for enhancing data entry workflows for your users by ensuring the first matching suggestion is automatically converted to a tag when a delimeter key is pressed (such as the enter key). This option has three possible values:

• true - when delimeter key (such as enter) is pressed, first matching suggestion is used.
• 1 - when delimeter key (such as enter) is pressed, matching suggestion is used only if there is a single matching suggestion
• false (default) - tags are not autocompleted on enter/delimeter

This option has no effect if there are no suggestions.

readOnly (optional)

Renders the component in read-only mode without the input box and removeComponent. This also disables the drag-n-drop feature.

Styling

<ReactTags> does not come up with any styles. However, it is very easy to customize the look of the component the way you want it. The component provides the following classes with which you can style -

• ReactTags__tags
• ReactTags__tagInput
• ReactTags__selected
• ReactTags__selected ReactTags__tag
• ReactTags__selected ReactTags__remove
• ReactTags__suggestions

An example can be found in /example/reactTags.css.

Dev

The component is written in ES6 and uses Webpack as its build tool.

npm install
npm run dev
python -m SimpleHTTPServer ### open in browser

Contributing

Got ideas on how to make this better? Open an issue! I'm yet to add tests so keep your PRs on hold :grinning:

Thanks

The autocomplete dropdown is inspired by Lea Verou's awesomeplete library. The Drag and drop functionality is provided by Dan Abramov's insanely useful ReactDND library.