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

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

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

Or load the script from a CDN provider.

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

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

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

#### 3. Use

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

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

## API Reference

### `feather.icons`

Cole Bemis's avatar
Cole Bemis committed
173
An object with data about every icon.
Cole Bemis's avatar
Cole Bemis committed
174 175 176

#### Usage

Cole Bemis's avatar
Cole Bemis committed
177 178 179 180
```js
feather.icons.x
// {
//    name: 'x',
Cole Bemis's avatar
Cole Bemis committed
181
//    contents: '<line ... /><line ... />',
Cole Bemis's avatar
Cole Bemis committed
182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197
//    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
198
// '<line ... /><line ... />'
Cole Bemis's avatar
Cole Bemis committed
199 200
```

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

Cole Bemis's avatar
Cole Bemis committed
203 204
---

Cole Bemis's avatar
Cole Bemis committed
205
### `feather.icons[name].toSvg([attrs])`
Cole Bemis's avatar
Cole Bemis committed
206 207 208 209 210 211 212

Returns an SVG string.

#### Parameters

| Name      | Type   | Description |
| --------- | ------ | ----------- |
Cole Bemis's avatar
Cole Bemis committed
213
| `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
214 215 216 217

#### Usage

```javascript
Cole Bemis's avatar
Cole Bemis committed
218
feather.icons.circle.toSvg()
Cole Bemis's avatar
Cole Bemis committed
219 220
// '<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
221
feather.icons.circle.toSvg({ 'stroke-width': 1 })
Cole Bemis's avatar
Cole Bemis committed
222 223
// '<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
224
feather.icons.circle.toSvg({ class: 'foo bar' })
Cole Bemis's avatar
Cole Bemis committed
225 226 227
// '<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
228
[View Source](https://github.com/colebemis/feather/blob/master/src/icon.js)
Cole Bemis's avatar
Cole Bemis committed
229

Cole Bemis's avatar
Cole Bemis committed
230 231
---

Cole Bemis's avatar
Cole Bemis committed
232
### `feather.replace([attrs])`
Cole Bemis's avatar
Cole Bemis committed
233 234 235 236 237 238 239

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
240
| `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
241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258

#### 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
259
You can pass `feather.replace()` an `attrs` object:
Cole Bemis's avatar
Cole Bemis committed
260 261 262 263 264 265 266 267 268 269 270 271
```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
272
All attributes on the placeholder element (i.e. `<i>`) will be copied to the `<svg>` tag:
Cole Bemis's avatar
Cole Bemis committed
273 274

```html
Cole Bemis's avatar
Cole Bemis committed
275
<i data-feather="circle" id="my-circle" class="foo bar" stroke-width="1"></i>
Cole Bemis's avatar
Cole Bemis committed
276 277
<!--
<i> will be replaced with:
Cole Bemis's avatar
Cole Bemis committed
278
<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
279 280 281 282 283 284 285 286 287
-->

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

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

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

290
### [Deprecated] `feather.toSvg(name, [attrs])`
Cole Bemis's avatar
Cole Bemis committed
291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317

> **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
318 319 320 321
## Roadmap

- [ ] Write icon design guidelines
- [ ] Track code coverage
322
- [ ] Improve SVG accessibility
Cole Bemis's avatar
Cole Bemis committed
323 324 325
- [ ] Handle usage of custom icons
- [ ] Add usage examples
- [ ] Make `<feather-icon>` web component
Cole Bemis's avatar
Cole Bemis committed
326 327 328

## Contributing

329
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
330 331 332 333

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
334

Cole Bemis's avatar
Cole Bemis committed
335
 - [angular-feather](https://github.com/michaelbazos/angular-feather) - Feather icons for Angular applications
336
 - [elm-feather](https://github.com/1602/elm-feather) - Feather icons for Elm applications
337
 - [react-feather](https://github.com/carmelopullara/react-feather) - Feather icons as React components
338
 - [sketch-feather](https://github.com/odmln/sketch-feather) - Feather icons as a Sketch library
339
 - [vue-feather-icon](https://github.com/mage3k/vue-feather-icon) - Feather icons as Vue components
340

Cole Bemis's avatar
Cole Bemis committed
341 342 343
## License

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