# Icons

WordPress Icons Library.

## Installation

Install the module:

```bash
npm install @wordpress/icons --save
```

_This package assumes that your code will run in an **ES2015+** environment. If you're using an environment that has limited or no support for such language features and APIs, you should include [the polyfill shipped in `@wordpress/babel-preset-default`](https://github.com/WordPress/gutenberg/tree/HEAD/packages/babel-preset-default#polyfill) in your code._

## Usage

```js
import { Icon, check } from '@wordpress/icons';

<Icon icon={ check } />;
```

### Stroke scaling

Stroke-based icons scale their stroke width with their size. An icon with a 24×24 viewBox and a stroke width of 1.5 renders a 1px stroke at 16px, a 1.25px stroke at 20px, and a 1.5px stroke at 24px.

You can adjust the stroke width with the standard SVG `strokeWidth` prop. Its value is in viewBox units and scales with the icon. For example, `<Icon icon={ check } size={ 16 } strokeWidth={ 3 } />` renders a 2px stroke. This does not affect fill-based icons.

### Recoloring

Use CSS `color`. Icons follow it through `currentColor` on `fill` or `stroke`.

A growing subset of the library is stroke-based. Those icons set `fill: none` as an inline style on the outer `<svg>`, so a `fill` prop or an ordinary CSS `fill` rule does not recolor them. Pass `style={ { fill: value } }` only when you intend to replace that intrinsic fill.

`Icon` merges a consumer `style` with the icon's own styles. The consumer value wins for the same property.

## Props

| Name    | Type      | Default | Description                                                                   |
| ------- | --------- | ------- | ----------------------------------------------------------------------------- |
| `size`  | `integer` | `24`    | Size of icon in pixels.                                                       |
| `style` | `object`  |         | Merged with the icon's intrinsic styles. Consumer properties take precedence. |

## Docs & examples

You can browse the icons docs and examples at [https://wordpress.github.io/gutenberg/?path=/docs/icons-icon--default](https://wordpress.github.io/gutenberg/?path=/docs/icons-icon--default)

## Adding new icons

To add a new icon to the library, follow these steps:

1. **Add the SVG file**: Place your SVG file in the `src/library/` directory. The filename should be in kebab-case (e.g., `my-new-icon.svg`). Stroke-based icons should use `stroke="currentColor"` on the stroked shapes. Omit `vector-effect` so the stroke width scales with the icon. The build script only accepts `fill: none` as an inline style.
2. **TypeScript files are auto-generated**: The TypeScript component files (`.tsx`) are automatically generated by the build script from the SVG files. You do not need to manually create or edit these files.

3. **Add the icon to `manifest.json`**: Add an entry for your new icon in `src/manifest.json`. The entry should include:
   - `slug`: The icon identifier (should match the SVG filename without the `.svg` extension)
   - `label`: The human-readable label for the icon. Use Title Case (for example, `My New Icon`).
   - `filePath`: The relative path to the SVG file (e.g., `library/my-new-icon.svg`)
   - `collections` (optional): The collections the icon is registered in once it ships to WordPress Core. Omit it to keep the icon in the JS library only. **Important**: Once an icon ships to WordPress Core, removing it is difficult, so carefully consider this field before setting it. The available collections are:
     - `core`: the public collection. Its icons are exposed through the SVG Icons API, which makes them selectable in the Icon block.
     - `core-admin`: the collection the WordPress admin interface renders from. It is not public, so its icons are never exposed through the REST API or selectable in the Icon block, and unregistering `core` cannot take them away from the admin interface.
   - `keywords` (optional): An array of additional translatable search terms for the icon (e.g. `[ "hamburger", "navigation" ]` for a Menu icon).
   - `dashicons` (optional): An array of the Dashicon class names the icon replaces in the admin interface, with the closest match first (e.g. `[ "dashicons-edit", "dashicons-edit-large" ]` for the Pencil icon). Only icons in the `core-admin` collection may set it, and each Dashicon is replaced by at most one icon.
4. **Do not edit `manifest.php`**: The `manifest.php` file is automatically generated from `manifest.json` by the build script. Do not edit it manually, as your changes will be overwritten when the build runs.

After adding your icon, run `npm run build` to generate the TypeScript files and update `manifest.php`.

## Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to [npm](https://www.npmjs.com/) and used by [WordPress](https://make.wordpress.org/core/) as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main [contributor guide](https://github.com/WordPress/gutenberg/tree/HEAD/CONTRIBUTING.md).

<br /><br /><p align="center"><img src="https://s.w.org/style/images/codeispoetry.png?1" alt="Code is Poetry." /></p>