css-custom-properties
v0.1.0
Published
Work with CSS Custom Properties in Javascript
Downloads
34
Maintainers
Readme
CSS Custom Properties
This module provides utilities to work with CSS custom properties in Javascript.
Getting Started
Installation
Install the package with the following command
npm install --save css-custom-properties
Usage
Example:
// Import using ES5 syntax
var CssCustomProperties = require('css-custom-properties');
// Import using ES6 syntax
import CssCustomProperties from 'css-custom-properties';
// Set a CSS variable
CssCustomProperties.set({
'my-var': '16px',
'my-other-var': 0.5,
});
// Get a CSS variable's value
console.log(CssCustomProperties.get('my-var'));
// => '16px'
// Get all CSS variables
console.log(CssCustomProperties.getAll());
// => {'my-var': '16px', 'my-other-var': 0.5}
// Check if a CSS variable has been set
console.log(CssCustomProperties.has('my-var'));
// => true
// Remove a CSS variable
console.log(CssCustomProperties.unset('my-var'));
// => '16px'
// Check if a CSS variable has been set
console.log(CssCustomProperties.has('my-var'));
// => false
Documentation
The package exposes the following methods.
CssCustomProperties.set(collection, [element])
This method sets CSS variables on a DOM element.
Arguments
- collection (Object): The collection of CSS variable-value pairs.
- [element] (DOM Element): (Optional) The DOM element to apply the css variable to. Defaults to the global
:root
element.
Returns
- (Object) returns
collection
.
Example
var variables = CssCustomProperties.set({
'my-var': '16px',
'my-other-var': 0.5,
'--my-prefixed-var': 'red',
});
console.log(variables);
// => {'my-var': '16px', 'my-other-var': 0.5, 'my-prefixed-var': 'red'}
CssCustomProperties.get(variable, [element])
This method gets a CSS variable's value on a DOM element.
Arguments
- variable (String): The CSS variable name.
- [element] (DOM Element): (Optional) The DOM element to get the css variable from. Defaults to the global
:root
element.
Returns
- (*): returns matched
variable
's value, elseundefined
.
Example
var myVar = CssCustomProperties.get('my-var');
console.log(myVar);
// => '16px'
var myNonExistantVar = CssCustomProperties.get('my-non-existant-var');
console.log(myNonExistantVar);
// => undefined
CssCustomProperties.getAll([element])
This method gets all CSS variables on a DOM element.
Arguments
- [element] (DOM Element): (Optional) The DOM element to get the css variables from. Defaults to the global
:root
element.
Returns
- (Object): returns collection of CSS variable-value pairs.
Example
CssCustomProperties.set({
'my-var': '16px',
'my-other-var': 0.5,
});
CssCustomProperties.set({
'another-one': 0,
});
var allVars = CssCustomProperties.getAll();
console.log(allVars);
// => {'my-var': '16px', 'my-other-var': 0.5, 'another-one': 0}
CssCustomProperties.getAllPrefixed([element])
This method gets all CSS variables on a DOM element. Like getAll()
but with prefixed variable names.
Arguments
- [element] (DOM Element): (Optional) The DOM element to get the css variables from. Defaults to the global
:root
element.
Returns
- (Object): returns collection of prefixed CSS variable-value pairs.
Example
CssCustomProperties.set({
'my-var': '16px',
'my-other-var': 0.5,
});
CssCustomProperties.set({
'another-one': 0,
});
var allVars = CssCustomProperties.getAll();
console.log(allVars);
// => {'--my-var': '16px', '--my-other-var': 0.5, '--another-one': 0}
CssCustomProperties.has(variable, [element])
This method checks if a CSS variable exists on a DOM element.
Arguments
- variable (String): The CSS variable name.
- [element] (DOM Element): (Optional) The DOM element to get the css variable from. Defaults to the global
:root
element.
Returns
- (boolean): returns
true
if CSS variable exists onelement
, elsefalse
.
Example
var myVarExists = CssCustomProperties.has('my-var');
console.log(myVarExists);
// => true
var myNonExistantVarExists = CssCustomProperties.get('my-non-existant-var');
console.log(myNonExistantVarExists);
// => false
CssCustomProperties.unset(variable, [element])
This method removes a CSS variable from a DOM element.
Arguments
- variable (String): The CSS variable name.
- [element] (DOM Element): (Optional) The DOM element to remove the css variable from. Defaults to the global
:root
element.
Returns
- (*): returns the value of the removed variable.
Example
var variables = CssCustomProperties.set({
'my-var': '16px',
'my-other-var': 0.5,
});
var removedVar = CssCustomProperties.unset('my-other-var');
// => 0.5
var allVars = CssCustomProperties.getAll();
console.log(allVars);
// => {'my-var': '16px'}
CssCustomProperties.unsetAll(variable, [element])
This method removes all CSS variable from a DOM element.
Arguments
- [element] (DOM Element): (Optional) The DOM element to remove the css variable from. Defaults to the global
:root
element.
Returns
- (*): returns the collection of removed variables.
Example
var variables = CssCustomProperties.set({
'my-var': '16px',
'my-other-var': 0.5,
});
var removedVars = CssCustomProperties.unsetAll();
// => {'my-var': '16px', 'my-other-var': 0.5}
var allVars = CssCustomProperties.getAll();
console.log(allVars);
// => {}
CssCustomProperties.prefix(item)
Adds the "--" prefix if it doesn't already exists.
Arguments
- [item] (String|Object|Array): The variable name or collection of variable names to prefix.
Returns
- (*): The prefixed result.
Example
CssCustomProperties.prefix('var');
// => '--var'
CssCustomProperties.prefix(['var', '--other-var']);
//=> ['--var', '--other-var']
CssCustomProperties.prefix({
'--var': 10,
'other-var': 'green',
});
//=> {'--var': 10, '--other-var': 'green'}
CssCustomProperties.unprefix(item)
Trim the "--" prefix, if it exists.
Arguments
- [item] (String|Object|Array): The variable name or collection of variable names to trim.
Returns
- (*): The trimmed result.
Example
CssCustomProperties.unprefix('--var');
// => 'var'
CssCustomProperties.unprefix(['var', '--other-var']);
//=> ['var', 'other-var']
CssCustomProperties.unprefix({
'--var': 10,
'other-var': 'green',
});
//=> {'var': 10, 'other-var': 'green'}