# @niksy/postcss-sprites

> Generate spritesheets from stylesheets

Latest version **5.0.0** (published 2021-11-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install @niksy/postcss-sprites
pnpm add @niksy/postcss-sprites
yarn add @niksy/postcss-sprites
bun add @niksy/postcss-sprites
```

## Health

**Score 25/100 (F)** — status: abandoned.

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

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 5.0.0 |
| Published | 2021-11-17 |
| First published | 2021-11-17 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Node | >=12 |
| Dependencies | 9 |
| Unpacked size | 60.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Author | 2createStudio |
| Maintainers | niksy |
| Keywords | postcss-plugin, postcss, css, spritesheet, spritesmith, sprite, png, svg |

## Links

- npm: https://www.npmjs.com/package/@niksy/postcss-sprites
- Repository: https://github.com/niksy/postcss-sprites
- Homepage: https://github.com/niksy/postcss-sprites#readme
- Issues: https://github.com/niksy/postcss-sprites/issues
- npm.io page: https://npm.io/package/@niksy/postcss-sprites

## Dependencies (9)

- [debug](https://npm.io/package/debug.md) ^4.3.2
- [p-map](https://npm.io/package/p-map.md) ^4.0.0
- [lodash](https://npm.io/package/lodash.md) ^4.0.0
- [fs-extra](https://npm.io/package/fs-extra.md) ^10.0.0
- [p-filter](https://npm.io/package/p-filter.md) ^2.1.0
- [p-reduce](https://npm.io/package/p-reduce.md) ^2.1.0
- [svg-sprite](https://npm.io/package/svg-sprite.md) ^1.3.5
- [spritesmith](https://npm.io/package/spritesmith.md) ^3.0.1
- [p-each-series](https://npm.io/package/p-each-series.md) ^2.2.0

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 5.0.0 (latest) — 2021-11-17

## README

# postcss-sprites [![Build Status](https://github.com/niksy/postcss-sprites/workflows/CI/badge.svg?branch=postcss-8-support)](https://github.com/niksy/postcss-sprites/actions?query=workflow%3ACI) [![npm version](https://badge.fury.io/js/postcss-sprites.svg)](https://badge.fury.io/js/postcss-sprites)

> [PostCSS](https://github.com/postcss/postcss) plugin that generates spritesheets from your stylesheets.

```css
/* Input */
.comment { background: url(images/sprite/ico-comment.png) no-repeat 0 0; }
.bubble { background: url(images/sprite/ico-bubble.png) no-repeat 0 0; }

/* ---------------- */

/* Output */
.comment { background-image: url(images/sprite.png); background-position: 0 0; }
.bubble { background-image: url(images/sprite.png); background-position: 0 -50px; }
```

----

### Usage

```javascript
var fs = require('fs');
var postcss = require('postcss');
var { default: sprites } = require('@niksy/postcss-sprites');

var css = fs.readFileSync('./css/style.css', 'utf8');
var opts = {
	stylesheetPath: './dist',
	spritePath: './dist/images/'
};

postcss([sprites(opts)])
	.process(css, {
		from: './css/style.css',
		to: './dist/style.css'
	})
	.then(function(result) {
		fs.writeFileSync('./dist/style.css', result.css);
	});

```

See [PostCSS](https://github.com/postcss/postcss) docs for examples for your environment.

----

### Options

###### stylesheetPath

> Relative path to the folder that will keep your output stylesheet(s). If it's null the path of CSS file will be used.

- Default: null
- Required: `false`

###### spritePath

> Relative path to the folder that will keep your output spritesheet(s).

- Default: `./`
- Required: `true`

###### basePath

> Your base path that will be used for images with absolute CSS urls.

- Default: `./`
- Required: `false`

###### relativeTo

> Indicates whether the url should be relative against current CSS context or original CSS stylesheet file.

- Default: `file`
- Required: `false`
- Options: `file|rule`

###### filterBy

> Defines filter functions that will manipulate the list of images founded in your stylesheet(s).

- Default: `[]`
- Required: `false`
- Options: `Function|Function[]`

**Every function must return a ``Promise`` which should be resolved or rejected.**

Built-in filters:

- based on `fs.stat` and used to remove non exisiting images

###### groupBy

> Defines group functions that will manipulate the list of images founded in your stylesheet(s).

- Default: `[]`
- Required: `false`
- Options: `Function|Function[]`

**Every function must return a ``Promise`` which should be resolved with a string or rejected.**

Built-in filters:

- based on `@2x` naming convention

###### retina

> Defines whether or not to search for retina mark in the filename.

- Default: `false`
- Required: `false`

###### hooks

> Defines whether or not to search for retina mark in the filename.

- Default: `{}`
- Required: `false`

###### hooks.onSaveSpritesheet

> Hook that allows to rewrite the data of produced spritesheet.

> If returned value is string, it is used as filepath value, and if returned value is object, it is used as value which will be merged with current spritesheet data.

> Returned value can also be Promise which should return either string or object.

- Default: `null`
- Required: `false`

###### hooks.onUpdateRule

> Hook that allows to rewrite the CSS output for an image.

- Default: `null`
- Required: `false`

###### spritesmith

> A [spritesmith](https://github.com/Ensighten/spritesmith) configuration.

- Default: `{}`
- Required: `false`

###### spritesmith.engine

> The [engine](https://github.com/Ensighten/spritesmith#engines).

- Default: `pixelsmith`
- Required: `false`

###### spritesmith.algorithm

> The [algorithm](https://github.com/Ensighten/spritesmith#algorithms).

- Default: `binary-tree`
- Required: `false`

###### spritesmith.padding

> The space between images in spritesheet.

- Default: `0`
- Required: `false`

###### spritesmith.engineOpts

> The configuration of the [engine](https://github.com/Ensighten/spritesmith#engines).

- Default: `{}`
- Required: `false`

###### spritesmith.exportOpts

> The export options of the [engine](https://github.com/Ensighten/spritesmith#engines).

- Default: `{}`
- Required: `false`

###### svgsprite

> A [svg-sprite](https://github.com/jkphl/svg-sprite#configuration-basics) configuration.

###### verbose

> Prints the plugin output to the console.

- Default: `false`
- Required: `false`

----

### The Image

Every filter or group function will be called with an ``Image`` object.

###### styleFilePath

> An absolute path to the stylesheet - ``/Path/to/your/source/stylesheet.css``

###### path

> An absolute path to the image - ``/Path/to/your/image.png``

###### originalUrl

> The url found in your stylesheet including the query params - ``../image.png?v1``

###### url

> A normalized version of the original url - ``../image.png``

###### ratio

> The retina ratio of your image - ``2``

###### retina

> Indicates whenever your image is retina - ``true``

###### groups

> The groups associated with the image - ``['shapes', '@2x']``

###### token

> The string used as reference in your stylesheet - ``/* @replace|image.png */``

###### coords

> The position & dimensions of image in generated spritesheet - ``{ width: 20, height: 20, x: 0, y: 0 }``

###### spritePath

> A relative path to the generated spritesheet - ``dist/sprite.png``

###### spriteUrl

> A CSS url to the generated spritesheet - ``sprite.png``

###### spriteWidth

> The total width of the spritesheet - ``200``

###### spriteHeight

> The total height of the spritesheet - ``400``

----

### Advanced

- [Filter By](examples/filter-by.md)
- [Group By](examples/group-by.md)
- [Output Dimensions](examples/output-dimensions.md)
- [Skip Prefix](examples/skip-prefix.md)
- [Responsive Spritesheets](examples/responsive-spritesheets.md)
- [Relative To Rule](examples/relative-to-rule.md)
- [Webpack Hot Load](examples/webpack-hot-load.md)

----

### Contributing

Pull requests are welcome.

```
$ git clone git@github.com:niksy/postcss-sprites.git
$ npm install
$ npm run watch
```

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