# icon-sprite

> Combines svg icons into a single sprite file.

Latest version **0.1.2** (published 2023-11-12) · MIT license · 0 weekly downloads

## Install

```sh
npm install icon-sprite
pnpm add icon-sprite
yarn add icon-sprite
bun add icon-sprite
```

## Health

**Score 40/100 (D)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned.

## Facts

| | |
|---|---|
| Version | 0.1.2 |
| Published | 2023-11-12 |
| First published | 2023-10-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 8.1 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | Brett Wood |
| Maintainers | woodbrettm |
| Keywords | combine, merge, svg, sprite, icons |

## Links

- npm: https://www.npmjs.com/package/icon-sprite
- Repository: https://github.com/woodbrettm/icon-sprite
- Issues: https://github.com/woodbrettm/icon-sprite/issues
- npm.io page: https://npm.io/package/icon-sprite

## Dependencies (1)

- [prettier](https://npm.io/package/prettier.md) 3.0.3

## Alternatives

- [@fortawesome/react-fontawesome](https://npm.io/package/@fortawesome/react-fontawesome.md) — 2.2M weekly downloads
- [roboto-fontface](https://npm.io/package/roboto-fontface.md) — 196.0K weekly downloads
- [@react-native-vector-icons/common](https://npm.io/package/@react-native-vector-icons/common.md) — 150.4K weekly downloads
- [@procore/core-icons](https://npm.io/package/@procore/core-icons.md) — 4.6K weekly downloads
- [@react-md/material-icons](https://npm.io/package/@react-md/material-icons.md) — 1.6K weekly downloads

## Recent versions

- 0.1.2 (latest) — 2023-11-12
- 0.1.1 — 2023-10-28
- 0.1.0 — 2023-10-27

## README

# Icon Sprite

[![npm](https://img.shields.io/npm/v/icon-sprite)](https://www.npmjs.com/package/icon-sprite)
[![Github Actions](https://github.com/woodbrettm/icon-sprite/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/woodbrettm/icon-sprite/actions/workflows/tests.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/woodbrettm/icon-sprite/blob/main/LICENSE)

This package contains functions which allow a dev to build an icon sprite from a folder of svg icons
and export it to a single icon sprite svg file.

- Best used inside an npm script for now.
- The majority of the original icons' SVG code is kept intact, so it's up to the dev to format
  the original icon files. (See below).
- The svg file name is used to create the symbol id. So a filename of `up-arrow` can be referenced
  in html using `#up-arrow`. (See below).

## Installation

```bash
npm install -D icon-sprite
```

## Usage

At the moment, the package is intended to be used inside a custom node script file, though
could also be used in a build process. In addition to the documentation below, the repo
contains a demo folder for reference.

### Exports

The package exports two functions. One to build the icon sprite as a string, and one to
export it to a file:

```javascript
import { buildSprite, exportSpriteToFile } from 'icon-sprite';

const sprite = await buildSprite('absolute-path-to-folder-containing-icons');
exportSpriteToFile(sprite, 'absolute-path-to-file.svg');

// Directory of sprite file and input icons cannot be the same, as
// buildSprite imports all svgs from the folder.
```

### Script Example

#### `Folder Structure:`

```
src
  assets
    icons
      source

scripts
  icon-sprite.ts|js

package.json
```

#### `icon-sprite.ts|js:`

```javascript
import path from 'path';
import { buildSprite, exportSpriteToFile } from 'icon-sprite';

const sourceFolderPath = path.resolve(__dirname, '../src/assets/icons/source');
const spriteFilePath = path.resolve(__dirname, '../src/assets/icons/icon-sprite.svg');

const spriteString = await buildSprite(sourceFolderPath);

exportSpriteToFile(spriteString, spriteFilePath);
```

#### `package.json`

I'm using @digitak/esrun instead of ts-node. Standard js file with
node command is also fine.

```json
{
  "scripts": {
    "icon-sprite": "esrun ./scripts/icon-sprite.ts"
  }
}
```

### SVG Code

When combining the svg files,

- The `xmlns` attribute is removed
- `<svg></svg>` is replaced with `<symbol></symbol>`
- The svg file-name is added to the symbol as: `id="file-name"`

The source/original icon svgs must be formatted like so:

- It's typically best to remove the height and width attributes so the svg can
  be sized from CSS.
- Make sure the `xmlns` attr is exactly `xmlns="http://www.w3.org/2000/svg`
- Other elements than `<path>` inside the svg should be fine

### Input:

```xml
<!-- Original icon file: up-arrow.svg -->
<!-- Setting fill="currentColor" is often useful -->
<svg viewBox="0 0 32 32" xmlns="http://www.w3.org/2000/svg">
  <path
    d="..."
    fill="..."
    other-attr="..."
  />
</svg>
```

### Output:

The outputted file is formatted using Prettier.

```xml
<svg xmlns="http://www.w3.org/2000/svg">
  <defs>
    <symbol id="up-arrow" viewBox="0 0 32 32">
      <path
        d="..."
        fill="..."
        other-attr="..."
      />
    </symbol>
    ... other icons converted to <symbol>
  </defs>
</svg>
```

### Referencing SVGs

```html
<svg><use href="path-to-sprite-file.svg#up-arrow"></use></svg>
```

---
_Source: https://npm.io/package/icon-sprite · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._