Overview
Converts a colors object to CSS custom properties and injects them into the document by creating or updating a <style> tag. This is the recommended method for applying dynamic colors to your application’s UI.
Signature
DynamicColor.colorsToDom(colors, prefix)
Parameters
The colors object containing color key-value pairs. Typically from DynamicColor.colors() response (e.g., colors.light, colors.dark, or colors.dayNight).{
primary: '#8D4E2A',
onPrimary: '#FFFFFF',
primaryContainer: '#331100',
surface: '#FFFBFF',
onSurface: '#201A17',
// ... more colors
}
prefix
String
default:"--md-sys-color"
The prefix to use for CSS variable names. The method will append a hyphen and the kebab-cased color key name.
Returns
Returns true after successfully inserting or updating the style tag in the DOM.
Behavior
- First call: Creates a new
<style> element with class dynamicColorCssVarsColors and appends it to <head>
- Subsequent calls: Updates the existing style element’s content with new CSS variables
- CSS variables are wrapped in
:root { ... } selector for global availability
Example
DynamicColor.colors(function(colors) {
// Apply dark theme colors to the DOM
DynamicColor.colorsToDom(colors.dark);
// Colors are now available as CSS variables throughout your app
});
/* Use the injected CSS variables in your styles */
.my-button {
background-color: var(--md-sys-color-primary);
color: var(--md-sys-color-on-primary);
}
.my-card {
background-color: var(--md-sys-color-surface);
color: var(--md-sys-color-on-surface);
}
With Tinted Surface Colors
DynamicColor.colors(function(colors) {
// Apply tinted surface colors for Material Design 3 elevation
var tintedColors = DynamicColor.tintSurfaceColors(colors.dayNight);
DynamicColor.colorsToDom(tintedColors);
});
/* Use elevation surfaces with tint */
.elevation-1 {
background-color: var(--md-sys-color-surface1);
}
.elevation-2 {
background-color: var(--md-sys-color-surface2);
}
With Custom Prefix
DynamicColor.colors(function(colors) {
DynamicColor.colorsToDom(colors.light, '--my-theme');
});
.custom-element {
color: var(--my-theme-primary);
background: var(--my-theme-surface);
}
Implementation
The method creates a :root CSS rule with all color variables:
// From plugin.js:145-150
function colorsToDom(colors, prefix = '--md-sys-color') {
_colorsToDom(colors, prefix, 'dynamicColorCssVarsColors');
return true;
}
// Helper function from plugin.js:124-143
function _colorsToDom(colors, prefix, className) {
var cssVars = colorsToCssVars(colors, prefix);
cssVars = ':root {\n'+cssVars+'}';
var element = document.querySelector('.'+className);
if(element) {
element.innerHTML = cssVars;
} else {
var head = document.head || document.getElementsByTagName('head')[0],
style = document.createElement('style');
style.className = className;
style.type = 'text/css';
style.appendChild(document.createTextNode(cssVars));
head.appendChild(style);
}
return true;
}
Complete Usage Pattern
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
DynamicColor.isDynamicColorAvailable(function(available) {
if(available) {
updateDynamicColors();
// Update colors when theme changes
document.addEventListener('dynamicColorChange', updateDynamicColors);
}
});
}
function updateDynamicColors() {
DynamicColor.colors(function(colors) {
// Apply tinted colors that match current theme (light/dark)
var tintedColors = DynamicColor.tintSurfaceColors(colors.dayNight);
DynamicColor.colorsToDom(tintedColors);
});
}
The style tag uses class dynamicColorCssVarsColors for tracking. If you need to apply both colors and palette, use this method alongside paletteToDom() - they use different class names and won’t conflict. Use Cases
- Apply Material Design 3 dynamic colors to your entire app
- Update theme colors when user switches between light/dark mode
- Respond to system wallpaper color changes on Android 12+
- Create adaptive UI that follows platform design guidelines
See Also
