# `pie-icons` — PIE Icon Set
[](https://img.shields.io/npm/v/@justeattakeaway/pie-icons.svg)
## Contributing
If you want to add a new icon please check [our icon set](https://pie.design/foundations/iconography/library/) first to avoid duplications. Before adding an svg file, please run it through [svgomg](https://jakearchibald.github.io/svgomg/) with the default settings applied and make sure to **turn off** “Clean IDs” setting and **turn on** "Prefer viewBox to width/height" and "Prettify markup" settings.
On top of that please prefix all the ids in the files with the icon name. For example `id="symbol"` for close-circle.svg should become `id="close-circle-symbol"`, as same ids in different SVG files can conflict and cause visual issues as well as invalidate the markup.
## Usage
At its core, `pie-icons` is a collection of [SVG](https://svgontheweb.com/#svg) files. This means that you can use these 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 `pie-icons`.
### Client-side JavaScript
You can either use the pie-icons package using native JS, or hook into the compiled framework components that are generated for React and Vue.
#### Native JS
#### 1. Install
> [!NOTE]
> If you intend to use `pie-icons` with a CDN, you can skip this installation step.
Install with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or Yarn.
```shell
npm install @justeattakeaway/pie-icons --save
yarn add @justeattakeaway/pie-icons
```
Or just copy [`pie-icons.js`](https://unpkg.com/@justeattakeaway/pie-icons/dist/pie-icons.js) or [`pie-icons.min.js`](https://unpkg.com/@justeattakeaway/pie-icons/dist/pie-icons.min.js) into your project directory. You don't need both `pie-icons.js` and `pie-icons.min.js`.
#### 2. Include
Include `pie-icons.js` or `pie-icons.min.js` with a `
```
> [!NOTE]
> `pie-icons.js` and `pie-icons.min.js` are located in the `dist` directory of the npm package.
Or load the script from a CDN provider:
```html
```
After including the script, `pieicons` will be available as a global variable. ### TODO test if this is the name of the global variable ###
#### 3. Use
To use an icon on your page, add a `data-pie-icons` attribute with the icon name to an element:
```html
```
#### 4. Replace
Call the `pieicons.replace()` method:
```html
```
All elements that have a `data-pie-icons` attribute will be replaced with SVG markup corresponding to their `data-pie-icons` attribute value. See the [API Reference](#api-reference) for more information about `pieicons.replace()`.
### Node
#### 1. Install
Install with [npm](https://docs.npmjs.com/getting-started/what-is-npm) or Yarn:
```shell
npm install @justeattakeaway/pie-icons --save
yarn add @justeattakeaway/pie-icons
```
#### 2. Require
```js
const pieicons = require('@justeattakeaway/pie-icons');
```
#### 3. Use
```js
pieicons.icons.x
// {
// name: 'x',
// contents: '`,
// tags: ['cancel', 'close', 'delete', 'remove'],
// attrs: {
// class: 'c-pieIcon c-pieIcon--x',
// xmlns: 'http://www.w3.org/2000/svg',
// },
// toSvg: [Function],
// }
pieicons.icons.x.toSvg()
//
pieicons.icons.x.toSvg({ class: 'foo bar', 'stroke-width': 1, color: 'red' })
//
```
See the [API Reference](#api-reference) for more information about the available properties and methods of the `pieicons` object.
## API Reference
### `pieicons.icons`
An object with data about every icon.
#### Usage
```js
pieicons.icons.x
// {
// name: 'x',
// contents: '',
// tags: ['cancel', 'close', 'delete', 'remove'],
// attrs: {
// 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',
// },
// toSvg: [Function],
// }
pieicons.icons.x.toString()
// ''
```
> [!NOTE]
> `x` in the above example can be replaced with any valid icon name. Icons with multi-word names (e.g. `arrow-right`) **cannot** be accessed using dot notation (e.g. `pieicons.icons.x`). Instead, use bracket notation (e.g. `pieicons.icons['arrow-right']`).
[View Source](https://github.com/justeat/pie-icons/blob/master/src/icons.js)
---
### `pieicons.icons[name].toSvg([attrs], platform)`
Returns an SVG string.
#### Parameters
| Name | Type | Description |
| --------------------- | ------ | ----------- |
| `attrs` (optional) | Object | Key-value pairs in the `attrs` object will be mapped to HTML attributes on the `