{"maintainers":[{"name":"anonymous","email":"vsync.design@gmail.com"}],"keywords":["tags","tagging","component","tag","ui"],"dist-tags":{"latest":"4.36.0"},"author":{"name":"Yair Even-Or","email":"vsync.design@gmail.com"},"description":"lightweight, efficient Tags input component in Vanilla JS / React / Angular [super customizable, tiny size & top performance]","readme":"

\n \n

\n Tagify - tags input component\n

\n\n

\n Transforms an input field or a textarea into a Tags component, in an easy, customizable way,\n with great performance and small code footprint, exploded with features.\n
\n Vanilla āš” React āš” Vue āš” Angular\n

\n\n

\n šŸ‘‰ See Many Examples šŸ‘ˆ\n

\n

\n\n

\n \n \n \n \n \n \n \n \n

\n\n

\n \n \n \n \n \n \n

\n\n## Table of Contents\n\n\n- [Table of Contents](#table-of-contents)\n- [Installation](#installation)\n - [Option 1 - import from CDN:](#option-1---import-from-cdn)\n - [Option 2 - import as a *Node module*:](#option-2---import-as-a-node-module)\n- [Basic Usage Examples](#basic-usage-examples)\n - [Debugging](#debugging)\n- [Features](#features)\n- [Building the project](#building-the-project)\n - [Output files:](#output-files)\n- [Adding tags dynamically](#adding-tags-dynamically)\n- [Output value](#output-value)\n - [Modify original input value format](#modify-original-input-value-format)\n- [Ajax whitelist](#ajax-whitelist)\n- [Persisted data](#persisted-data)\n- [Edit tags](#edit-tags)\n- [Validations](#validations)\n- [Drag \\& Sort](#drag--sort)\n - [Integration example:](#integration-example)\n- [DOM Templates](#dom-templates)\n - [Example of overriding the `tag` template:](#example-of-overriding-the-tag-template)\n- [Suggestions list](#suggestions-list)\n - [Example for a suggestion item alias](#example-for-a-suggestion-item-alias)\n - [Example whitelist:](#example-whitelist)\n- [Mixed-Content](#mixed-content)\n- [Single-Value](#single-value)\n- [React](#react)\n - [Update regarding `onChange` prop:](#update-regarding-onchange-prop)\n - [Updating the component's state](#updating-the-components-state)\n- [Vue](#vue)\n- [jQuery version](#jquery-version)\n - [`jQuery.tagify.js`](#jquerytagifyjs)\n- [HTML input \\& textarea attributes](#html-input--textarea-attributes)\n- [Caveats](#caveats)\n- [FAQ](#faq)\n- [CSS Variables](#css-variables)\n - [Suggestions Dropdown CSS variables](#suggestions-dropdown-css-variables)\n - [Full list of Tagify's SCSS variables](#full-list-of-tagifys-scss-variables)\n- [Methods](#methods)\n- [Events](#events)\n- [Hooks](#hooks)\n- [Settings](#settings)\n\n\n## Installation\n\n### Option 1 - import from CDN:\n\nPlace these lines before any other code which is (or will be) using *Tagify* ([Example here](https://jsbin.com/jekuqap/edit?html))\n```html\n\n\n\n```\n\n`Tagify` will then be available globally.\nTo load specific version use `@` - for example: `unpkg.com/@yaireo/tagify@3.1.0`\n\n### Option 2 - import as a *Node module*:\n```sh\nnpm i @yaireo/tagify --save\n```\n\n## Basic Usage Examples\n\n- Many demos with code examples can be [seen here](https://yaireo.github.io/tagify/)\n- [CodeSandbox live demo](https://codesandbox.io/s/simple-tagify-setup-6pfi2)\n\n\n\n```js\nimport Tagify from '@yaireo/tagify'\n\nvar inputElem = document.querySelector('input') // the 'input' element which will be transformed into a Tagify component\nvar tagify = new Tagify(inputElem, {\n // A list of possible tags. This setting is optional if you want to allow\n // any possible tag to be added without suggesting any to the user.\n whitelist: ['foo', 'bar', 'and baz', 0, 1, 2]\n})\n```\n\nThe above example shows the most basic `whitelist` array setting possible, with a mix\nof *Strings* and *Numbers* but the array also support Objects which has a must-have property of `value`:\n\n```js\nwhitelist: [{value: 'foo', id: '123', email: 'foo@whatever.com'}, ...]\n```\n\nThe `value` property is what will be used when actually defining the `value` property of the original input element (`inputElem` in the example above) which was transformed\ninto a *Tagify* component, and so when the form data is sent to the server, it will contain all the values (which are the selected tags in the component).\n\nFor selected tags to show a different text than what is defined in `value` for a whitelist item, see the `tagTextProp` [setting](#settings)\n\nāš ļø Important:\nDon't forget to **include `tagify.css`** file in your project.\nCSS location: `@yaireo/tagify/dist/tagify.css`\nSCSS location: `@yaireo/tagify/src/tagify.scss`\n[See SCSS usecase & example](https://github.com/yairEO/tagify/pull/282)\n\n### Debugging\nThere are several places in the source code which emits `console.warn` logs to help identify issues.\nThose will only work if `Tagify.logger.enabled` flag is set to `true`.\nTo disable the default logging, set the following global variable:\n\n\n```js\nwindow.TAGIFY_DEBUG = false\n\nvar tagify = new Tagify(...)\n```\n\n\n## Features\n* Can be applied to input & textarea elements\n* Supports [mix content](#mixed-content) (text and tags together)\n* Supports [single-value](#single-value) mode (like `\n```\n\n\n## Validations\nFor \"regular\" tags (not *mix-mode* or *select-mode*) the easiest way is to use the `pattern` setting and use a Regex, or\napply the `pattern` attribute directly on the `input` which will be \"transformed\" into a *Tagify* component (for vanilla code where the `input` tag is fully accessible to developers).\n\nIf the `pattern` setting does not meet your needs, use the [`validate` setting](#settings), which receives a *tag data object* as an argument and should return `true` if validation is passing, or `false`/`string` of not.\nA *string* may be returned as the reason of the validation failure so it would be printed as the `title` attribute of the invalid tag.\n\n[Here's an example](https://jsbin.com/rojixul/edit?js,output) for async validation for an added tag. The idea is to listen to `\"add\"` event,\nand when it fires, first set the tag to \"loading\" state, run an async call, and then set the *loading* state (of the tag) back to `false`.\nIf the custom async validation failed, call the `replaceTag` Tagify method and set the `__isValid` tag data property to the error string which will\nbe shown when hovering the tag.\n\n\nNote - there is a setting to keep invalid tags ([`keepInvalidTags`](#settings)) and if it's set to `true`, the user can see the reason for the invalidation by\nhovering the tag and see the browser's native tooltip via the `title` attribute:\n\n```js\n{\n empty : \"empty\",\n exceed : \"number of tags exceeded\",\n pattern : \"pattern mismatch\",\n duplicate : \"already exists\",\n notAllowed : \"not allowed\"\n}\n```\n\nThe texts for those (invalid tags) *titles* can be customized from the settings:\n\n```js\nnew Tagify(inputElement, {\n texts: {\n duplicate: \"Duplicates are not allowed\"\n }\n})\n```\n\nOr by directly manipulating the *Tagify* function *prototype*:\n\n```js\nTagify.prototype.TEXTS = {...Tagify.prototype.TEXTS, {duplicate: \"Duplicates are not allowed\"}}\n```\n\n## Drag & Sort\n\nTo be able to sort tags by dragging, a 3rd-party script is needed.\n\nI have made a very simple *drag & drop* (~`11kb` *unminified*) script which uses [HTML5 native API](https://developer.mozilla.org/en-US/docs/Web/API/HTML_Drag_and_Drop_API) and\nit is available to download via [NPM](https://www.npmjs.com/package/@yaireo/dragsort) or [Github](https://github.com/yairEO/dragsort)\nbut any other *drag & drop* script may work. I could not find on the whole internet a decent lightweight script.\n\n### [Integration example](https://codepen.io/vsync/pen/jOqYOVJ):\n\n```js\nvar tagify = new Tagify(inputElement)\n\n// bind \"DragSort\" to Tagify's main element and tell\n// it that all the items with the below \"selector\" are \"draggable\"\nvar dragsort = new DragSort(tagify.DOM.scope, {\n selector: '.'+tagify.settings.classNames.tag,\n callbacks: {\n dragEnd: onDragEnd\n }\n})\n\n// must update Tagify's value according to the re-ordered nodes in the DOM\nfunction onDragEnd(elm){\n tagify.updateValueByDOMTags()\n}\n```\n\n\n## DOM Templates\nIt's possible to control the templates for some of the HTML elements Tagify is using by\nmodifying the `settings.templates` Object with your own custom functions which **must return** an *HTML string*.\n\nAvailable templates are: `wrapper`, `input`, `tag`, `dropdown`, `dropdownItem`, `dropdownContent`, `dropdownHeader`, `dropdownFooter` and the optional `dropdownItemNoMatch`\nwhich is a special template for rendering a suggestion item (in the dropdown list) only if there were no matches found for the typed input, for example:\n\n```js\n// ...more tagify settings...\ntemplates: {\n dropdownItemNoMatch: data =>\n `
\n No suggestion found for: ${data.value}\n
`\n}\n```\n\n[View templates](https://github.com/yairEO/tagify/blob/master/src/parts/templates.js)\n\n### Example of overriding the `tag` template:\n\nEach template function is automatically bound with `this` pointing to the current *Tagify* instance.\nIt is imperative to preserve the class names and also the `this.getAttributes(tagData)` for proper functionality.\n\n```js\nnew Tagify(inputElem, {\n templates: {\n tag(tagData, tagify){\n return `\n \n
\n ${tagData[this.settings.tagTextProp] || tagData.value}\n
\n `,\n\n dropdownFooter(suggestions){\n var hasMore = suggestions.length - this.settings.dropdown.maxItems;\n\n return hasMore > 0\n ? ``\n : '';\n }\n }\n})\n```\n\n## Suggestions list\n\n

\n suggestions list dropdown\n

\n\nThe suggestions list is a *whitelist Array* of *Strings* or *Objects* which was set in the [settings](#settings) Object when the Tagify instance was created, and can be set later directly on the instance: `tagifyInstance.whitelist = [\"tag1\", \"tag2\", ...]`.\n\nThe suggestions dropdown will be appended to the document's `` element and will be rendered by default in a position below (bottom of) the Tagify element.\nUsing the keyboard arrows up/down will highlight an option from the list, and hitting the Enter key to select.\n\nIt is possible to tweak the list dropdown via 2 settings:\n\n - `enabled` - this is a numeral value that tells Tagify when to show the suggestions dropdown, when a minimum of N characters were typed.\n - `maxItems` - Limits the number of items the suggestions list will render\n\n```javascript\nvar input = document.querySelector('input'),\n tagify = new Tagify(input, {\n whitelist : ['aaa', 'aaab', 'aaabb', 'aaabc', 'aaabd', 'aaabe', 'aaac', 'aaacc'],\n dropdown : {\n classname : \"color-blue\",\n enabled : 0, // show the dropdown immediately on focus\n maxItems : 5,\n position : \"text\", // place the dropdown near the typed text\n closeOnSelect : false, // keep the dropdown open after selecting a suggestion\n highlightFirst: true\n }\n });\n```\n\n

Will render

\n\n```html\n
\n
\n
aaab
\n
aaabb
\n
aaabc
\n
aaabd
\n
aaabe
\n
\n
\n```\n\nBy default searching the suggestions is using [fuzzy-search](https://en.wikipedia.org/wiki/Approximate_string_matching) (see [settings](#settings)).\n\nIf you wish to assign *alias* to items (in your suggestion list), add the `searchBy` property to *whitelist* items you wish\nto have an *alias* for.\n\nIn the below example, typing a part of a string which is included in the `searchBy` property, for example *`land midd\"`* -\nthe suggested item which matches the value \"Israel\" will be rendered in the suggestions (dropdown) list.\n\n### [Example](https://yaireo.github.io/tagify/#section-extra-properties) for a suggestion item alias\n\n```javascript\nwhitelist = [\n ...\n { value:'Israel', code:'IL', searchBy:'holy land, desert, middle east' },\n ...\n]\n```\n\nAnother handy setting is `dropdown.searchKeys` which, like the above `dropdown.searchBy` setting, allows\nexpanding the search of any typed terms to more than the `value` property of the whitelist items (if items are a *Collection*).\n\n### Example whitelist:\n\n```javascript\n[\n {\n value : 123456,\n nickname : \"foo\",\n email : \"foo@mail.com\"\n },\n {\n value : 987654,\n nickname : \"bar\",\n email : \"bar@mail.com\"\n },\n ...more..\n]\n```\n\nModified `searchKeys` setting to also search in other keys:\n```javascript\n{\n dropdown: {\n searchKeys: [\"nickname\", \"email\"] // fuzzy-search matching for those whitelist items' properties\n }\n}\n```\n\n## Mixed-Content\n\n[See demo here](https://yaireo.github.io/tagify/#section-mix)\n\nThis feature must be toggled using these [settings](#settings):\n\n```js\n{\n // mixTagsInterpolator: [\"{{\", \"}}\"], // optional: interpolation before & after string\n mode: 'mix', // <-- Enable mixed-content\n pattern: /@|#/ // <-- Text starting with @ or # (if single, String can be used here instead of Regex)\n}\n```\n\nWhen mixing text with tags, the original textarea (or input) element will have a value as follows:\n\n [[cartman]]ā  and [[kyle]]ā  do not know [[Homer simpson]]ā \n\nIf the initial value of the textarea or input is formatted as the above example, Tagify will try to\nautomatically convert everything between `[[` & `]]` to a tag, if tag exists in the *whitelist*, so make\nsure when the Tagify instance is initialized, that it has tags with the correct `value` property that match\nthe same values that appear between `[[` & `]]`.\n\nApplying the setting `dropdown.position:\"text\"` is encouraged for mixed-content tags, because the suggestions list\nlooks weird when there is already a lot of content on multiple lines.\n\nIf a tag does not exist 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.\n\n## Single-Value\n\nSimilar to native ``'s element `name` attribute\nvalue | String/Array | āœ” | Initial value.\ndefaultValue | String/Array | | Same as `value` prop\nplaceholder | String | āœ” | placeholder text for the component\nreadOnly | Boolean | āœ” | Toggles `readonly` state. With capital `O`.\ntagifyRef | Object | | `useRef` hook refference for the component inner instance of vanilla *Tagify* (for methods access)\nshowDropdown | Boolean/String | āœ” | if `true` shows the suggestions dropdown. if assigned a String, show the dropdown pre-filtered.\nloading | Boolean | āœ” | Toggles `loading` state for the whole component\nwhitelist | Array | āœ” | Sets the `whitelist` which is the basis for the suggestions dropdown & autocomplete\nclassName | String | | Component's optional class name to be added\nInputMode | String | | `\"textarea\"` will create a `