JavaScript CSS Variables: setProperty and getPropertyValue
Manipulating CSS custom properties (commonly known as CSS variables)
using JavaScript allows developers to create dynamic themes, respond to
user interactions, and update layouts in real time. By utilizing the
getPropertyValue and setProperty methods
provided by the DOM Style Declaration API, JavaScript can read existing
variable values from computed styles and assign new values directly to
elements or globally across the entire document.
Reading CSS
Variables with getPropertyValue
To retrieve the current value of a CSS custom property, you must
access the element’s computed style using
window.getComputedStyle(). Directly checking the
element.style object only returns inline styles, so
getComputedStyle is required to read values defined in
stylesheets or inherited from parent elements.
To read a globally scoped CSS variable defined on
:root:
// Target the root element (<html>)
const rootElement = document.documentElement;
// Get the computed styles of the root element
const rootStyles = window.getComputedStyle(rootElement);
// Retrieve the value of the custom property
const primaryColor = rootStyles.getPropertyValue('--primary-color').trim();
console.log(primaryColor); // Outputs the value, e.g., "#3498db"The .trim() method is often recommended because
getPropertyValue frequently returns values with leading
whitespace.
To read a custom property scoped to a specific element:
const card = document.querySelector('.card');
const cardPadding = window.getComputedStyle(card).getPropertyValue('--card-padding').trim();Modifying CSS
Variables with setProperty
To update or create a CSS custom property via JavaScript, call the
setProperty method on the style object of the
target element.
The method accepts three arguments: 1. Property
Name: The name of the custom property (must include the
-- prefix). 2. Value: The new value as a
string. 3. Priority (optional): Set to
'important' if needed, or left empty/omitted.
To update a global variable on :root:
// Target the root element
const rootElement = document.documentElement;
// Update the variable value
rootElement.style.setProperty('--primary-color', '#e74c3c');To update a variable on a specific element:
const button = document.querySelector('.btn-custom');
// Set a local variable scoped only to this button
button.style.setProperty('--button-scale', '1.2');Setting a property on an element applies it as an inline style. This overrides any rules declared in external stylesheets due to the standard CSS specificity rules, and all child elements inherit the updated variable automatically.
Removing CSS Custom Properties
If you need to remove an inline override and revert a custom property
back to its stylesheet default, use removeProperty:
document.documentElement.style.removeProperty('--primary-color');By combining getComputedStyle,
getPropertyValue, and setProperty, JavaScript
provides full programmatic control over CSS variables, enabling clean
separation between presentation logic and runtime behavior.