|
0
|
1 # Feather
|
|
|
2
|
|
|
3 [](https://travis-ci.org/colebemis/feather)
|
|
|
4 [](https://www.npmjs.com/package/feather-icons)
|
|
|
5 [](https://npm-stat.com/charts.html?package=feather-icons&from=2017-06-01)
|
|
|
6 [](https://codeclimate.com/github/colebemis/feather)
|
|
|
7 [](https://cdnjs.com/libraries/feather-icons)
|
|
|
8
|
|
|
9 ## What is Feather?
|
|
|
10
|
|
|
11 Feather is a collection of **simply beautiful open source icons**. Each icon is designed on a 24x24 grid with an emphasis on simplicity, consistency and readability.
|
|
|
12
|
|
|
13 **[feathericons.com](https://feathericons.com)**
|
|
|
14
|
|
|
15 ```
|
|
|
16 npm install feather-icons
|
|
|
17 ```
|
|
|
18
|
|
|
19 ## Table of Contents
|
|
|
20
|
|
|
21 * [Quick Start](#quick-start)
|
|
|
22 * [Usage](#usage)
|
|
|
23 * [Client-side JavaScript](#client-side-javascript)
|
|
|
24 * [Node](#node)
|
|
|
25 * [API Reference](#api-reference)
|
|
|
26 * [`feather.icons`](#feathericons)
|
|
|
27 * [`feather.toSvg()`](#feathertosvgkey-options)
|
|
|
28 * [`feather.replace()`](#featherreplaceoptions)
|
|
|
29 * [Roadmap](#roadmap)
|
|
|
30 * [Contributing](#contributing)
|
|
|
31 * [Related Projects](#related-projects)
|
|
|
32 * [License](#license)
|
|
|
33
|
|
|
34 ## Quick Start
|
|
|
35
|
|
|
36 Start with this [CodePen Template](https://codepen.io/pen?template=WOJZdM) to begin prototyping with Feather in the browser.
|
|
|
37
|
|
|
38 Or copy and paste the following code snippet into a blank `html` file.
|
|
|
39
|
|
|
40 ```html
|
|
|
41 <!DOCTYPE html>
|
|
|
42 <html lang="en">
|
|
|
43 <title></title>
|
|
|
44 <script src="https://unpkg.com/feather-icons/dist/feather.min.js"></script>
|
|
|
45 <body>
|
|
|
46
|
|
|
47 <!-- example icon -->
|
|
|
48 <i data-feather="circle"></i>
|
|
|
49
|
|
|
50 <script>
|
|
|
51 feather.replace()
|
|
|
52 </script>
|
|
|
53 </body>
|
|
|
54 </html>
|
|
|
55 ```
|
|
|
56
|
|
|
57 ## Usage
|
|
|
58
|
|
|
59 At its core, Feather is a collection of [SVG](https://svgontheweb.com/#svg) files. This means that you can use Feather icons in all the same ways you can use SVGs (e.g. `img`, `background-image`, `inline`, `object`, `embed`, `iframe`). Here's a helpful article detailing the many ways SVGs can be used on the web: [SVG on the Web – Implementation Options](https://svgontheweb.com/#implementation)
|
|
|
60
|
|
|
61 The following are additional ways you can use Feather.
|
|
|
62
|
|
|
63 ### Client-side JavaScript
|
|
|
64
|
|
|
65 #### 1. Install
|
|
|
66
|
|
|
67 > **Note:** If you intend to use Feather with a CDN, you can skip this installation step.
|
|
|
68
|
|
|
69 Install with [npm](https://docs.npmjs.com/getting-started/what-is-npm).
|
|
|
70
|
|
|
71 ```
|
|
|
72 npm install feather-icons --save
|
|
|
73 ```
|
|
|
74
|
|
|
75 Or just copy [`feather.js`](https://unpkg.com/feather-icons/dist/feather.js) or [`feather.min.js`](https://unpkg.com/feather-icons/dist/feather.min.js) into your project directory. You don't need both `feather.js` and `feather.min.js`.
|
|
|
76
|
|
|
77 #### 2. Include
|
|
|
78
|
|
|
79 Include `feather.js` or `feather.min.js` with a `<script>` tag. These files are located in the `dist` directory of the npm package.
|
|
|
80
|
|
|
81 ```html
|
|
|
82 <script src="path/to/dist/feather.min.js"></script>
|
|
|
83 ```
|
|
|
84
|
|
|
85 Or load the script from a CDN provider.
|
|
|
86
|
|
|
87 ```html
|
|
|
88 <!-- choose one -->
|
|
|
89 <script src="https://cdn.jsdelivr.net/npm/feather-icons/dist/feather.min.js"></script>
|
|
|
90 <script src="https://unpkg.com/feather-icons/dist/feather.min.js"></script>
|
|
|
91 ```
|
|
|
92
|
|
|
93 After including the script, `feather` will be available as a global variable.
|
|
|
94
|
|
|
95 #### 3. Use
|
|
|
96
|
|
|
97 To use an icon on your page, add a `data-feather` attribute with the icon name to an element.
|
|
|
98
|
|
|
99 ```html
|
|
|
100 <i data-feather="circle"></i>
|
|
|
101 ```
|
|
|
102
|
|
|
103 See the complete list of icons at [feathericons.com](https://feathericons.com).
|
|
|
104
|
|
|
105 #### 4. Replace
|
|
|
106
|
|
|
107 Call the `feather.replace` method.
|
|
|
108
|
|
|
109 ```html
|
|
|
110 <script>
|
|
|
111 feather.replace()
|
|
|
112 </script>
|
|
|
113 ```
|
|
|
114
|
|
|
115 All elements that have a `data-feather` attribute will be replaced with SVG markup corresponding to their `data-feather` attribute value. See the [API Reference](#api-reference) for more information about `feather.replace()`.
|
|
|
116
|
|
|
117 ### Node
|
|
|
118 #### 1. Install
|
|
|
119
|
|
|
120 Install with [npm](https://docs.npmjs.com/getting-started/what-is-npm).
|
|
|
121
|
|
|
122 ```
|
|
|
123 npm install feather-icons --save
|
|
|
124 ```
|
|
|
125
|
|
|
126 #### 2. Require
|
|
|
127
|
|
|
128 ```javascript
|
|
|
129 var feather = require('feather-icons')
|
|
|
130 ```
|
|
|
131
|
|
|
132 #### 3. Use
|
|
|
133 ```javascript
|
|
|
134 feather.icons.circle
|
|
|
135 // <circle cx="12" cy="12" r="10"></circle>
|
|
|
136
|
|
|
137 feather.toSvg('circle')
|
|
|
138 // '<svg class="feather feather-circle" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle></svg>'
|
|
|
139
|
|
|
140 feather.toSvg('circle', { class: 'my-class', 'stroke-width': 1 })
|
|
|
141 // '<svg class="feather feather-circle my-class" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle></svg>'
|
|
|
142 ```
|
|
|
143
|
|
|
144 See the [API Reference](#api-reference) for more information about the available properties and methods of the `feather` object.
|
|
|
145
|
|
|
146 ### Sprite
|
|
|
147
|
|
|
148 *Coming soon*
|
|
|
149
|
|
|
150 ## API Reference
|
|
|
151
|
|
|
152 ### `feather.icons`
|
|
|
153
|
|
|
154 An object with SVG path information for every icon.
|
|
|
155
|
|
|
156 #### Usage
|
|
|
157
|
|
|
158 ```javascript
|
|
|
159 feather.icons.circle
|
|
|
160 // <circle cx="12" cy="12" r="10"></circle>
|
|
|
161
|
|
|
162 feather.icons.clock
|
|
|
163 // '<circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 15 15"/>'
|
|
|
164 ```
|
|
|
165
|
|
|
166 ### `feather.toSvg(key, [options])`
|
|
|
167
|
|
|
168 Returns an SVG string.
|
|
|
169
|
|
|
170 #### Parameters
|
|
|
171
|
|
|
172 | Name | Type | Description |
|
|
|
173 | --------- | ------ | ----------- |
|
|
|
174 | `key` | string | Icon name |
|
|
|
175 | `options` (optional) | Object | Key-value pairs in the `options` object will be mapped to HTML attributes on the `<svg>` tag (e.g. `{ foo: 'bar' }` maps to `foo="bar"`). All default attributes on the `<svg>` tag can be overridden with the `options` object. |
|
|
|
176
|
|
|
177 #### Usage
|
|
|
178
|
|
|
179 ```javascript
|
|
|
180 feather.toSvg('circle')
|
|
|
181 // '<svg class="feather feather-circle" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle></svg>'
|
|
|
182
|
|
|
183 feather.toSvg('circle', { 'stroke-width': 1 })
|
|
|
184 // '<svg class="feather feather-circle" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle></svg>'
|
|
|
185
|
|
|
186 feather.toSvg('circle', { class: 'foo bar' })
|
|
|
187 // '<svg class="feather feather-circle foo bar" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle></svg>'
|
|
|
188 ```
|
|
|
189
|
|
|
190 [View Source](https://github.com/colebemis/feather/blob/master/src/to-svg.js)
|
|
|
191
|
|
|
192 ### `feather.replace([options])`
|
|
|
193
|
|
|
194 Replaces all elements that have a `data-feather` attribute with SVG markup corresponding to the element's `data-feather` attribute value.
|
|
|
195
|
|
|
196 #### Parameters
|
|
|
197
|
|
|
198 | Name | Type | Description |
|
|
|
199 | ---------- | ------ | ----------- |
|
|
|
200 | `options` (optional) | Object | Key-value pairs in the `options` object will be mapped to HTML attributes on the `<svg>` tag (e.g. `{ foo: 'bar' }` maps to `foo="bar"`). All default attributes on the `<svg>` tag can be overridden with the `options` object. |
|
|
|
201
|
|
|
202 #### Usage
|
|
|
203
|
|
|
204 > **Note:** `feather.replace()` only works in a browser environment.
|
|
|
205
|
|
|
206 Simple usage:
|
|
|
207 ```html
|
|
|
208 <i data-feather="circle"></i>
|
|
|
209 <!--
|
|
|
210 <i> will be replaced with:
|
|
|
211 <svg class="feather feather-circle" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle></svg>
|
|
|
212 -->
|
|
|
213
|
|
|
214 <script>
|
|
|
215 feather.replace()
|
|
|
216 </script>
|
|
|
217 ```
|
|
|
218
|
|
|
219 You can pass `feather.replace()` an `options` object:
|
|
|
220 ```html
|
|
|
221 <i data-feather="circle"></i>
|
|
|
222 <!--
|
|
|
223 <i> will be replaced with:
|
|
|
224 <svg class="feather feather-circle foo bar" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle></svg>
|
|
|
225 -->
|
|
|
226
|
|
|
227 <script>
|
|
|
228 feather.replace({ class: 'foo bar', 'stroke-width': 1 })
|
|
|
229 </script>
|
|
|
230 ```
|
|
|
231
|
|
|
232 The id and classes on a placeholder element (i.e. `<i>`) will be copied to the `<svg>` tag:
|
|
|
233
|
|
|
234 ```html
|
|
|
235 <i id="my-circle-icon" class="foo bar" data-feather="circle"></i>
|
|
|
236 <!--
|
|
|
237 <i> will be replaced with:
|
|
|
238 <svg id="my-circle-icon" class="feather feather-circle foo bar" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="10"></circle></svg>
|
|
|
239 -->
|
|
|
240
|
|
|
241 <script>
|
|
|
242 feather.replace()
|
|
|
243 </script>
|
|
|
244 ```
|
|
|
245
|
|
|
246 [View Source](https://github.com/colebemis/feather/blob/master/src/replace.js)
|
|
|
247
|
|
|
248 ## Roadmap
|
|
|
249
|
|
|
250 - [x] Write contributing guidelines
|
|
|
251 - [ ] Write icon design guidelines
|
|
|
252 - [ ] Add usage examples
|
|
|
253 - [ ] Add SVG sprite
|
|
|
254 - [ ] Add tests
|
|
|
255 - [ ] Track code coverage
|
|
|
256 - [ ] Use Prettier to enforce consistent code style
|
|
|
257 - [ ] Add search/filter functionality to project website
|
|
|
258 - [ ] Handle icon aliases
|
|
|
259 - [ ] Handle usage of custom icons
|
|
|
260 - [ ] Improve SVG accessibility
|
|
|
261
|
|
|
262 ## Contributing
|
|
|
263
|
|
|
264 For more info on how to contribute please see the [contribution guidelines](https://github.com/colebemis/feather/blob/master/CONTRIBUTING.md).
|
|
|
265
|
|
|
266 Caught a mistake or want to contribute to the documentation? [Edit this page on Github](https://github.com/colebemis/feather/blob/master/README.md)
|
|
|
267
|
|
|
268 ## Related Projects
|
|
|
269
|
|
|
270 - [angular-feather](https://github.com/michaelbazos/angular-feather) - Feather icons for Angular applications
|
|
|
271 - [react-feather](https://github.com/carmelopullara/react-feather) - Feather icons as React components
|
|
|
272 - [vue-feather-icon](https://github.com/mage3k/vue-feather-icon) - Feather icons as Vue components
|
|
|
273
|
|
|
274 ## License
|
|
|
275
|
|
|
276 Feather is licensed under the [MIT License](https://github.com/colebemis/feather/blob/master/LICENSE).
|
|
|
277
|
|
|
278 [👋](mailto:[email protected])
|
