react-tag-autocomplete

React Tag Autocomplete

React Tag Autocomplete is a simple tagging component ready to drop in your React projects. Originally based on the React Tags project by Prakhar Srivastav this version removes the drag-and-drop re-ordering functionality, adds appropriate roles and ARIA states and introduces a resizing text input. React Tag Autocomplete is compatible with Preact >= 6.0.0.

Installation

The preferred way of using the component is via NPM

npm install --save react-tag-autocomplete

Usage

Here's a sample implementation that initializes the component with a list of preselected tags and a suggestions list. For more details, go through the API.

const React = require('react')
const ReactDOM = require('react-dom')
const ReactTags = require('react-tag-autocomplete')

class App extends React.Component {
  constructor (props) {
    super(props)

    this.state = {
      tags: [
        { id: 1, name: "Apples" },
        { id: 2, name: "Pears" }
      ],
      suggestions: [
        { id: 3, name: "Bananas" },
        { id: 4, name: "Mangos" },
        { id: 5, name: "Lemons" },
        { id: 6, name: "Apricots" }
      ]
    }
  }

  onDelete (i) {
    const tags = this.state.tags.slice(0)
    tags.splice(i, 1)
    this.setState({ tags })
  }

  onAddition (tag) {
    const tags = [].concat(this.state.tags, tag)
    this.setState({ tags })
  }

  render () {
    return (
      <ReactTags
        tags={this.state.tags}
        suggestions={this.state.suggestions}
        onDelete={this.onDelete.bind(this)}
        onAddition={this.onAddition.bind(this)} />
    )
  }
}

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

Options

• id
• tags
• suggestions
• suggestionsFilter
• placeholderText
• removeButtonText
• autoresize
• delimiters
• minQueryLength
• maxSuggestionsLength
• classNames
• onAddition
• onDelete
• onInput
• onFocus
• onBlur
• onValidate
• addOnBlur
• allowNew
• allowBackspace
• tagComponent
• inputAttributes

id (optional)

The ID attribute given to the listbox element. Default: ReactTags.

tags (optional)

An array of tags that are displayed as pre-selected. Each tag must have an id and a name property. Default: [].

const tags =  [
  { id: 1, name: "Apples" },
  { id: 2, name: "Pears" }
]

suggestions (optional)

An array of suggestions that are used as basis for showing suggestions. Each suggestion must have an id and a name property and an optional disabled property. Default: [].

const suggestions = [
  { id: 3, name: "Bananas" },
  { id: 4, name: "Mangos" },
  { id: 5, name: "Lemons" },
  { id: 6, name: "Apricots", disabled: true }
]

suggestionsFilter (optional)

A function to filter suggestion items on; takes a suggestion item as the single argument.

If no function is supplied the default filter is applied. Default: null.

placeholderText (optional)

The input placeholder text displayed when no text has been entered. Default: 'Add new tag'.

removeButtonText (optional)

The title text to add to the remove selected tag button. Default 'Click to remove tag'.

autoresize (optional)

Boolean parameter to control whether the text-input should be automatically resized to fit its value. Default: true.

delimiters (optional)

Array of keys matching keyboard event key values. When a corresponding key is pressed, the preceding string is finalised as tag. Default: ['Enter', 'Tab'].

minQueryLength (optional)

How many characters are needed for suggestions to appear. Default: 2.

maxSuggestionsLength (optional)

Maximum number of suggestions to display. Default: 6.

classNames (optional)

Override the default class names. Defaults:

{
  root: 'react-tags',
  rootFocused: 'is-focused',
  selected: 'react-tags__selected',
  selectedTag: 'react-tags__selected-tag',
  selectedTagName: 'react-tags__selected-tag-name',
  search: 'react-tags__search',
  searchWrapper: 'react-tags__search-wrapper',
  searchInput: 'react-tags__search-input',
  suggestions: 'react-tags__suggestions',
  suggestionActive: 'is-active',
  suggestionDisabled: 'is-disabled'
}

onAddition (required)

Function called when the user wants to add a tag. Receives the tag.

function onAddition(tag) {
  // Add the tag { id, name } to the tag list
  tags.push(tag)
}

onDelete (required)

Function called when the user wants to delete a tag. Receives the tag index.

function onDelete(i) {
  // Delete the tag at index i
  tags.splice(i, 1)
}

onInput (optional)

Optional event handler when the input changes. Receives the current input value.

function onInput(input) {
  if (!this.state.busy) {
    this.setState({ busy: true })

    return fetch(`query=${input}`).then((result) => {
      this.setState({ busy: false })
    })
  }
}

onFocus (optional)

Optional event handler when the input receives focus. Receives no arguments.

onBlur (optional)

Optional event handler when focus on the input is lost. Receives no arguments.

onValidate (optional)

Optional validation function that determines if tag should be added to tags. Receives a tag object. Should return a boolean.

function onValidate(tag) {
  return tag.name.length >= 5;
}

addOnBlur (optional)

Creates a tag from the current input value when focus on the input is lost. Default: false.

allowNew (optional)

Allows users to add new (not suggested) tags. Default: false.

allowBackspace (optional)

Disables ability to delete the selected tags when backspace is pressed while focussed on the text input. Default: true.

tagComponent (optional)

Provide a custom tag component to render. Default: null.

suggestionComponent (optional)

Provide a custom suggestion component to render. Default: null.

inputAttributes (optional)

An object containing additional attributes that will be applied to the underlying text <input /> field.

As an example inputAttributes={{ maxLength: 10 }} would be applied as <input maxlength="10" … />. Note this prop won't overwrite existing attributes, it can only add new ones.

API

addTag(tag)

deleteTag(index)

clearInput()

Styling

It is possible to customize the look of the component the way you want it. An example can be found in /example/styles.css.

Development

The component is written in ES6 and uses Rollup as its build tool. Tests are written with Jasmine using JSDOM.

npm install
npm run dev # will open http://localhost:8080 and watch files for changes

Upgrading

To see all changes refer to the changelog.

Upgrading from 5.x to 6.x

• React 16.3 or above is now required.
• Event handlers and callbacks have been renamed to use on prefixes, e.g. the handleAddition() callback should now be called onAddition().
• The delimiters option is now an array of KeyboardEvent.key values and not KeyboardEvent.keyCode codes, e.g. [13, 9] should now be written as ['Enter', 'Tab']. See https://keycode.info/ for more information.
• The delimiterChars option has been removed, use the delimiters option instead.
• The autofocus option has been removed.

Upgrading from 4.x to 5.x

1. The delimiters option has been removed, any references to this will now be ignored.
2. The classNames option has been updated:

{
-  root: 'ReactTags',
-  tagInput: 'ReactTags__tagInput',
-  selected: 'ReactTags__selected',
-  tag: 'ReactTags__tag',
-  tagName: 'ReactTags__tagName',
-  suggestions: 'ReactTags__suggestions',
-  isActive: 'is-active',
-  isDisabled: 'is-disabled'
+  root: 'react-tags',
+  rootFocused: 'is-focused',
+  selected: 'react-tags__selected',
+  selectedTag: 'react-tags__selected-tag',
+  selectedTagName: 'react-tags__selected-tag-name',
+  search: 'react-tags__search',
+  searchInput: 'react-tags__search-input',
+  suggestions: 'react-tags__suggestions',
+  suggestionActive: 'is-active',
+  suggestionDisabled: 'is-disabled'
}