sindresorhus / srcset

Parse and stringify the HTML <img> srcset attribute

srcset

Parse and stringify the HTML <img> srcset attribute.

Can be useful if you're creating a build-tool.

Install

npm install srcset

Usage

How an image with srcset might look like:

<img
	alt="The Breakfast Combo"
	src="banner.jpg"
	srcset="banner-HD.jpg 2x, banner-phone.jpg 100w"
>

Then have some fun with it:

import {parseSrcset, stringifySrcset} from 'srcset';

const parsed = parseSrcset('banner-HD.jpg 2x, banner-phone.jpg 100w');
console.log(parsed);
/*
[
	{
		url: 'banner-HD.jpg',
		density: 2
	},
	{
		url: 'banner-phone.jpg',
		width: 100
	}
]
*/

parsed.push({
	url: 'banner-super-HD.jpg',
	density: 3
});

const stringified = stringifySrcset(parsed);
console.log(stringified);
/*
banner-HD.jpg 2x, banner-phone.jpg 100w, banner-super-HD.jpg 3x
*/

API

parseSrcset(string, options?)

Parse the HTML <img> srcset attribute.

Accepts a “srcset” string and returns an array of objects with the possible properties: url (always), width, height, and density.

string

Type: string

A “srcset” string.

options

Type: object

strict

Type: boolean
Default: false

When enabled, an invalid “srcset” string will cause an error to be thrown. When disabled, a best effort will be made to parse the string, potentially resulting in invalid or nonsensical output.

stringifySrcset(SrcSetDefinitions, options?)

Stringify SrcSetDefinitions. Accepts an array of SrcSetDefinition objects and returns a “srcset” string.

srcsetDescriptors

Type: array

An array of SrcSetDefinition objects. Each object should have a url field and may have width, height or density fields. When the strict option is true, only width or density is accepted.

options

Type: object

strict

Type: boolean
Default: false

Enable or disable validation of the SrcSetDefinition's. When true, invalid input will cause an error to be thrown. When false, a best effort will be made to stringify invalid input, likely resulting in invalid srcset value.

---

Get professional support for this package with a Tidelift subscription
_{Tidelift helps make open source sustainable for maintainers while giving companies
assurances about security, maintenance, and licensing for their dependencies.}

srcset's Issues

Image URLs with commas incorrectly parsed

Probably an edge case for many, but we have image urls with query parameters like:

https://my.site/image.jpg?foo=bar,baz

The initial parse call is a string split on ',', baz gets trimmed off into its own source.

I'm trying to thing of a way to regex this and if I come up with a solution I'll submit a PR.

[Feature request] Support minified output

Recently I am implementing "minify srcset" feature for htmlnano, a modular HTML minifier. And I decide to utilize srcset in the feature.

According to HTML Standard, both of following HTML markups are valid:

<img srcset="image.png 1x, image2.png 2x, image2.png 3x">

<img srcset="image.png 1x,image2.png 2x,image2.png 3x">

Currently srcset's stringify method only supports the first one. Although I could bring up my own stringify function, it is better to have a built-in option for srcset#stringify.

Property value with newlines leads to corrupt data

I recently started using this library ... and thank you for this! My parsing logic was very bad and wrong. I got a user issue reported over here:
JustinBeckwith/linkinator#511

Which basically boils down to the library not really properly parsing srcset values if there are gratuitous newlines and spaces strewn about. The following shows what's happenin:

import {parseSrcset} from 'srcset';

let value, result;

value = `/docs/v1/assets/img/bootstrap-icons.png,
                                                    /docs/v1/assets/img/[email protected] 2x`;
result = parseSrcset(value);
console.log(result);

// result: [ { url: '/docs/v1/assets/img/bootstrap-icons.png,', density: 2 } ]

value = '/docs/v1/assets/img/bootstrap-icons.png, /docs/v1/assets/img/[email protected] 2x';
result = parseSrcset(value);
console.log(result);

// result: [
//   { url: '/docs/v1/assets/img/bootstrap-icons.png' },
//   { url: '/docs/v1/assets/img/[email protected]', density: 2 }
// ]

Match the latest spec

• h descriptor is not allowed anymore
• w and x on the same candidate is not allowed
• Just splitting on commas does not parse correctly (e.g. URLs can contain commas).

http://www.whatwg.org/specs/web-apps/current-work/multipage/embedded-content.html#parse-a-srcset-attribute

---

IssueHunt Summary

willianveiga has been rewarded.

Backers (Total: $60.00)

• issuehunt ($60.00)

Submitted pull Requests

• #3 fix issue #1
• #6 Match the latest spec

---

Tips

• Checkout the Issuehunt explorer to discover more funded issues.
• Need some help from other developers? Add your repositories on IssueHunt to raise funds.