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}
      />
    )
  }
}