README.md 13.4 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

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

Cole Bemis's avatar
Cole Bemis committed
10
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
11

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

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

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

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

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

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

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

#### 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
89
<script src="path/to/dist/feather.js"></script>
Cole Bemis's avatar
Cole Bemis committed
90 91 92 93 94
```

Or load the script from a CDN provider.

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

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
114
Call the `feather.replace()` method.
Cole Bemis's avatar
Cole Bemis committed
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135

```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
136
const feather = require('feather-icons')
Cole Bemis's avatar
Cole Bemis committed
137 138 139 140
```

#### 3. Use

Cole Bemis's avatar
Cole Bemis committed
141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165
```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
166 167 168 169
```

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

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

#### 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:

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

Cole Bemis's avatar
Cole Bemis committed
202 203 204 205
> **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.

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

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

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

### `feather.icons`

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

#### Usage

Cole Bemis's avatar
Cole Bemis committed
232 233 234 235
```js
feather.icons.x
// {
//    name: 'x',
Cole Bemis's avatar
Cole Bemis committed
236
//    contents: '<line ... /><line ... />',
Cole Bemis's avatar
Cole Bemis committed
237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252
//    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
253
// '<line ... /><line ... />'
Cole Bemis's avatar
Cole Bemis committed
254 255
```

256 257
> **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
258 259
[View Source](https://github.com/colebemis/feather/blob/master/src/icons.js)

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

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

Returns an SVG string.

#### Parameters

| Name      | Type   | Description |
| --------- | ------ | ----------- |
Cole Bemis's avatar
Cole Bemis committed
270
| `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
271 272 273 274

#### Usage

```javascript
Cole Bemis's avatar
Cole Bemis committed
275
feather.icons.circle.toSvg()
Cole Bemis's avatar
Cole Bemis committed
276 277
// '<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
278
feather.icons.circle.toSvg({ 'stroke-width': 1 })
Cole Bemis's avatar
Cole Bemis committed
279 280
// '<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
281
feather.icons.circle.toSvg({ class: 'foo bar' })
Cole Bemis's avatar
Cole Bemis committed
282 283 284
// '<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
285
[View Source](https://github.com/colebemis/feather/blob/master/src/icon.js)
Cole Bemis's avatar
Cole Bemis committed
286

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

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

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
297
| `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
298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315

#### 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
316
You can pass `feather.replace()` an `attrs` object:
Cole Bemis's avatar
Cole Bemis committed
317 318 319 320 321 322 323 324 325 326 327 328
```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
329
All attributes on the placeholder element (i.e. `<i>`) will be copied to the `<svg>` tag:
Cole Bemis's avatar
Cole Bemis committed
330 331

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

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

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

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

Cole Bemis's avatar
Cole Bemis committed
347
### (DEPRECATED) `feather.toSvg(name, [attrs])`
Cole Bemis's avatar
Cole Bemis committed
348 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

> **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
375 376 377 378
## Roadmap

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

## Contributing

386
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
387 388 389 390

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
391

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

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

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