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, else undefined.

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 on element, else false.

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'}