# Icons
> Icons are essential to Volue's user interfaces. When used correctly, they communicate and help the users navigate, understand and use our solutions.

## Overview

Our icon set is a subset of [Feather Icons](https://feathericons.com/) with some custom-made additions. It is a collection of [SVG](https://svgontheweb.com/#svg) files, which comes with the following advantages:

<ul>
  <li iconName="check">
    They’re vector graphics that can be infinitely scaled.
  </li>
  <li iconName="check">
    SVG images can be inlined right in the document and thus styled with CSS or
    even manipulated with JavaScript.
  </li>
  <li iconName="check">
    It is possible to create single SVG sprite sheet and reuse shapes without
    duplication.
  </li>
</ul>

## Browse icons

<IconsGalleryFeature>
  <IconsGallery />
</IconsGalleryFeature>

---

## Usage

### Include the SVG sprite in your app

An SVG sprite is a single SVG file that contains data for multiple SVG graphics.

> **Tip**
>
> Sprite that comes with all the available icons is distributed together
> with `@volue/wave` core package. Once installed, the sprite file can be found
> at `node_modules/@volue/wave/dist/core/sprite.svg`.
>
> It is also included in
> `@volue/design-icons` package along with other files containing
> icons data. [See readme](https://github.com/Volue/wave/tree/next/design-primitives/design-icons).

<Accordion>
<AccordionItem title="How does an SVG sprite work">

SVG sprite is just an `<svg>` tag with a bunch of `<symbol>` elements. Each `<symbol>` tag has a unique ID and wraps all the paths and whatnot for each icon.
Once the sprite sheet file is included you can access all of its shapes as if they were inline via the `<svg>` and `<use>` tags.

```markup
<!DOCTYPE html>
<html>
<head><title>My App</title></head>
<body>
  <!-- SVG sprite sheet up in the DOM, make sure that the SVG sprite file is included on every page/view you want the icons to appear -->
  <div id="svgSpritePlaceholder" class="is-hidden" aria-hidden="true">
    <svg width="0" height="0" xmlns="http://www.w3.org/2000/svg">
      <symbol id="svg--iconOne" viewBox="0 0 24 24">
        <path d="M20 6L9 17l-5-5" />
      </symbol>
      <!-- rest of the icons… -->
    </svg>
  </div>

  <!-- reuse the icons at any point -->
  <div class="svgIcon svgIcon--stroked">
    <svg aria-hidden="true" focusable="false"><use xlink:href="#svg--iconOne" /></svg>
  </div>
</body>
</html>
```

</AccordionItem>
</Accordion>

To use the icons, the sprite markup has to be embedded in your `index.html` file at the top of `<body>`.
In a [webpack](https://webpack.js.org/) settings it's recommended to use `raw-loader` to achieve this:

```markup
<!DOCTYPE html>
<html>
<head><title>My App</title></head>
<body>
  <div id="svgSpritePlaceholder" class="is-hidden" aria-hidden="true">
    <%= require('!!raw-loader!@volue/wave/dist/core/sprite.svg').default %>
  </div>
  <div id="root"></div>
</body>
</html>
```

It is also possible to inject the sprite in a React component:

```jsx
import svgSprite from '!!raw-loader!@volue/wave/dist/core/sprite.svg';

const Document = () => (
  <Html>
    <Head />
    <body>
      <div
        id="svgSpritePlaceholder"
        className="is-hidden"
        aria-hidden="true"
        dangerouslySetInnerHTML={{ __html: svgSprite }}
      />
      <Main />
    </body>
  </Html>
);
```

### Use SvgIcon component

Once the sprite is embedded, it's a breeze to use the icons thanks to the `SvgIcon` component:

```jsx
import { svgIcon } from '@volue/wave-react';

const AddIcon = () => <SvgIcon iconName="add" />;
```

To read more about the `SvgIcon`, [visit the component page](https://next.wave-design-system.pages.dev/components/svg-icon.md).

---

## Custom sprites builder

If you need to build a custom SVG sprite sheet from individual SVG icons, you can use the tool available in the old docs.

<Grid
  columns={{
    '@initial': '1',
    '@mqLargeAndUp': '2'
  }}
  columnGap="spacingL"
>
  <GridItem>
    <Card
      href="https://volue.github.io/wave/icons.html#sprite-builder"
      title="Sprite builder"
      actionIcon="externalLink"
    />
  </GridItem>
</Grid>

---

## Adding new icons

Ready to expand existing set with a new icon?
Follow the [icon design guidelines](https://next.wave-design-system.pages.dev/tokens/icon-design-guidelines.md) and use the icon template as a starting point for your new icon designs.

<Grid
  columns={{
    '@initial': '1',
    '@mqLargeAndUp': '2'
  }}
  columnGap="spacingL"
>
  <GridItem>
    <Card
      href="/resources/wave-icon-design-template.fig.zip"
      download
      title="Figma icon design template"
      actionIcon="download"
    />
  </GridItem>
  <GridItem>
    <Card
      href="https://github.com/Volue/wave/tree/next/design-primitives/design-icons"
      title="See icons repo"
      actionIcon="externalLink"
    />
  </GridItem>
</Grid>
