Tagify - tags input component
Transforms an input field or a textarea into a Tags component , in an easy, customizable way,
with great performance and small code footprint, exploded with features.
Vanilla ⚡ React ⚡ Vue ⚡ Angular
## Table of Contents
* [Installation](#installation)
* [What can Tagify do](#features)
* [Building the project](#building-the-project)
* [Adding tags dynamically](#adding-tags-dynamically)
* [Output value](#output-value)
* [Ajax whitelist](#ajax-whitelist)
* [Edit tags](#edit-tags)
* [Drag & Sort](#drag--sort)
* [DOM Templates](#dom-templates)
* [Suggestions selectbox](#suggestions-selectbox)
* [Tags mixed with text](#mixed-content)
* [Single-Value Only](#single-value)
* [React wrapper](#react)
* [Angular wrapper](#angular)
* [Vue Example](https://codesandbox.io/s/tagify-tags-component-vue-example-l8ok4)
* [jQuery version](#jquery-version)
* [FAQ](#FAQ)
* [CSS Variables](#css-variables)
* [Methods](#methods)
* [Events](#events)
* [Hooks](#hooks)
* [Settings](#settings)
## Installation
```sh
npm i @yaireo/tagify --save
```
### Usage (in your bundle):
[live demo using Parcel as bundler](https://codesandbox.io/s/simple-tagify-setup-6pfi2)
```js
import Tagify from '@yaireo/tagify'
var tagify = new Tagify(...)
```
> Don't forget to **include `tagify.css`** file in your project.
> CSS location: `@yaireo/tagify/dist/tagify.css`
> SCSS location: `@yaireo/tagify/src/tagify.scss`
> [See SCSS usecase & example](https://github.com/yairEO/tagify/pull/282)
## Features
* Can be applied on input & textarea elements
* Supports [mix content](#mixed-content) (text and tags together)
* Supports [single-value](#single-value) mode (like ``)
* Supports whitelist/blacklist
* Supports Templates for: component wrapper , tag items , suggestion list & suggestion items
* Shows suggestions selectbox (flexiable settings & styling) at *full (component) width* or *next to* the typed texted (caret)
* Allows setting suggestions' [aliases](#example-for-a-suggestion-item-alias) for easier fuzzy-searching
* Auto-suggest input as-you-type with ability to auto-complete
* Can paste in multiple values: `tag 1, tag 2, tag 3` or even newline-separated tags
* Tags can be created by Regex delimiter or by pressing the "Enter" key / focusing of the input
* Validate tags by Regex pattern
* Tags may be [editable](#edit-tags) (double-click)
* ARIA accessibility support(Component too generic for any meaningful ARIA)
* Supports read-only mode to the whole componenet or per-tag
* Each tag can have any properties desired (class, data-whatever, readonly...)
* Automatically disallow duplicate tags (vis "settings" object)
* Has built-in CSS loader, if needed (Ex. AJAX whitelist pulling)
* Tags can be trimmed via `hellip` by giving `max-width` to the `tag` element in your `CSS`
* Easily change direction to RTL (via the SCSS file)
* Internet Explorer - A polyfill script should be used: `tagify.polyfills.min.js` (in `/dist`)
* Many useful custom [events](#events)
* Original input/textarea element values kept in sync with Tagify
## Building the project
Simply run `gulp` in your terminal, from the project's path ([Gulp](https://gulpjs.com) should be installed first).
Source files are this path: `/src/`
Output files, which are automatically generated using Gulp, are in: `/dist/`
The rest of the files are most likely irrelevant.
## Adding tags dynamically
```javascript
var tagify = new Tagify(...);
tagify.addTags(["banana", "orange", "apple"])
// or add tags with pre-defined propeties
tagify.addTags([{value:"banana", color:"yellow"}, {value:"apple", color:"red"}, {value:"watermelon", color:"green"}])
```
## Output value
There are two possible ways to get the value of the tags:
1. Access the tagify's instance's `value` prop: `tagify.value` (Array of tags)
2. Access the *original* input's value: `inputElm.value` (Stringified Array of tags)
The most common way is to simply listen to the `change` event on the *original input*
```javascript
var inputElm = document.querySelector,
tagify = new Tagify (inputElm);
inputElm.addEventListener('change', onChange)
function onChange(e){
// outputs a String
console.log(e.target.value)
}
```
### [Modify original input value format](https://jsbin.com/paxijaj/edit?html,js,output)
Default format is a JSON string:loading
state is controlled by the method `tagify.loading` which accepts `true` or `false` as arguments.
Below is a basic example using the `fetch` API. I advise to abort the last request on any input before starting a new request.
Example:
```javascript
var input = document.querySelector('input'),
tagify = new Tagify(input, {whitelist:[]}),
controller; // for aborting the call
// listen to any keystrokes which modify tagify's input
tagify.on('input', onInput)
function onInput( e ){
var value = e.detail.value;
tagify.settings.whitelist.length = 0; // reset the whitelist
// https://developer.mozilla.org/en-US/docs/Web/API/AbortController/abort
controller && controller.abort();
controller = new AbortController();
// show loading animation and hide the suggestions dropdown
tagify.loading(true).dropdown.hide.call(tagify)
fetch('http://get_suggestions.com?value=' + value, {signal:controller.signal})
.then(RES => RES.json())
.then(function(whitelist){
// update inwhitelist Array in-place
tagify.settings.whitelist.splice(0, whitelist.length, ...whitelist)
tagify.loading(false).dropdown.show.call(tagify, value); // render the suggestions dropdown
})
}
```
## Edit tags
Tags which aren't `read-only` can be edited by double-clicking them (by default)
or by changing the `editTags` *setting* to `1`, making tags editable by single-clicking them.
The value is saved on `blur` or by pressing `enter` key. Pressing `Escape` will revert the change trigger `blur`.
ctrl z will revert the change if an edited tag was marked as not valid (perhaps duplicate or blacklisted)
To prevent *all* tags from being allowed to be editable, set the `editTags` setting to `false` (or `null`).Will render
```html
aaab
aaabb
aaabc
aaabd
aaabe
```
By default searching the suggestions is using [fuzzy-search](https://en.wikipedia.org/wiki/Approximate_string_matching) (see [settings](#settings)).
If you wish to assign *alias* to items (in your suggestion list), add the `searchBy` property to *whitelist* items you wish
to have an *alias* for.
In the below example, typing a part of a string which is included in the `searchBy` property, for example *`land midd"`* -
the suggested item which match the value "Israel" will be rendered in the suggestions (dropdown) list.
### [Example](https://yaireo.github.io/tagify/#section-extra-properties) for a suggestion item alias
```javascript
whitelist = [
...
{ value:'Israel', code:'IL', searchBy:'holy land, desert, middle east' },
...
]
```
Another handy setting is `dropdown.searchKeys` which, like the above `dropdown.searchBy` setting, allows
expanding the search of any typed terms to more than the `value` property of the whitelist items (if items are a *Collection*).
### Example whitelist:
```javascript
[
{
value : 123456,
nickname : "foo",
email : "foo@mail.com"
},
{
value : 987654,
nickname : "bar",
email : "bar@mail.com"
},
...more..
]
```
// setting to search in other keys:
```javascript
{
dropdown: {
searchKeys: ["nickname", "email"] // fuzzy-search matching for those whitelist items' properties
}
}
```
## Mixed-Content
> To use this feature it must be toggled - see [settings](#settings).
When mixing text with tags, the original textarea (or input) element will have a value as follows:
[[cartman]] and [[kyle]] do not know [[Homer simpson]]
If the inital value of the textarea or input is formatted as the above example, tagify will try to
automatically convert everything between `[[` & `]]` to a tag, if tag exists in the *whitelist*, so make
sure when the Tagify instance is initialized, that it has tags with the correct `value` property that match
the same values that appear between `[[` & `]]`.
Applying the setting `dropdown.position:"text"` is encouraged for mixed-content tags, because the suggestions list
will be rendered right next to the caret location and not the the bottom of the Tagify componenet, which might look
weird when there is already a lot of content at multiple lines.
If a tag does not exists in the *whitelist*, it may be created by the user and all you should do is listen to the `add` event and update your local/remote state.
## Single-Value
Similar to native `` element, but allows typing text as value.
## React
See [**live demo**](https://codesandbox.io/s/tagify-react-wrapper-oempc) for React integration examples.
A Tagify React component is exported from [`react.tagify.js`](https://github.com/yairEO/tagify/blob/master/dist/react.tagify.js):
> Note: You will need to inport Tagify's CSS also, either by javasceript or by SCSS `@import` (which is preferable)
```javascript
import Tags from "@yaireo/tagify/dist/react.tagify" // React-wrapper file
import "@yaireo/tagify/dist/tagify.css" // Tagify CSS
const App = () => {
return (
(e.persist(), console.log("CHANGED:", e.target.value))}
/>
)
})
```
To gain full access to Tagify's (instance) inner methods, A custom `ref` can be used:
```jsx
` component is a shorthand for ``
#### Updating the component's state
The `settings` prop is **only used once** in the initialization process, please do not update it afterwards.
---
📖 List of (React) props for the <Tags/> component
Prop | Type | Updatable | Info
----------------------- | ------------------------- |:---------:| -----------------------------------------------------------
settings | Object | | See [*settings* section](#settings)
name | String | ✔ | `String/Array | ✔ | Initial value.
defaultValue | String/Array | | Only affects the hidden `String | ✔ | placeholder text for the component
readOnly | Boolean | ✔ | Toggles `readonly` state. With capital `O`.
tagifyRef | Object | | `useRef` hook refference for the component inner instance of vailla *Tagify* (for methods access)
showFilteredDropdown | Boolean/String | ✔ | if `true` shows the suggestions dropdown. if assigned a String, show the dropdown pre-filtered.
loading | Boolean | ✔ | Toggles `loading` state for the whole component
whitelist | Array | ✔ | Sets the `whitelist` which is the basis for the suggestions dropdown & autocomplete
className | String | | Component's optional class name to be added
InputMode | String | | `"textarea"` will create a ` 
