css-background-parser
v0.1.0
Published
Parse an element’s CSS background properties to get a list of individual backgrounds
Downloads
807,452
Readme
CSS Background Parser
Parse an element’s CSS background properties to get a list of individual backgrounds.
This library is still a work in progress and is probably not very useful yet. It’s pre-1.0 and has no tests yet.
- Methods
- Objects
Usage
Available on npm as css-background-parser
, or in the browser as a global called cssBgParser
Methods
parseElementStyle(styleObject)
Takes a CSSStyleDeclaration
object and returns a BackgroundList
of backgrounds found in the styles.
In non-techo-babble, the only input is an object which represents an element’s style. It could be element.style
, the result of window.getComputedStyle(element)
, or a custom object that happens to have properties which are prefixed background
(backgroundColor
, backgroundSize
, etc.).
If you want the most accurate results, I suggest you use window.getComputedStyle(element)
— see the code examples below.
Since multiple backgrounds can be assigned to an element, this method will always return a BackgroundList
, even if there is only one background. Backgrounds are listed in order from top layer to bottom layer (in other words, the first layer is closest to the person looking at the screen). This means that the color
property will only be filled on the last Background
object in the list, representing the bottom layer.
A very basic example:
var style = getComputedStyle(someElement);
var bglist = cssBgParser.parseElementStyle(style);
console.log(bglist.backgrounds.length); // 1
console.log(bglist.backgrounds[0]); // Logs a Background object
Multiple backgrounds:
someElement.style.backgroundImage = 'linear-gradient(white, blue), url(/background.png)';
someElement.style.backgroundColor = 'black';
var style = getComputedStyle(someElement);
var bglist = cssBgParser.parseElementStyle(style);
console.log(bglist.backgrounds.length); // 2
console.log(bglist.backgrounds[0].image); // "linear-gradient(white, blue)"
console.log(bglist.backgrounds[1].image); // "url(http://example.com/background.png)"
console.log(bglist.backgrounds[0].color); // ""
console.log(bglist.backgrounds[1].color); // "rgb(0, 0, 0)"
The difference between element.style
and window.getComputedStyle(element)
:
someElement.style.background = 'red';
var parsedStyle = cssBgParser.parsesomeElemententStyle(elem.style);
console.log(parsedStyle.backgrounds[0]);
/*
* Background {
* attachment: "initial"
* clip: "initial"
* color: "red"
* image: "initial"
* origin: "initial"
* position: "initial"
* repeat: "initial"
* size: "initial"
* }
*/
var computed = getComputedStyle(elem);
var parsedComputed = cssBgParser.parseElementStyle(computed);
console.log(parsedComputed.backgrounds[0]);
/*
* Background {
* attachment: "scroll"
* clip: "border-box"
* color: "rgb(255, 0, 0)"
* image: "none"
* origin: "padding-box"
* position: "0% 0%"
* repeat: "repeat"
* size: "auto"
* }
*/
Objects / “Classes”
Background(props)
A simple object holding the properties of a single background for an element.
Properties
Background
objects contain the following properties, listed here with their default values (as defined by the CSS specification):
attachment
— "scroll"clip
— "border-box"color
— ""image
— "none"origin
— "padding-box"position
— "0% 0%"repeat
— "repeat"size
— "auto"
A Background
can be instantiated with an optional first parameter, which is an object containing key/value pairs of properties to set. Any properties in the list above that are not found in the props
argument are set to their default values. In most cases, though, you’d only deal with Background
objects as return values from parseElementStyle()
.
Methods
toString()
Returns a string of all properties, in a format that matches browsers’ formatting of thebackground
CSS shorthand property (when an element has only a single background). For reference, the format is:<color> <repeat> <attachment> <position> / <size> <origin> <clip>
BackgroundList(arrayOfBackgrounds)
A collection of Background
objects representing all the backgrounds used for a single element.
Properties
BackgroundList
objects only contain a single property called backgrounds
, which is an array of Background
objects.
A BackgroundList
can be instantiated with an optional first parameter, which is an array of Background
objects that gets assigned to the backgrounds
property. In most cases, though, you’d only deal with BackgroundList
objects as return values from parseElementStyle()
.
Methods
toString()
Returns a comma-separated string of allBackground
s contained in the collection, calling.toString()
on eachBackground
. This matches browsers’ formatting of thebackground
CSS shorthand property (when an element has multiple backgrounds).