https://github.com/ben-eb/postcss-resemble-image
Provide a gradient fallback for an image that loosely resembles the original.
https://github.com/ben-eb/postcss-resemble-image
Last synced: about 1 month ago
JSON representation
Provide a gradient fallback for an image that loosely resembles the original.
- Host: GitHub
- URL: https://github.com/ben-eb/postcss-resemble-image
- Owner: ben-eb
- License: mit
- Archived: true
- Created: 2016-10-25T09:46:34.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2017-01-18T12:38:53.000Z (over 9 years ago)
- Last Synced: 2025-07-07T12:54:37.148Z (12 months ago)
- Language: JavaScript
- Homepage: https://ben-eb.github.io/postcss-resemble-image/
- Size: 1.44 MB
- Stars: 432
- Watchers: 6
- Forks: 10
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE-MIT
Awesome Lists containing this project
- awesome-github-projects - postcss-resemble-image - Provide a gradient fallback for an image that loosely resembles the original. ⭐429 `JavaScript` (📦 Legacy & Inactive Projects)
README
# [postcss][postcss]-resemble-image [][ci] [](https://ci.appveyor.com/project/ben-eb/postcss-resemble-image) [][npm] [][deps]
> Provide a gradient fallback for an image that loosely resembles the original.
## Install
With [npm](https://npmjs.org/package/postcss-resemble-image) do:
```
npm install postcss-resemble-image --save
```
postcss-resemble-image uses [Jimp] to perform the image analysis. The following
image formats are supported:
* `BMP`
* `JPEG`
* `PNG`
[Jimp]: https://github.com/oliver-moran/jimp
## Example
This module will add a background gradient fallback for images, should the
resource fail to load; the image fallback loosely resembles the original. The
idea for this module was inspired by [Harry Roberts' article][csswizardry].
Each image will be loaded relative to the CSS file; in these examples, `"waves.jpg"`
is in the same directory as the CSS. Note that this module can also load images
from a URL.
There are two ways to use postcss-resemble-image; the first allows you to
automatically render these gradients by providing a list of selectors
to analyse for images. The second allows you to use a non-standard function,
`resemble-image`, which takes a CSS URL as the first parameter and the
*fidelity* as the second. You may use these interchangeably if you so wish.
### Using the automatic render
#### Options
```js
{
selectors: ['header']
}
```
#### Input
```css
header {
background: url("waves.jpg");
}
```
#### Output
```css
header {
background: url("waves.jpg"), linear-gradient(90deg, #353230 0%, #3c3835 25%, #3b3734 50%, #322f2c 75%);
}
```
### Using the `resemble-image` function
#### Defaults
##### Input
```css
header {
background: resemble-image(url("waves.jpg"));
}
```
##### Output
```css
header {
background: url("waves.jpg"), linear-gradient(90deg, #353230 0%, #3c3835 25%, #3b3734 50%, #322f2c 75%);
}
```
#### Passing percentages
`fidelity` is set globally, but can also be passed as the second parameter to the
`resemble-image` function. This code will generate a colour stop for each tenth
of the image.
```css
header {
background: resemble-image(url("waves.jpg"), 10%);
}
```
#### Passing absolute lengths
`fidelity` can also be set via a *pixel* value. Anything other than `%` will be
parsed as a `px` value, including no unit; these are equivalent:
```css
header {
background: resemble-image(url("waves.jpg"), 10px);
background: resemble-image(url("waves.jpg"), 10em);
background: resemble-image(url("waves.jpg"), 10);
}
```
## Screenshots
Original image:
After processing (using `simpleGradient`, with 25% stops):
After processing (using `complexGradient`, with 5% stops):
Image credit: https://unsplash.com/?photo=9EM7s13H2I0
## API
### `resembleImage([options])`
Note that postcss-resemble-image is an *asynchronous* processor. It cannot be
used like this:
```js
import postcss from 'postcss';
import resembleImage from 'postcss-resemble-image';
const result = postcss([ resembleImage() ]).process(css).css;
console.log(result);
```
Instead make sure your PostCSS runner uses the asynchronous API:
```js
import postcss from 'postcss';
import resembleImage from 'postcss-resemble-image';
postcss([ resembleImage() ]).process(css).then((result) => {
console.log(result.css);
});
```
postcss-resemble-image is designed to be used with `import` & `export`. When
using `require`, make sure that you load the main module by doing:
```js
const resembleImage = require('postcss-resemble-image').default;
```
#### options
##### fidelity
Type: `number|string`
Default: `25%`
The `fidelity` option controls how many colour stops will be generated for the
linear gradient fallback. By default, it will be split into quarters. Setting
this to anything other than `%` will be parsed as a `px` value, including
no unit. Zero values are not allowed.
##### generator
Type: `function`
Default: `simpleGradient`
The `generator` option controls the rendering of the gradient function; by
default it is set to `simpleGradient` which will smoothly transition between
the gradient stops. The `complexGradient` function hard transitions between each
colour, for a striped effect. To use this instead you may import the function
from the module, like so:
```js
import postcss from 'postcss';
import resembleImage, {complexGradient} from 'postcss-resemble-image';
postcss([ resembleImage({generator: complexGradient}) ]).process(css).then((result) => {
console.log(result.css);
});
```
##### selectors
Type: `array`
Default: `[]`
The `selectors` array controls which selectors postcss-resemble-image should
analyse for URLs to provide gradients for. The module tests using strict
equality; if you are checking a selector which contains more than one simple
selector only one of these needs to be specified. For example:
```js
import postcss from 'postcss';
import resembleImage from 'postcss-resemble-image';
const css = `
header, footer {
background: url("waves.jpg");
}
`;
postcss([ resembleImage({selectors: ['footer']}) ]).process(css).then((result) => {
console.log(result.css);
// => header, footer {
// background: url("waves.jpg"), linear-gradient(90deg, #353230 0%, #3c3835 25%, #3b3734 50%, #322f2c 75%);
// }
});
```
Note that this option isn't required when using the `resemble-image` function.
## Usage
See the [PostCSS documentation](https://github.com/postcss/postcss#usage) for
examples for your environment.
## Contributors
Thanks goes to these wonderful people ([emoji key](https://github.com/kentcdodds/all-contributors#emoji-key)):
| [
Ben Briggs](http://beneb.info)
[💻](https://github.com/ben-eb/postcss-resemble-image/commits?author=ben-eb) [📖](https://github.com/ben-eb/postcss-resemble-image/commits?author=ben-eb) 👀 [⚠️](https://github.com/ben-eb/postcss-resemble-image/commits?author=ben-eb) | [
Manuel Wieser](https://manu.ninja)
[💻](https://github.com/ben-eb/postcss-resemble-image/commits?author=Lorti) [⚠️](https://github.com/ben-eb/postcss-resemble-image/commits?author=Lorti) | [
Steven Sinatra](http://diagramatics.me)
[💻](https://github.com/ben-eb/postcss-resemble-image/commits?author=diagramatics) [⚠️](https://github.com/ben-eb/postcss-resemble-image/commits?author=diagramatics) |
| :---: | :---: | :---: |
This project follows the [all-contributors] specification. Contributions of
any kind welcome!
## Resources
* [Harry Roberts' original article][csswizardry].
* [Manuel Wieser's resemble image blog post](https://manu.ninja/thoughts-on-linear-gradients-that-resemble-images).
[csswizardry]: http://csswizardry.com/2016/10/improving-perceived-performance-with-multiple-background-images/
## License
MIT © [Ben Briggs](http://beneb.info)
[all-contributors]: https://github.com/kentcdodds/all-contributors
[ci]: https://travis-ci.org/ben-eb/postcss-resemble-image
[deps]: https://gemnasium.com/ben-eb/postcss-resemble-image
[npm]: http://badge.fury.io/js/postcss-resemble-image
[postcss]: https://github.com/postcss/postcss