js/TagSelect.js/README.md

   1 # TagSelect.js
   2
   3 ## Overview
   4
   5 HTML5-based input for typing lists of tags, tokens, or other discrete values.
   6
   7 No dependencies required. 6kb gzipped.
   8
   9 ![screenshot](https://dl.dropboxusercontent.com/u/42869844/LTS/TagSelect.gif)
  10
  11 Features:
  12
  13 * Built-in validation, with visual feedback on unexpected values.
  14 * Full keyboard/cursor support (you can type anywhere in the input).
  15 * Full copy/paste support.
  16
  17 Currently, all non-word characters are treated as tag dividers. More separator options may be added in the future.
  18
  19 > **Compatibility:** Only modern browsers are supported. Some of the nicer features of this plugin (copy/paste support, native selection and cursor movement) aren't realistic on older browsers.
  20
  21 ***
  22
  23 ## Quickstart (Scripts)
  24
  25 Include the files from `dist/` in your project. Example:
  26
  27 ```html
  28 <link rel="stylesheet" href="tagselect.min.css">
  29 <script src="tagselect.min.js"></script>
  30 ```
  31
  32 Next, you can use the plugin in your own JavaScript. If you have an element with the ID 'my-input':
  33
  34 ```html
  35 <div id="my-input"></div>
  36 ```
  37
  38 ```javascript
  39 var element = document.querySelector('#my-input');
  40 var tags = new TagSelect(element, {
  41     options: ['Red', 'Green', 'Blue', 'Yellow', 'Orange', 'Magenta']
  42 });
  43 ```
  44
  45 ## Quickstart (NPM + Browserify / Webpack)
  46
  47 Add the dependency:
  48
  49 ```bash
  50 npm install --save TagSelect.js
  51 ```
  52
  53 And use it in your script:
  54
  55 ```javascript
  56 var TagSelect = require('TagSelect.js');
  57
  58 var element = document.querySelector('#my-input');
  59 var tags = new TagSelect(element, {
  60     options: ['Red', 'Green', 'Blue', 'Yellow', 'Orange', 'Magenta']
  61 });
  62 ```
  63
  64 ### Methods
  65
  66 ```javascript
  67 /* .get()
  68 *************************/
  69 var selected = tags.get();
  70 // => ['Magenta, 'Yellow']
  71
  72 /* .set()
  73 *************************/
  74 tags.set(['Orange']);
  75
  76 /* .on()
  77 *************************/
  78 tags.on('change', function () {
  79     console.log('Tags updated!');
  80     console.log(tags.get());
  81 })
  82 ```
  83
  84 ## Contributing
  85
  86 ### Development
  87
  88 To get started, you'll need install the development dependencies:
  89
  90 ```
  91 npm install
  92 ```
  93
  94 Development tasks, like compiling [Sass](http://sass-lang.com/) and minifying JavaScript, are handled by [NPM scripts](https://docs.npmjs.com/misc/scripts).
  95
  96 ```bash
  97 # Run a local development server, recompiling files on update.
  98 npm run dev
  99
 100 # Rebuild all CSS and JS.
 101 npm run build
 102
 103 # Bump the version, commit the dist/, and release on NPM.
 104 npm version [ major | minor | patch ]
 105 ```