@xonev/react-tag-input

    2.0.4 • Public • Published

    React-Tags

    NPM

    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

    img

    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 (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).

    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 😀

    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.

    Install

    npm i @xonev/react-tag-input

    DownloadsWeekly Downloads

    5

    Version

    2.0.4

    License

    MIT

    Last publish

    Collaborators

    • xonev