|
1 | 1 | # react-tags |
2 | | -> Simple tagging component for React projects. |
| 2 | + |
| 3 | +![npm][npm-version-image] |
| 4 | +[![peerDependency Status][peer-dep-image]][peer-dep-url] |
| 5 | +[![devDependency Status][dev-dep-image]][dev-dep-url] |
| 6 | + |
| 7 | +> Simple tagging component for React projects. |
| 8 | +
|
| 9 | +## Getting Started ## |
| 10 | + |
| 11 | +#### Installation |
| 12 | +From the root of your project. |
| 13 | +```sh |
| 14 | +npm install react-tags --save |
| 15 | +``` |
| 16 | + |
| 17 | +## Usage |
| 18 | +Simple implementation of tags. See [options available](#options) below. |
| 19 | +```js |
| 20 | +import React, { Component } from 'react'; |
| 21 | +import { render } from 'react-dom'; |
| 22 | +import Tags from 'react-tags'; |
| 23 | + |
| 24 | +class Application extends Component{ |
| 25 | + constructor(props){ |
| 26 | + super(props); |
| 27 | + |
| 28 | + this.state = { |
| 29 | + tags: ['hello', 'world'] |
| 30 | + } |
| 31 | + } |
| 32 | + |
| 33 | + onTagsChange(tags){ |
| 34 | + console.log(`new tags: ${tags}`); |
| 35 | + } |
| 36 | + |
| 37 | + render(){ |
| 38 | + return ( |
| 39 | + <div> |
| 40 | + <Tags |
| 41 | + initialTags={this.state.tags} |
| 42 | + placeholder="Add a tag" |
| 43 | + change={this.onTagsChange} /> |
| 44 | + </div> |
| 45 | + ); |
| 46 | + } |
| 47 | +} |
| 48 | + |
| 49 | +render(<Application />, document.getElementById('application')); |
| 50 | +``` |
| 51 | + |
| 52 | +<a name="options"></a> |
| 53 | +#### Options |
| 54 | +* **[`initialTags`](#initialTags)** |
| 55 | +* **[`placeholder`](#placeholder)** |
| 56 | +* **[`change`](#change)** |
| 57 | +* **[`added`](#added)** |
| 58 | +* **[`readOnly`](#readOnly)** |
| 59 | +* **[`removeTagWithDeleteKey`](#removeTagWithDeleteKey)** |
| 60 | +* **[`removeTagIcon`](#removeTagIcon)** |
| 61 | +* **[`allowDupes`](#allowDupes)** |
| 62 | +* **[`id`](#id)** |
| 63 | + |
| 64 | +<a name="initialTags"></a> |
| 65 | +##### initialTags ~ optional ~ default `[]` |
| 66 | +An `array` of tags to be passed in and rendered right away in the component |
| 67 | +```js |
| 68 | +const tags = ['hello', 'world']; |
| 69 | + |
| 70 | +<Tags initialTags={tags} /> |
| 71 | +``` |
| 72 | + |
| 73 | +<a name="placeholder"></a> |
| 74 | +##### placeholder ~ optional ~ default `null` |
| 75 | +A `string` used as placeholder text in the tags input field |
| 76 | +```js |
| 77 | +<Tags placeholder="Add a tag" /> |
| 78 | +``` |
| 79 | + |
| 80 | +<a name="change"></a> |
| 81 | +##### change ~ optional |
| 82 | +A `function` fired anytime there is a change - returns the new `array` of tags |
| 83 | +```js |
| 84 | +onTagsChange(tags){ |
| 85 | + console.log(`new tags: ${tags}`); |
| 86 | +} |
| 87 | + |
| 88 | +<Tags change={this.onTagsChange} /> |
| 89 | +``` |
| 90 | + |
| 91 | +<a name="added"></a> |
| 92 | +##### added ~ optional |
| 93 | +A `function` fired when a new tag is added - returns a `string` of the new tag |
| 94 | +```js |
| 95 | +onTagAdded(tag){ |
| 96 | + console.log(`new tag: ${tags}`); |
| 97 | +} |
| 98 | + |
| 99 | +<Tags added={this.onTagAdded} /> |
| 100 | +``` |
| 101 | + |
| 102 | +<a name="removed"></a> |
| 103 | +##### removed ~ optional |
| 104 | +A `function` fired when a new tag is deleted - returns a `string` of the tag that was deleted |
| 105 | +```js |
| 106 | +onTagRemoved(tag){ |
| 107 | + console.log(`deleted tag: ${tag}`); |
| 108 | +} |
| 109 | + |
| 110 | +<Tags removed={this.onTagRemoved} /> |
| 111 | +``` |
| 112 | + |
| 113 | +<a name="readOnly"></a> |
| 114 | +##### readOnly ~ optional ~ default `false` |
| 115 | +A `boolean` that sets the tag component to read only mode. No adding or removing tags and pointer events |
| 116 | +```js |
| 117 | +<Tags readOnly={true} /> |
| 118 | +``` |
| 119 | + |
| 120 | +<a name="removeTagWithDeleteKey"></a> |
| 121 | +##### removeTagWithDeleteKey ~ optional ~ default `true` |
| 122 | +A `boolean` that allows tags to be removed with the delete key when the input field is empty |
| 123 | +```js |
| 124 | +<Tags removeTagWithDeleteKey={true} /> |
| 125 | +``` |
| 126 | + |
| 127 | +<a name="removeTagIcon"></a> |
| 128 | +##### removeTagIcon ~ optional ~ default `"x"` |
| 129 | +The `element` to be used for the delete icon |
| 130 | +```js |
| 131 | +const removeIcon = () => { |
| 132 | + return ( |
| 133 | + <i class="my-custom-icon"></i> |
| 134 | + ); |
| 135 | +} |
| 136 | + |
| 137 | +<Tags removeTagsIcon={removeIcon()} /> |
| 138 | +``` |
| 139 | + |
| 140 | +<a name="allowDupes"></a> |
| 141 | +##### allowDupes ~ optional ~ default `false` |
| 142 | +A `boolean` that allows tags to be added more than once |
| 143 | +```js |
| 144 | +<Tags allowDupes={false} /> |
| 145 | +``` |
| 146 | + |
| 147 | +<a name="id"></a> |
| 148 | +##### id ~ optional ~ default `null` |
| 149 | +The `string` to be used for the ID of the component |
| 150 | +```js |
| 151 | +<Tags id="my-tags-component" /> |
| 152 | +``` |
| 153 | + |
| 154 | +## Styling |
| 155 | +#### Installation |
| 156 | +Import the main SCSS file in to your application SCSS files |
| 157 | +```scss |
| 158 | +@import "node_modules/react-tags/src/scss/react-tags"; |
| 159 | +``` |
| 160 | + |
| 161 | +There are a few variables set to `!default` that can be overriden. If you need to change it more just override the actual styles. |
| 162 | + |
| 163 | +**Any overriden variables needs to go above the `@import` statement to take effect** |
| 164 | +```scss |
| 165 | +//-- Global UI |
| 166 | +$tag-base-height |
| 167 | +$tag-base-font-size |
| 168 | +$tag-base-border-radius |
| 169 | +$tag-base-font-color |
| 170 | +$tag-base-margin |
| 171 | +$tag-base-font-family |
| 172 | + |
| 173 | +//-- Tags |
| 174 | +$tag-background-color |
| 175 | +$tag-background-hover-color |
| 176 | +$tag-remove-color |
| 177 | +$tag-remove-font-size |
| 178 | +$tag-remove-hover-color |
| 179 | + |
| 180 | +//-- Input |
| 181 | +$tag-input-bg-color |
| 182 | +$tag-input-border |
| 183 | +$tag-input-placeholder-color |
| 184 | +``` |
| 185 | + |
| 186 | +If you don't care to override variables and just want to override actual styles you may choose to import the minified compiled version of the css instead |
| 187 | +```scss |
| 188 | +@import "node_modules/react-tags/dist/react-tags.min.css"; |
| 189 | +``` |
| 190 | + |
| 191 | +## License ## |
| 192 | + |
| 193 | + * [MIT License](http://www.opensource.org/licenses/mit-license.php) |
| 194 | + |
| 195 | +[npm-version-image]: https://img.shields.io/npm/v/npm.svg?maxAge=2592000 |
| 196 | +[dev-dep-image]: https://david-dm.org/JFusco/react-tags/dev-status.svg |
| 197 | +[dev-dep-url]: https://david-dm.org/JFusco/react-tags#info=devDependencies |
| 198 | +[peer-dep-image]: https://david-dm.org/JFusco/react-tags/peer-status.svg |
| 199 | +[peer-dep-url]: https://david-dm.org/JFusco/react-tags#info=peerDependencies |
0 commit comments