Runtime utilities for dynamic CSS variable assignment in vanilla-extract
npx @tessl/cli install tessl/npm-vanilla-extract--dynamic@2.1.0@vanilla-extract/dynamic provides runtime utilities for dynamic CSS variable assignment in vanilla-extract, a zero-runtime CSS-in-TypeScript solution. It offers two main functions for setting CSS custom properties both as inline styles and directly on DOM elements, with support for both simple key-value assignments and type-safe theme contract-based assignments.
npm install @vanilla-extract/dynamicimport { assignInlineVars, setElementVars } from "@vanilla-extract/dynamic";CommonJS:
const { assignInlineVars, setElementVars } = require("@vanilla-extract/dynamic");import { assignInlineVars, setElementVars } from "@vanilla-extract/dynamic";
// Create inline styles for CSS variables
const inlineStyles = assignInlineVars({
'--primary-color': '#0066cc',
'--font-size': '16px',
'--margin': '10px'
});
// Apply to an element
const element = document.getElementById('myElement');
element.style.cssText = inlineStyles.toString();
// Or set variables directly on an element
setElementVars(element, {
'--primary-color': '#ff0066',
'--background': 'white'
});Creates inline style objects with CSS custom properties that can be applied to elements.
/**
* Creates inline style objects for CSS custom properties
* @param vars - Record mapping CSS variable names to values, null/undefined values are ignored
* @returns Styles object with CSS variable names as keys and custom toString method
*/
function assignInlineVars(
vars: Record<string, string | undefined | null>
): Styles;
/**
* Creates inline style objects using theme contracts for type safety
* @param contract - Theme contract object defining CSS variable structure
* @param tokens - Values matching the contract structure
* @returns Styles object with CSS variable names as keys and custom toString method
*/
function assignInlineVars<ThemeContract extends Contract>(
contract: ThemeContract,
tokens: MapLeafNodes<ThemeContract, string>
): Styles;Usage Example:
import { assignInlineVars } from "@vanilla-extract/dynamic";
// Basic usage with CSS variable names
const styles = assignInlineVars({
'--primary-color': '#0066cc',
'--secondary-color': '#ff6600',
'--font-size': '14px',
'--disabled': null // ignored
});
// Apply to element
element.style.cssText = styles.toString();
// Results in: "--primary-color:#0066cc;--secondary-color:#ff6600;--font-size:14px"
// Contract-based usage (requires vanilla-extract contract)
import { createThemeContract } from "@vanilla-extract/css";
const themeContract = createThemeContract({
color: {
primary: null,
secondary: null
},
spacing: {
small: null,
large: null
}
});
const contractStyles = assignInlineVars(themeContract, {
color: {
primary: '#0066cc',
secondary: '#ff6600'
},
spacing: {
small: '8px',
large: '24px'
}
});Directly sets CSS custom properties on DOM elements.
/**
* Directly sets CSS custom properties on DOM elements
* @param element - Target HTML element
* @param vars - Record mapping CSS variable names to values, null/undefined values are ignored
*/
function setElementVars(
element: HTMLElement,
vars: Record<string, string | undefined | null>
): void;
/**
* Sets CSS custom properties using theme contracts for type safety
* @param element - Target HTML element
* @param contract - Theme contract object defining CSS variable structure
* @param tokens - Values matching the contract structure
*/
function setElementVars<ThemeContract extends Contract>(
element: HTMLElement,
contract: ThemeContract,
tokens: MapLeafNodes<ThemeContract, string>
): void;Usage Example:
import { setElementVars } from "@vanilla-extract/dynamic";
const element = document.getElementById('myComponent');
// Basic usage
setElementVars(element, {
'--primary-color': '#0066cc',
'--font-size': '16px',
'--margin': '10px',
'--disabled': null // ignored
});
// Contract-based usage
setElementVars(element, themeContract, {
color: {
primary: '#0066cc',
secondary: '#ff6600'
},
spacing: {
small: '8px',
large: '24px'
}
});/**
* Object containing CSS variable names as keys and their values as strings
* Runtime object includes a custom toString() method for CSS conversion
*/
type Styles = {
[cssVarName: string]: string;
toString(): string;
};
/**
* Recursive structure defining CSS variable contracts for type-safe theming
*/
type Contract = {
[key: string]: CSSVarFunction | null | Contract;
};
/**
* Maps all leaf nodes in a nested object structure to a specified type
* Used to ensure token values match contract structure
*/
type MapLeafNodes<Obj, LeafType> = {
[Prop in keyof Obj]: Obj[Prop] extends Primitive
? LeafType
: Obj[Prop] extends Record<string | number, any>
? MapLeafNodes<Obj[Prop], LeafType>
: never;
};
/**
* CSS variable function format
*/
type CSSVarFunction = `var(--${string})`;
type Primitive = string | boolean | number | null | undefined;