README.md 13.7 KB
Newer Older
Cole Bemis's avatar
Cole Bemis committed
1
# Feather
Cole Bemis's avatar
Cole Bemis committed
2

3
[![Travis branch](https://img.shields.io/travis/feathericons/feather/master.svg?style=flat-square)](https://travis-ci.org/feathericons/feather)
Cole Bemis's avatar
Cole Bemis committed
4 5
[![npm downloads](https://img.shields.io/npm/dm/feather-icons.svg?style=flat-square)](https://npm-stat.com/charts.html?package=feather-icons&from=2017-06-01)
[![npm version](https://img.shields.io/npm/v/feather-icons.svg?style=flat-square)](https://www.npmjs.com/package/feather-icons)
6
[![CDNJS version](https://img.shields.io/cdnjs/v/feather-icons.svg?style=flat-square)](https://cdnjs.com/libraries/feather-icons)
7
[![Donate](https://img.shields.io/badge/donate-paypal-blue.svg?style=flat-square)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=G6CPFZ6PQRZW8&lc=US&item_name=Feather&currency_code=USD&bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)
8

Cole Bemis's avatar
Cole Bemis committed
9
## What is Feather?
Cole Bemis's avatar
Cole Bemis committed
10

Cole Bemis's avatar
Cole Bemis committed
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.
Cole Bemis's avatar
Cole Bemis committed
12

Cole Bemis's avatar
Cole Bemis committed
13
https://feathericons.com
14

Cole Bemis's avatar
Cole Bemis committed
15
```sh
16 17
npm install feather-icons
```
Cole Bemis's avatar
Cole Bemis committed
18

Cole Bemis's avatar
Cole Bemis committed
19 20
**Sponsored by**

21
<a href="https://stdlib.com">
Cole Bemis's avatar
Cole Bemis committed
22 23 24
  <img src="https://stdlib.com/static/images/stdlib-logo-wordmark-128.png" width="128" />
</a>

Cole Bemis's avatar
Cole Bemis committed
25 26 27 28
## Table of Contents

* [Quick Start](#quick-start)
* [Usage](#usage)
29
  * [Client-side JavaScript](#client-side-javascript)
Cole Bemis's avatar
Cole Bemis committed
30
  * [Node](#node)
31
  * [SVG Sprite](#svg-sprite)
Cole Bemis's avatar
Cole Bemis committed
32 33
* [API Reference](#api-reference)
	* [`feather.icons`](#feathericons)
Cole Bemis's avatar
Cole Bemis committed
34 35
	* [`feather.icons[name].toSvg()`](#feathericonsnametosvgattrs)
	* [`feather.replace()`](#featherreplaceattrs)
Cole Bemis's avatar
Cole Bemis committed
36
	* [(DEPRECATED) `feather.toSvg()`](#deprecated-feathertosvgname-attrs)
Cole Bemis's avatar
Cole Bemis committed
37 38
* [Roadmap](#roadmap)
* [Contributing](#contributing)
39
* [Related Projects](#related-projects)
Cole Bemis's avatar
Cole Bemis committed
40 41 42 43 44 45 46 47 48 49 50 51
* [License](#license)

## Quick Start

Start with this [CodePen Template](https://codepen.io/pen?template=WOJZdM) to begin prototyping with Feather in the browser.

Or copy and paste the following code snippet into a blank `html` file.

```html
<!DOCTYPE html>
<html lang="en">
  <title></title>
Cole Bemis's avatar
Cole Bemis committed
52
  <script src="https://unpkg.com/feather-icons/dist/feather.min.js"></script>
Cole Bemis's avatar
Cole Bemis committed
53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70
  <body>

    <!-- example icon -->
    <i data-feather="circle"></i>

    <script>
      feather.replace()
    </script>
  </body>
</html>
```

## Usage

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)

The following are additional ways you can use Feather.

71
### Client-side JavaScript
Cole Bemis's avatar
Cole Bemis committed
72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89

#### 1. Install

> **Note:** If you intend to use Feather with a CDN, you can skip this installation step.

Install with [npm](https://docs.npmjs.com/getting-started/what-is-npm).

```
npm install feather-icons --save
```

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`.

#### 2. Include

Include `feather.js` or `feather.min.js` with a `<script>` tag. These files are located in the `dist` directory of the npm package.

```html
Cole Bemis's avatar
Cole Bemis committed
90
<script src="path/to/dist/feather.js"></script>
Cole Bemis's avatar
Cole Bemis committed
91 92 93 94 95
```

Or load the script from a CDN provider.

```html
Lukas Drgon's avatar
Lukas Drgon committed
96 97
<!-- choose one -->
<script src="https://cdn.jsdelivr.net/npm/feather-icons/dist/feather.min.js"></script>
Cole Bemis's avatar
Cole Bemis committed
98
<script src="https://unpkg.com/feather-icons/dist/feather.min.js"></script>
Cole Bemis's avatar
Cole Bemis committed
99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
```

After including the script, `feather` will be available as a global variable.

#### 3. Use

To use an icon on your page, add a `data-feather` attribute with the icon name to an element.

```html
<i data-feather="circle"></i>
```

See the complete list of icons at [feathericons.com](https://feathericons.com).

#### 4. Replace

Cole Bemis's avatar
Cole Bemis committed
115
Call the `feather.replace()` method.
Cole Bemis's avatar
Cole Bemis committed
116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136

```html
<script>
  feather.replace()
</script>
```

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()`.

### Node
#### 1. Install

Install with [npm](https://docs.npmjs.com/getting-started/what-is-npm).

```
npm install feather-icons --save
```

#### 2. Require

```javascript
Cole Bemis's avatar
Cole Bemis committed
137
const feather = require('feather-icons')
Cole Bemis's avatar
Cole Bemis committed
138 139 140 141
```

#### 3. Use

Cole Bemis's avatar
Cole Bemis committed
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
```js
feather.icons.x
// {
//    name: 'x',
//    contents: '<line ... /><line ... />`,
//    tags: ['cancel', 'close', 'delete', 'remove'],
//    attrs: {
//      class: 'feather feather-x',
//      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',
//    }
// }

feather.icons.x.toSvg()
// <svg class="feather feather-x" ...><line ... /><line ... /></svg>

feather.icons.x.toSvg({ class: 'foo bar', 'stroke-width': 1, color: 'red' })
// <svg class="feather feather-x foo bar" stroke-width="1" color="red" ...><line ... /><line ... /></svg>
Cole Bemis's avatar
Cole Bemis committed
167 168 169 170
```

See the [API Reference](#api-reference) for more information about the available properties and methods of the `feather` object.

171
### SVG Sprite
Cole Bemis's avatar
Cole Bemis committed
172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188

#### 1. Install

> **Note:** If you intend to use Feather with a CDN, you can skip this installation step.

Install with [npm](https://docs.npmjs.com/getting-started/what-is-npm).

```
npm install feather-icons --save
```

Or just copy [`feather-sprite.svg`](https://unpkg.com/feather-icons/dist/feather-sprite.svg) into your project directory.

#### 2. Use

In your HTML, you can include an icon like so:

189
```html
Cole Bemis's avatar
Cole Bemis committed
190
<svg
191
  width="24"
Cole Bemis's avatar
Cole Bemis committed
192
  height="24"
193 194 195 196 197 198
  fill="none"
  stroke="currentColor"
  stroke-width="2"
  stroke-linecap="round"
  stroke-linejoin="round"
>
Cole Bemis's avatar
Cole Bemis committed
199
  <use xlink:href="path/to/feather-sprite.svg#circle"/>
200 201 202
</svg>
```

Cole Bemis's avatar
Cole Bemis committed
203 204 205 206
> **Note:** `circle` in the above example can be replaced with any valid icon name. See the complete list of icon names at [feathericons.com](https://feathericons.com).

However, this markup can be simplified using a simple CSS class to avoid repetition of SVG attributes between icons.

207 208
```css
.feather {
Cole Bemis's avatar
Cole Bemis committed
209 210 211 212 213 214
  width: 24px;
  height: 24px;
  stroke: currentColor;
  stroke-width: 2;
  stroke-linecap: round;
  stroke-linejoin: round;
215 216 217
  fill: none;
}
```
Cole Bemis's avatar
Cole Bemis committed
218

219
```html
Cole Bemis's avatar
Cole Bemis committed
220 221
<svg class="feather">
  <use xlink:href="path/to/dist/feather-sprite.svg#circle"/>
222 223 224
</svg>
```

Cole Bemis's avatar
Cole Bemis committed
225 226 227 228
## API Reference

### `feather.icons`

Cole Bemis's avatar
Cole Bemis committed
229
An object with data about every icon.
Cole Bemis's avatar
Cole Bemis committed
230 231 232

#### Usage

Cole Bemis's avatar
Cole Bemis committed
233 234 235 236
```js
feather.icons.x
// {
//    name: 'x',
Cole Bemis's avatar
Cole Bemis committed
237
//    contents: '<line ... /><line ... />',
Cole Bemis's avatar
Cole Bemis committed
238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253
//    tags: ['cancel', 'close', 'delete', 'remove'],
//    attrs: {
//      class: 'feather feather-x',
//      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',
//    }
// }

feather.icons.x.toString()
Cole Bemis's avatar
Cole Bemis committed
254
// '<line ... /><line ... />'
Cole Bemis's avatar
Cole Bemis committed
255 256
```

257 258
> **Note:** `x` in the above example can be replaced with any valid icon name. See the complete list of icon names at [feathericons.com](https://feathericons.com). Icons with multi-word names (e.g. `arrow-right`) **cannot** be accessed using dot notation (e.g. `feather.icons.x`). Instead, use bracket notation (e.g. `feather.icons['arrow-right']`).

Cole Bemis's avatar
Cole Bemis committed
259 260
[View Source](https://github.com/colebemis/feather/blob/master/src/icons.js)

Cole Bemis's avatar
Cole Bemis committed
261 262
---

Cole Bemis's avatar
Cole Bemis committed
263
### `feather.icons[name].toSvg([attrs])`
Cole Bemis's avatar
Cole Bemis committed
264 265 266 267 268 269 270

Returns an SVG string.

#### Parameters

| Name      | Type   | Description |
| --------- | ------ | ----------- |
Cole Bemis's avatar
Cole Bemis committed
271
| `attrs` (optional) | Object |  Key-value pairs in the `attrs` 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 `attrs` object. |
Cole Bemis's avatar
Cole Bemis committed
272 273 274 275

#### Usage

```javascript
Cole Bemis's avatar
Cole Bemis committed
276
feather.icons.circle.toSvg()
Cole Bemis's avatar
Cole Bemis committed
277 278
// '<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>'

Cole Bemis's avatar
Cole Bemis committed
279
feather.icons.circle.toSvg({ 'stroke-width': 1 })
Cole Bemis's avatar
Cole Bemis committed
280 281
// '<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>'

Cole Bemis's avatar
Cole Bemis committed
282
feather.icons.circle.toSvg({ class: 'foo bar' })
Cole Bemis's avatar
Cole Bemis committed
283 284 285
// '<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>'
```

Cole Bemis's avatar
Cole Bemis committed
286
[View Source](https://github.com/colebemis/feather/blob/master/src/icon.js)
Cole Bemis's avatar
Cole Bemis committed
287

Cole Bemis's avatar
Cole Bemis committed
288 289
---

Cole Bemis's avatar
Cole Bemis committed
290
### `feather.replace([attrs])`
Cole Bemis's avatar
Cole Bemis committed
291 292 293 294 295 296 297

Replaces all elements that have a `data-feather` attribute with SVG markup corresponding to the element's `data-feather` attribute value.

#### Parameters

| Name       | Type   | Description |
| ---------- | ------ | ----------- |
Cole Bemis's avatar
Cole Bemis committed
298
| `attrs` (optional)  | Object | Key-value pairs in the `attrs` 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 `attrs` object. |
Cole Bemis's avatar
Cole Bemis committed
299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316

#### Usage

> **Note:** `feather.replace()` only works in a browser environment.

Simple usage:
```html
<i data-feather="circle"></i>
<!--
<i> will be replaced with:
<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>
-->

<script>
  feather.replace()
</script>
```

Cole Bemis's avatar
Cole Bemis committed
317
You can pass `feather.replace()` an `attrs` object:
Cole Bemis's avatar
Cole Bemis committed
318 319 320 321 322 323 324 325 326 327 328 329
```html
<i data-feather="circle"></i>
<!--
<i> will be replaced with:
<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>
-->

<script>
  feather.replace({ class: 'foo bar', 'stroke-width': 1 })
</script>
```

Cole Bemis's avatar
Cole Bemis committed
330
All attributes on the placeholder element (i.e. `<i>`) will be copied to the `<svg>` tag:
Cole Bemis's avatar
Cole Bemis committed
331 332

```html
Cole Bemis's avatar
Cole Bemis committed
333
<i data-feather="circle" id="my-circle" class="foo bar" stroke-width="1"></i>
Cole Bemis's avatar
Cole Bemis committed
334 335
<!--
<i> will be replaced with:
Cole Bemis's avatar
Cole Bemis committed
336
<svg id="my-circle" 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>
Cole Bemis's avatar
Cole Bemis committed
337 338 339 340 341 342 343 344 345
-->

<script>
  feather.replace()
</script>
```

[View Source](https://github.com/colebemis/feather/blob/master/src/replace.js)

Cole Bemis's avatar
Cole Bemis committed
346 347
---

Cole Bemis's avatar
Cole Bemis committed
348
### (DEPRECATED) `feather.toSvg(name, [attrs])`
Cole Bemis's avatar
Cole Bemis committed
349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375

> **Note:** `feather.toSvg()` is deprecated. Please use `feather.icons[name].toSvg()` instead.

Returns an SVG string.

#### Parameters

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| `name`    | string | Icon name   |
| `attrs` (optional) | Object |  Key-value pairs in the `attrs` 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 `attrs` object. |

#### Usage

```javascript
feather.toSvg('circle')
// '<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>'

feather.toSvg('circle', { 'stroke-width': 1 })
// '<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>'

feather.toSvg('circle', { class: 'foo bar' })
// '<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>'
```

[View Source](https://github.com/colebemis/feather/blob/master/src/to-svg.js)

Cole Bemis's avatar
Cole Bemis committed
376 377 378 379
## Roadmap

- [ ] Write icon design guidelines
- [ ] Track code coverage
380
- [ ] Improve SVG accessibility
Cole Bemis's avatar
Cole Bemis committed
381 382 383
- [ ] Handle usage of custom icons
- [ ] Add usage examples
- [ ] Make `<feather-icon>` web component
Cole Bemis's avatar
Cole Bemis committed
384 385 386

## Contributing

387
For more info on how to contribute please see the [contribution guidelines](https://github.com/colebemis/feather/blob/master/CONTRIBUTING.md).
Cole Bemis's avatar
Cole Bemis committed
388 389 390 391

Caught a mistake or want to contribute to the documentation? [Edit this page on Github](https://github.com/colebemis/feather/blob/master/README.md)

## Related Projects
392

Cole Bemis's avatar
Cole Bemis committed
393
 - [angular-feather](https://github.com/michaelbazos/angular-feather) - Feather icons for Angular applications
394
 - [elm-feather](https://github.com/1602/elm-feather) - Feather icons for Elm applications
395
 - [react-feather](https://github.com/carmelopullara/react-feather) - Feather icons as React components
396
 - [sketch-feather](https://github.com/odmln/sketch-feather) - Feather icons as a Sketch library
397
 - [vue-feather-icon](https://github.com/mage3k/vue-feather-icon) - Feather icons as Vue components
398

Cole Bemis's avatar
Cole Bemis committed
399 400 401
## License

Feather is licensed under the [MIT License](https://github.com/colebemis/feather/blob/master/LICENSE).