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

Cole Bemis's avatar
Cole Bemis committed
3 4 5
[![Build status](https://img.shields.io/travis/feathericons/feather/master.svg?style=flat-square)](https://travis-ci.org/feathericons/feather)
[![Coverage](https://img.shields.io/codecov/c/github/feathericons/feather/master.svg?style=flat-square)](https://codecov.io/gh/feathericons/feather)
[![npm downloads](https://img.shields.io/npm/dm/feather-icons.svg?style=flat-square)](https://www.npmjs.com/package/feather-icons)
Cole Bemis's avatar
Cole Bemis committed
6
[![npm version](https://img.shields.io/npm/v/feather-icons.svg?style=flat-square)](https://www.npmjs.com/package/feather-icons)
7
[![CDNJS version](https://img.shields.io/cdnjs/v/feather-icons.svg?style=flat-square)](https://cdnjs.com/libraries/feather-icons)
8
[![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)
9

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

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

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

Cole Bemis's avatar
Cole Bemis committed
16
```shell
17 18
npm install feather-icons
```
Cole Bemis's avatar
Cole Bemis committed
19

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

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

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

* [Quick Start](#quick-start)
* [Usage](#usage)
30
  * [Client-side JavaScript](#client-side-javascript)
Cole Bemis's avatar
Cole Bemis committed
31
  * [Node](#node)
32
  * [SVG Sprite](#svg-sprite)
33
  * [Figma](#figma)
Cole Bemis's avatar
Cole Bemis committed
34 35
* [API Reference](#api-reference)
	* [`feather.icons`](#feathericons)
Cole Bemis's avatar
Cole Bemis committed
36 37
	* [`feather.icons[name].toSvg()`](#feathericonsnametosvgattrs)
	* [`feather.replace()`](#featherreplaceattrs)
Cole Bemis's avatar
Cole Bemis committed
38
	* [(DEPRECATED) `feather.toSvg()`](#deprecated-feathertosvgname-attrs)
Cole Bemis's avatar
Cole Bemis committed
39 40
* [Roadmap](#roadmap)
* [Contributing](#contributing)
41
* [Related Projects](#related-projects)
Cole Bemis's avatar
Cole Bemis committed
42 43 44 45 46 47 48 49 50 51 52 53
* [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
54
  <script src="https://unpkg.com/feather-icons"></script>
Cole Bemis's avatar
Cole Bemis committed
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
  <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.

73
### Client-side JavaScript
Cole Bemis's avatar
Cole Bemis committed
74 75 76 77 78 79 80

#### 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).

Cole Bemis's avatar
Cole Bemis committed
81
```shell
Cole Bemis's avatar
Cole Bemis committed
82 83 84 85 86 87 88
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

Cole Bemis's avatar
Cole Bemis committed
89
Include `feather.js` or `feather.min.js` with a `<script>` tag:
Cole Bemis's avatar
Cole Bemis committed
90 91

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

Cole Bemis's avatar
Cole Bemis committed
95 96 97
> **Note:** `feather.js` and `feather.min.js` are located in the `dist` directory of the npm package.

Or load the script from a CDN provider:
Cole Bemis's avatar
Cole Bemis committed
98 99

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

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

#### 3. Use

Cole Bemis's avatar
Cole Bemis committed
109
To use an icon on your page, add a `data-feather` attribute with the icon name to an element:
Cole Bemis's avatar
Cole Bemis committed
110 111 112 113 114 115 116 117 118

```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
119
Call the `feather.replace()` method:
Cole Bemis's avatar
Cole Bemis committed
120 121 122 123 124 125 126 127 128 129 130 131

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

Cole Bemis's avatar
Cole Bemis committed
132
Install with [npm](https://docs.npmjs.com/getting-started/what-is-npm):
Cole Bemis's avatar
Cole Bemis committed
133

Cole Bemis's avatar
Cole Bemis committed
134
```shell
Cole Bemis's avatar
Cole Bemis committed
135 136 137 138 139
npm install feather-icons --save
```

#### 2. Require

Cole Bemis's avatar
Cole Bemis committed
140
```js
Cole Bemis's avatar
Cole Bemis committed
141
const feather = require('feather-icons')
Cole Bemis's avatar
Cole Bemis committed
142 143 144 145
```

#### 3. Use

Cole Bemis's avatar
Cole Bemis committed
146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162
```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',
Cole Bemis's avatar
Cole Bemis committed
163 164
//    },
//    toSvg: [Function],
Cole Bemis's avatar
Cole Bemis committed
165 166 167 168 169 170 171
// }

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
172 173 174 175
```

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

176
### SVG Sprite
Cole Bemis's avatar
Cole Bemis committed
177 178 179 180 181 182 183

#### 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).

Cole Bemis's avatar
Cole Bemis committed
184
```shell
Cole Bemis's avatar
Cole Bemis committed
185 186 187 188 189 190 191
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

Cole Bemis's avatar
Cole Bemis committed
192
Include an icon on your page with the following markup:
Cole Bemis's avatar
Cole Bemis committed
193

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

Cole Bemis's avatar
Cole Bemis committed
208 209
> **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).

Cole Bemis's avatar
Cole Bemis committed
210
However, this markup can be simplified using a simple CSS class to avoid repetition of SVG attributes between icons:
Cole Bemis's avatar
Cole Bemis committed
211

212 213
```css
.feather {
Cole Bemis's avatar
Cole Bemis committed
214 215 216 217 218 219
  width: 24px;
  height: 24px;
  stroke: currentColor;
  stroke-width: 2;
  stroke-linecap: round;
  stroke-linejoin: round;
220 221 222
  fill: none;
}
```
Cole Bemis's avatar
Cole Bemis committed
223

224
```html
Cole Bemis's avatar
Cole Bemis committed
225 226
<svg class="feather">
  <use xlink:href="path/to/dist/feather-sprite.svg#circle"/>
227 228
</svg>
```
229 230
### Figma
Feather is available as a [Figma component library](https://www.figma.com/file/dyJRSFTIajik4cdkcXN8yA3K/Feather-Component-Library). To use the components, log in to your Figma account and **duplicate** the file to your drafts.
231

Cole Bemis's avatar
Cole Bemis committed
232 233 234 235
## API Reference

### `feather.icons`

Cole Bemis's avatar
Cole Bemis committed
236
An object with data about every icon.
Cole Bemis's avatar
Cole Bemis committed
237 238 239

#### Usage

Cole Bemis's avatar
Cole Bemis committed
240 241 242 243
```js
feather.icons.x
// {
//    name: 'x',
Cole Bemis's avatar
Cole Bemis committed
244
//    contents: '<line ... /><line ... />',
Cole Bemis's avatar
Cole Bemis committed
245 246 247 248 249 250 251 252 253 254 255 256
//    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',
Cole Bemis's avatar
Cole Bemis committed
257 258
//    },
//    toSvg: [Function],
Cole Bemis's avatar
Cole Bemis committed
259 260 261
// }

feather.icons.x.toString()
Cole Bemis's avatar
Cole Bemis committed
262
// '<line ... /><line ... />'
Cole Bemis's avatar
Cole Bemis committed
263 264
```

265 266
> **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
267 268
[View Source](https://github.com/colebemis/feather/blob/master/src/icons.js)

Cole Bemis's avatar
Cole Bemis committed
269 270
---

Cole Bemis's avatar
Cole Bemis committed
271
### `feather.icons[name].toSvg([attrs])`
Cole Bemis's avatar
Cole Bemis committed
272 273 274 275 276 277 278

Returns an SVG string.

#### Parameters

| Name      | Type   | Description |
| --------- | ------ | ----------- |
Cole Bemis's avatar
Cole Bemis committed
279
| `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
280

281 282 283 284 285 286 287 288
> **Hint:** You might find these SVG attributes helpful for manipulating icons:
> * [`color`](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/color)
> * [`width`](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/width)
> * [`height`](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/height)
> * [`stroke-width`](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-width)
> * [`stroke-linecap`](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-linecap)
> * [`stroke-linejoin`](https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stroke-linejoin)

Cole Bemis's avatar
Cole Bemis committed
289 290
#### Usage

Cole Bemis's avatar
Cole Bemis committed
291
```js
Cole Bemis's avatar
Cole Bemis committed
292
feather.icons.circle.toSvg()
Cole Bemis's avatar
Cole Bemis committed
293 294
// '<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
295
feather.icons.circle.toSvg({ 'stroke-width': 1 })
Cole Bemis's avatar
Cole Bemis committed
296 297
// '<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
298
feather.icons.circle.toSvg({ class: 'foo bar' })
Cole Bemis's avatar
Cole Bemis committed
299 300 301
// '<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
302
[View Source](https://github.com/colebemis/feather/blob/master/src/icon.js)
Cole Bemis's avatar
Cole Bemis committed
303

Cole Bemis's avatar
Cole Bemis committed
304 305
---

Cole Bemis's avatar
Cole Bemis committed
306
### `feather.replace([attrs])`
Cole Bemis's avatar
Cole Bemis committed
307 308 309 310 311 312 313

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
314
| `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
315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332

#### 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
333
You can pass `feather.replace()` an `attrs` object:
Cole Bemis's avatar
Cole Bemis committed
334 335 336 337 338 339 340 341 342 343 344 345
```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
346
All attributes on the placeholder element (i.e. `<i>`) will be copied to the `<svg>` tag:
Cole Bemis's avatar
Cole Bemis committed
347 348

```html
Cole Bemis's avatar
Cole Bemis committed
349
<i data-feather="circle" id="my-circle" class="foo bar" stroke-width="1"></i>
Cole Bemis's avatar
Cole Bemis committed
350 351
<!--
<i> will be replaced with:
Cole Bemis's avatar
Cole Bemis committed
352
<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
353 354 355 356 357 358 359 360 361
-->

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

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

Cole Bemis's avatar
Cole Bemis committed
362 363
---

Cole Bemis's avatar
Cole Bemis committed
364
### (DEPRECATED) `feather.toSvg(name, [attrs])`
Cole Bemis's avatar
Cole Bemis committed
365 366 367 368 369 370 371 372 373 374 375 376 377 378

> **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

Cole Bemis's avatar
Cole Bemis committed
379
```js
Cole Bemis's avatar
Cole Bemis committed
380 381 382 383 384 385 386 387 388 389 390 391
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
392 393 394
## Roadmap

- [ ] Write icon design guidelines
395
- [ ] Improve SVG accessibility
Cole Bemis's avatar
Cole Bemis committed
396 397 398
- [ ] Handle usage of custom icons
- [ ] Add usage examples
- [ ] Make `<feather-icon>` web component
Cole Bemis's avatar
Cole Bemis committed
399 400 401

## Contributing

402
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
403 404 405 406

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
407

Cole Bemis's avatar
Cole Bemis committed
408
 - [angular-feather](https://github.com/michaelbazos/angular-feather) - Feather icons for Angular applications
409
 - [elm-feather](https://github.com/1602/elm-feather) - Feather icons for Elm applications
410
 - [react-feather](https://github.com/carmelopullara/react-feather) - Feather icons as React components
411
 - [sketch-feather](https://github.com/odmln/sketch-feather) - Feather icons as a Sketch library
412
 - [vue-feather-icon](https://github.com/mage3k/vue-feather-icon) - Feather icons as Vue components
413
 - [php-feather](https://github.com/Pixelrobin/php-feather) - Feather icons as a PHP Library
414

Cole Bemis's avatar
Cole Bemis committed
415 416 417
## License

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