Overview
Converts a palette object to CSS custom properties and injects them into the document by creating or updating a <style> tag. This provides access to the full Material Design 3 tonal palette for advanced theming and custom color derivations.
Signature
DynamicColor.paletteToDom(palette, prefix)
Parameters
The palette object containing palette color key-value pairs. Typically from DynamicColor.palette() response (colors.palette).{
error0: '#000000',
error10: '#410E0B',
primary0: '#000000',
primary40: '#8D4E2A',
neutral50: '#7D7470',
neutralVariant95: '#FFEDE6',
// ... more palette colors (0-100 for each color group)
}
prefix
String
default:"--md-ref-palette"
The prefix to use for CSS variable names. The method will append a hyphen and the kebab-cased palette 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 dynamicColorCssVarsPalette 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
- Uses different class name than
colorsToDom() to avoid conflicts
Example
DynamicColor.palette(function(colors) {
// Apply palette colors to the DOM
DynamicColor.paletteToDom(colors.palette);
// Palette variables are now available throughout your app
});
/* Use reference palette for custom color schemes */
.custom-background {
background-color: var(--md-ref-palette-neutral95);
}
.custom-accent {
color: var(--md-ref-palette-primary40);
border-color: var(--md-ref-palette-primary60);
}
.error-banner {
background-color: var(--md-ref-palette-error90);
color: var(--md-ref-palette-error10);
}
Combined with Colors
DynamicColor.colors(function(colors) {
// Apply system colors
DynamicColor.colorsToDom(colors.dayNight);
});
DynamicColor.palette(function(colors) {
// Apply reference palette for advanced theming
DynamicColor.paletteToDom(colors.palette);
});
/* Use system colors for standard UI */
.button {
background: var(--md-sys-color-primary);
color: var(--md-sys-color-on-primary);
}
/* Use palette colors for custom variations */
.button-light {
background: var(--md-ref-palette-primary80);
color: var(--md-ref-palette-primary20);
}
.button-dark {
background: var(--md-ref-palette-primary30);
color: var(--md-ref-palette-primary90);
}
With Custom Prefix
DynamicColor.palette(function(colors) {
DynamicColor.paletteToDom(colors.palette, '--palette');
});
.custom-element {
background: var(--palette-neutral95);
color: var(--palette-neutral10);
}
Implementation
The method creates a :root CSS rule with all palette variables:
// From plugin.js:153-158
function paletteToDom(colors, prefix = '--md-ref-palette') {
_colorsToDom(colors, prefix, 'dynamicColorCssVarsPalette');
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 wallpaper or theme changes
document.addEventListener('dynamicColorChange', updateDynamicColors);
}
});
}
function updateDynamicColors() {
// Apply system colors
DynamicColor.colors(function(colors) {
DynamicColor.colorsToDom(DynamicColor.tintSurfaceColors(colors.dayNight));
});
// Apply reference palette for advanced theming
DynamicColor.palette(function(colors) {
DynamicColor.paletteToDom(colors.palette);
});
}
The style tag uses class dynamicColorCssVarsPalette for tracking. This is separate from colorsToDom() which uses dynamicColorCssVarsColors, allowing both to coexist without conflicts.
Material Design 3 Palette Structure
The injected palette includes tonal values (0-100) for:
- Primary (primary0-primary100): 13 tones
- Secondary (secondary0-secondary100): 13 tones
- Tertiary (tertiary0-tertiary100): 13 tones
- Neutral (neutral0-neutral100): 13 tones
- Neutral Variant (neutralVariant0-neutralVariant100): 13 tones
- Error (error0-error100): 13 tones
Each color group has values at: 0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95, 99, 100
Use Cases
- Create custom color variations beyond system colors
- Build advanced theming systems with full tonal control
- Design custom components that need specific palette tones
- Implement Material Design 3 guidelines with precise color values
- Create gradient effects using multiple tonal values
- Build accessible color combinations using palette reference
See Also
