get-css-data
A micro-library for collecting stylesheet data from link and style nodes.
Features
- Collects CSS data from
<link>
and <style>
nodes - Collects static Node.textContent or live CSS Object Model (CSSOM) data
- Returns CSS data as a concatenated string and a DOM-ordered array of strings
- Allows document, iframe, and shadow DOM traversal
- Handles
@import
rules - Handles absolute and relative URLs
- Inspect, modify and/or filter CSS data from each node
- Modify XHR object before each request
- UMD and ES6 modules available
- Compatible with modern and legacy browsers (IE9+)
- Lightweight (less than 1.5k min+gzip) and dependency-free
Installation
NPM:
npm install get-css-data --save
import getCssData from 'get-css-data';
getCssData({
onComplete: function(cssText, cssArray, nodeArray) {
}
});
Git:
git clone https://github.com/jhildenbiddle/get-css-data.git
CDN (jsdelivr.com shown, also on unpkg.com):
<script src="https://cdn.jsdelivr.net/npm/get-css-data@2"></script>
<script>
getCssData({
onComplete: function(cssText, cssArray, nodeArray) {
}
});
</script>
<script type="module">
import getCssData from 'https://cdn.jsdelivr.net/npm/get-css-data@2/dist/get-css-data.esm.min.js';
getCssData({
onComplete(cssText, cssArray, nodeArray) {
}
});
</script>
Example
HTML:
<head>
<link rel="stylesheet" href="style1.css">
<style>
@import "style2.css";
p { color: blue; }
</style>
</head>
CSS:
p { color: red; }
p { color: green; }
JavaScript (see Options for details)
getCssData({
onComplete: function(cssText, cssArray, nodeArray) {
console.log(cssText);
console.log(cssArray);
console.log(nodeArray);
}
});
Options
Example
getCssData({
rootElement : document,
include : 'link[rel=stylesheet],style',
exclude : '',
filter : '',
skipDisabled: true,
useCSSOM : false,
onBeforeSend: function(xhr, node, url) {
},
onSuccess: function(cssText, node, url) {
},
onError: function(xhr, node, url) {
},
onComplete: function(cssText, cssArray, nodeArray) {
}
});
options.rootElement
- Type:
object
- Default:
document
Root element to traverse for <link>
and <style>
nodes.
Examples
getCssData({
rootElement: document
});
getCssData({
rootElement: (myIframe.contentDocument || myIframe.contentWindow.document)
});
getCssData({
rootElement: myElement.shadowRoot
});
options.include
- Type:
string
- Default:
"link[rel=stylesheet],style"
CSS selector matching <link>
and <style>
nodes to collect data from. The default value includes all style and link nodes.
Example
getCssData({
include: 'link[rel=stylesheet]:not([href*=bootstrap])',
});
options.exclude
CSS selector matching <link>
and <style>
nodes to exclude from those matched by options.include.
Example
getCssData({
exclude: '[href*=bootstrap]',
});
options.filter
Regular expression used to filter node CSS data. Each block of CSS data is tested against the filter, and only matching data is processed.
Example
getCssData({
filter: /\.myclass/,
});
options.skipDisabled
- Type:
boolean
- Default:
true
Determines if disabled stylesheets will be skipped while collecting CSS data.
Example
getCssData({
skipDisabled: true
});
options.useCSSOM
- Type:
boolean
- Default:
false
Determines how CSS data will be collected from <style>
nodes.
When false
, static CSS data is collected by reading each node's textContent value. This method is fast, but the data collected will not reflect changes made using the deleteRule()
or insertRule()
methods. When true
, live CSS data is collected by iterating over each node's CSSRuleList
and concatenating all CSSRule.cssText
values into a single string. This method is slower, but the data collected accurately reflects all changes made to the stylesheet.
Keep in mind that browsers often drop unrecognized selectors, properties, and values when parsing static CSS. For example, Chrome/Safari will drop declarations with Mozilla's -moz-
prefix, while Firefox will drop declarations with Chrome/Safari's -webkit
prefix . This means that data collected when this options is set to true
will likely vary between browsers and differ from the static CSS collected when it is set to false
.
Example
getCssData({
useCSSOM: false
});
options.onBeforeSend
- Type:
function
- Arguments:
- xhr: The XHR
object
containing details of the request - node: The source node
object
reference - url: The source URL
string
(<link>
href or @import
url)
Callback before each XMLHttpRequest (XHR) is sent. Allows modifying the XML object by setting properties, calling methods, or adding event handlers.
Example
getCssData({
onBeforeSend: function(xhr, node, url) {
if (/some-domain.com/.test(url)) {
xhr.withCredentials = true;
xhr.setRequestHeader("foo", "1");
xhr.setRequestHeader("bar", "2");
}
}
});
options.onSuccess
- Type:
function
- Arguments:
- cssText: A
string
of CSS text from node
and url
- node: The source node
object
reference - url: The source URL
string
(<link>
href, @import
url, or page url for <style>
data)
Callback after CSS data has been collected from each node. Allows modifying the CSS data before it is added to the final output by returning any string
value or skipping the CSS data by returning false
or an empty string (""
).
Note that the order in which <link>
and @import
CSS data is "successfully" collected (thereby triggering this callback) is not guaranteed as these requests are asynchronous. To access CSS data in DOM order, use the cssArray
argument passed to the options.oncomplete callback.
Example
getCssData({
onSuccess: function(cssText, node, url) {
const newCssText = cssText.replace(/color:\s*red\s;/g, 'color: blue;');
return newCssText;
}
});
options.onError
- Type:
function
- Arguments:
- xhr: The XHR
object
containing details of the request - node: The source node
object
reference - url: The source URL
string
(<link>
href or @import
url)
Callback after <link>
or @import
request has failed or when
xhr.responseText
appears to be HTML instead of CSS.
Example
getCssData({
onError: function(xhr, node, url) {
console.log(xhr.status);
console.log(xhr.statusText);
}
});
options.onComplete
- Type:
function
- Arguments:
- cssText: A
string
of concatenated CSS text from all nodes in DOM order. - cssArray: An
array
of per-node CSS text in DOM order. The node containing each CSS text block is available at the same nodeArray index. - nodeArray: An
array
of processed <style>
and <link>
nodes in DOM order. The CSS text for each node is available at the same cssArray index.
Callback after CSS data has been collected from all nodes.
Example
getCssData({
onComplete: function(cssText, cssArray, nodeArray) {
}
});
Contact
License
This project is licensed under the MIT License. See the LICENSE for details.
Copyright (c) John Hildenbiddle (@jhildenbiddle)