{"id":13813240,"url":"https://github.com/bevacqua/insignia","last_synced_at":"2025-05-16T18:09:37.588Z","repository":{"id":25780767,"uuid":"29219178","full_name":"bevacqua/insignia","owner":"bevacqua","description":"🔖 Customizable tag input. Progressive. No non-sense!","archived":false,"fork":false,"pushed_at":"2016-07-13T15:18:42.000Z","size":238,"stargazers_count":672,"open_issues_count":4,"forks_count":26,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-05-12T18:57:51.288Z","etag":null,"topics":["autocomplete","component","es6","front-end","javascript","vanilla"],"latest_commit_sha":null,"homepage":"https://bevacqua.github.io/insignia","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bevacqua.png","metadata":{"files":{"readme":"readme.markdown","changelog":"changelog.markdown","contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-01-14T00:32:53.000Z","updated_at":"2025-03-23T14:42:23.000Z","dependencies_parsed_at":"2022-09-09T13:21:55.409Z","dependency_job_id":null,"html_url":"https://github.com/bevacqua/insignia","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bevacqua%2Finsignia","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bevacqua%2Finsignia/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bevacqua%2Finsignia/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bevacqua%2Finsignia/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bevacqua","download_url":"https://codeload.github.com/bevacqua/insignia/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254101572,"owners_count":22014903,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autocomplete","component","es6","front-end","javascript","vanilla"],"created_at":"2024-08-04T04:01:08.990Z","updated_at":"2025-05-16T18:09:37.541Z","avatar_url":"https://github.com/bevacqua.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Insignia\n\n\u003e Customizable tag input. Progressive. No non-sense!\n\nBrowser support includes every sane browser and **IE7+**.\n\n# Demo!\n\nYou can see a [live demo here][5].\n\n[![screenshot.png][4]][5]\n\n# Inspiration\n\nI needed a tag input that was progressively enhanced, fast, easy to use, and reliable. Tag inputs I stumbled upon were too bloated, too dependant on JavaScript, or provided an unfriendly human experience.\n\nThe goal is to produce a framework-agnostic tag input editor that is easily integrated into your favorite MVC framework, that doesn't translate into a significant addition to your codebase, and that's **enjoyable to work with**. Insignia shares the modular design philosophy of [Rome, the datetime picker][2].\n\n# Features\n\n- Small and focused\n- Natural keyboard navigation\n- Progressively enhanced\n- Extensive browser support\n\n# Install\n\nYou can get it on npm.\n\n```shell\nnpm install insignia --save\n```\n\nOr bower, too.\n\n```shell\nbower install insignia --save\n```\n\n# Usage\n\nInsignia demands one thing of you: **the input must have no siblings.**\n\n```html\n\u003cdiv\u003e\n  \u003cinput id='insigificant' /\u003e\n\u003c/div\u003e\n```\n\nIf client-side JavaScript never executes, because its disabled or too slow [_(on intermittent mobile network connections, for example)_][3], you should treat user input as a delimited list of tags. When JavaScript does execute, you should consider sending tags as a single string and splitting them on the server-side, for consistency.\n\n# `insignia.find(input)`\n\nRetrieves a previously created instance of Insignia associated with the provided `input`. Returns `null` if none can be found.\n\n# `insignia(input, options={})`\n\nInsignia exposes a function to turn an input into a tag list input. Empty spans will be added on both sides of your input element.\n\nA few options may be provided. They are detailed below.\n\n### `free`\n\nDefaults to `true`. When this flag is turned off, tags can't be edited by hand but they can still be deleted entirely using backspace. Tags would have to be added programmatically.\n\n## `deletion`\n\nWhen `true`, humans will be able to delete individual tags by clicking on an icon.\n\n## `delimiter`\n\nThe separator between tags. Defaults to `' '`. Must be a single character.\n\n## `preventInvalid`\n\nThis option will prevent tags identified as invalid from being added. By default this is turned off and they just get a `nsg-invalid` CSS class.\n\n## `validate(value)`\n\nA method that validates whether the user input `value` constitutes a valid tag. Useful to filter out duplicates. Defaults to the method below, that does exactly that. Note that in the code below, `toy` is the API returned by calling `insignia(el)`.\n\n```js\nfunction validate (value) {\n  return toy.findItem(value) === null;\n}\n```\n\nNote that `tags` is only a copy and modifying it won't affect the list of tags.\n\n## `render(container, item)`\n\nA method that's called whenever a tag should be rendered. Defaults to setting `getText(item)` as the container's text.\n\n## `getText`\n\nWhen you have complex data items from autocomplete, you need to set `getText` to read the value that should be used as a display value.\n\n## `getValue`\n\nWhen you have complex data items from autocomplete, you need to set `getValue` to read the value that should be used as each tag's value.\n\n## `convertOnBlur`\n\nBy default, tags are converted whenever the `blur` event fires on elements other than `input`. Set to `false` to disable.\n\n# Instance API\n\nWhen you call `insignia(input, options)`, you'll get back a tiny API to interact with the instance. Calling `insignia` repeatedly on the same DOM element will have no effect, and it will return the same API object.\n\n## `.addItem(data)`\n\nAdds an item to the input. The `data` parameter could be a string or a complex object, depending on your instance configuration.\n\n## `.findItem(data)`\n\nFinds an item by its `data` string or object.\n\n## `.findItemIndex(data)`\n\nReturn the index of the first item found by its `data` string or object.\n\n## `.findItemByElement(el)`\n\nFinds an item by its `.nsg-tag` DOM element.\n\n## `.removeItem(data)`\n\nRemoves an item from the input. The item is found using the `data` string or object.\n\n## `.removeItemByElement(el)`\n\nRemoves an item from the input. The item is found using a `.nsg-tag` DOM element.\n\n## `.value()`\n\nReturns the list of valid tags as an array.\n\n## `.allValues()`\n\nReturns the list of tags as an array including invalid tags.\n\n## `.refresh()`\n\nWhen changing the value of the `el` input by hand, call `.refresh()` to convert tags again.\n\n## `.destroy()`\n\nRemoves all event listeners, CSS classes, and DOM elements created by insignia. The input's `value` is set to the output of `.value()`. Once the instance is destroyed it becomes useless, and you'll have to call `insignia(input, options)` once again if you want to restore the behavior.\n\n## Instance Events\n\nThe instance API comes with a few events.\n\nEvent     | Arguments    | Description\n----------|--------------|------------\n`add`     | `data`, `el` | Emitted whenever a new item is added to the list\n`remove`  | `data`       | Emitted whenever an item is removed from the list\n`invalid` | `data`, `el` | Emitted whenever an invalid item is added to the list\n\nYou can listen to these events using the following API.\n\n```js\nconst toy = insignia(el);\ntoy.on('add', data =\u003e console.log(data)); // listen to an event\ntoy.once('invalid', data =\u003e throw new Error('invalid data')); // listener discarded after one execution\n\ntoy.on('add', added);\ntoy.off('add', added); // removes `added` listener\n\nfunction added (data) {\n  console.log(data);\n}\n```\n\n# License\n\nMIT\n\n[1]: http://stackoverflow.com/questions/ask\n[2]: https://github.com/bevacqua/rome\n[3]: http://ponyfoo.com/articles/stop-breaking-the-web\n[4]: http://i.imgur.com/mhy3Fv9.png\n[5]: http://bevacqua.github.io/insignia\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbevacqua%2Finsignia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbevacqua%2Finsignia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbevacqua%2Finsignia/lists"}