PostCSS Image Dimensions

PostCSS plugin for using image width, height, ratio and color data in your CSS.

Features

Image width and height
Image size ratio (width:height and height:width)
Average color
Caching

Note: All width, height and ratio helpers include a 2x resolution version. For example, image-width() becomes image-width-2x(). The assumption is that the 2x image is the original image found and the 1x image is half of that.

Usage

Install package as a dependency.

yarn add postcss-image-dimensions

Add to your PostCSS build chain.

const postcssImageDimensions = require('postcss-image-dimensions');

postcss([
	postcssImageDimensions({
		globPattern: ['./src/images/**/*', './other/images/**/*'], // String or Array of strings
		cachePath: './.cache'
	})
]);

Use available helper methods in your CSS.

/* Input */
.example-image {
    width: image-width('src/images/example.jpg');
}

/* Output */
.example-image {
    width: 200px;
}

CSS helper methods

Important: All image paths used with the CSS helpers must be absolute from the root of your project.

image-width() - Width in pixels.
image-width-2x() - Width in pixels.
image-width-ratio() - Ratio of width as a percentage (to 4 decimal places).
image-width-ratio-2x() - Ratio of width as a percentage (to 4 decimal places).
image-height() - Height in pixels.
image-height-2x() - Height in pixels.
image-height-ratio() - Ratio of height as a percentage (to 4 decimal places).
image-height-ratio-2x() - Ratio of height as a percentage (to 4 decimal places).
image-color() - The average color of the image as a hexadecimal string or transparent if image is transparent.

Examples

All examples below assume the following image has been used.

Example Input	Example Output
`image-width('test/juice.jpg')`	`125px`
`image-width-2x('test/juice.jpg')`	`250px`
`image-width-ratio('test/juice.jpg')`	`117.9245%`
`image-width-ratio-2x('test/juice.jpg')`	`118.4834%`
`image-height('test/juice.jpg')`	`106px`
`image-height-2x('test/juice.jpg')`	`211px`
`image-height-ratio('test/juice.jpg')`	`84.8%`
`image-height-ratio-2x('test/juice.jpg')`	`84.4%`
`image-color('test/juice.jpg')`	`#cbbc8e`

API