or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-vanilla-extract--dynamic

Runtime utilities for dynamic CSS variable assignment in vanilla-extract

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@vanilla-extract/dynamic@2.1.x

To install, run

npx @tessl/cli install tessl/npm-vanilla-extract--dynamic@2.1.0

index.mddocs/

@vanilla-extract/dynamic

@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.

Package Information

  • Package Name: @vanilla-extract/dynamic
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @vanilla-extract/dynamic

Core Imports

import { assignInlineVars, setElementVars } from "@vanilla-extract/dynamic";

CommonJS:

const { assignInlineVars, setElementVars } = require("@vanilla-extract/dynamic");

Basic Usage

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

Capabilities

Inline Variable Assignment

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

Direct Element Variable Setting

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

Types

/**
 * 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;