0
# @vanilla-extract/dynamic
1

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

4
## Package Information
5

6
- **Package Name**: @vanilla-extract/dynamic
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @vanilla-extract/dynamic`
10

11
## Core Imports
12

13
```typescript
14
import { assignInlineVars, setElementVars } from "@vanilla-extract/dynamic";
15
```
16

17
CommonJS:
18

19
```javascript
20
const { assignInlineVars, setElementVars } = require("@vanilla-extract/dynamic");
21
```
22

23
## Basic Usage
24

25
```typescript
26
import { assignInlineVars, setElementVars } from "@vanilla-extract/dynamic";
27

28
// Create inline styles for CSS variables
29
const inlineStyles = assignInlineVars({
30
  '--primary-color': '#0066cc',
31
  '--font-size': '16px',
32
  '--margin': '10px'
33
});
34

35
// Apply to an element
36
const element = document.getElementById('myElement');
37
element.style.cssText = inlineStyles.toString();
38

39
// Or set variables directly on an element
40
setElementVars(element, {
41
  '--primary-color': '#ff0066',
42
  '--background': 'white'
43
});
44
```
45

46
## Capabilities
47

48
### Inline Variable Assignment
49

50
Creates inline style objects with CSS custom properties that can be applied to elements.
51

52
```typescript { .api }
53
/**
54
 * Creates inline style objects for CSS custom properties
55
 * @param vars - Record mapping CSS variable names to values, null/undefined values are ignored
56
 * @returns Styles object with CSS variable names as keys and custom toString method
57
 */
58
function assignInlineVars(
59
  vars: Record<string, string | undefined | null>
60
): Styles;
61

62
/**
63
 * Creates inline style objects using theme contracts for type safety
64
 * @param contract - Theme contract object defining CSS variable structure
65
 * @param tokens - Values matching the contract structure
66
 * @returns Styles object with CSS variable names as keys and custom toString method
67
 */
68
function assignInlineVars<ThemeContract extends Contract>(
69
  contract: ThemeContract,
70
  tokens: MapLeafNodes<ThemeContract, string>
71
): Styles;
72
```
73

74
**Usage Example:**
75

76
```typescript
77
import { assignInlineVars } from "@vanilla-extract/dynamic";
78

79
// Basic usage with CSS variable names
80
const styles = assignInlineVars({
81
  '--primary-color': '#0066cc',
82
  '--secondary-color': '#ff6600',
83
  '--font-size': '14px',
84
  '--disabled': null // ignored
85
});
86

87
// Apply to element
88
element.style.cssText = styles.toString();
89
// Results in: "--primary-color:#0066cc;--secondary-color:#ff6600;--font-size:14px"
90

91
// Contract-based usage (requires vanilla-extract contract)
92
import { createThemeContract } from "@vanilla-extract/css";
93

94
const themeContract = createThemeContract({
95
  color: {
96
    primary: null,
97
    secondary: null
98
  },
99
  spacing: {
100
    small: null,
101
    large: null
102
  }
103
});
104

105
const contractStyles = assignInlineVars(themeContract, {
106
  color: {
107
    primary: '#0066cc',
108
    secondary: '#ff6600'
109
  },
110
  spacing: {
111
    small: '8px',
112
    large: '24px'
113
  }
114
});
115
```
116

117
### Direct Element Variable Setting
118

119
Directly sets CSS custom properties on DOM elements.
120

121
```typescript { .api }
122
/**
123
 * Directly sets CSS custom properties on DOM elements
124
 * @param element - Target HTML element
125
 * @param vars - Record mapping CSS variable names to values, null/undefined values are ignored
126
 */
127
function setElementVars(
128
  element: HTMLElement,
129
  vars: Record<string, string | undefined | null>
130
): void;
131

132
/**
133
 * Sets CSS custom properties using theme contracts for type safety
134
 * @param element - Target HTML element
135
 * @param contract - Theme contract object defining CSS variable structure
136
 * @param tokens - Values matching the contract structure
137
 */
138
function setElementVars<ThemeContract extends Contract>(
139
  element: HTMLElement,
140
  contract: ThemeContract,
141
  tokens: MapLeafNodes<ThemeContract, string>
142
): void;
143
```
144

145
**Usage Example:**
146

147
```typescript
148
import { setElementVars } from "@vanilla-extract/dynamic";
149

150
const element = document.getElementById('myComponent');
151

152
// Basic usage
153
setElementVars(element, {
154
  '--primary-color': '#0066cc',
155
  '--font-size': '16px',
156
  '--margin': '10px',
157
  '--disabled': null // ignored
158
});
159

160
// Contract-based usage
161
setElementVars(element, themeContract, {
162
  color: {
163
    primary: '#0066cc',
164
    secondary: '#ff6600'
165
  },
166
  spacing: {
167
    small: '8px',
168
    large: '24px'
169
  }
170
});
171
```
172

173
## Types
174

175
```typescript { .api }
176
/**
177
 * Object containing CSS variable names as keys and their values as strings
178
 * Runtime object includes a custom toString() method for CSS conversion
179
 */
180
type Styles = { 
181
  [cssVarName: string]: string;
182
  toString(): string;
183
};
184

185
/**
186
 * Recursive structure defining CSS variable contracts for type-safe theming
187
 */
188
type Contract = {
189
  [key: string]: CSSVarFunction | null | Contract;
190
};
191

192
/**
193
 * Maps all leaf nodes in a nested object structure to a specified type
194
 * Used to ensure token values match contract structure
195
 */
196
type MapLeafNodes<Obj, LeafType> = {
197
  [Prop in keyof Obj]: Obj[Prop] extends Primitive
198
    ? LeafType
199
    : Obj[Prop] extends Record<string | number, any>
200
    ? MapLeafNodes<Obj[Prop], LeafType>
201
    : never;
202
};
203

204
/**
205
 * CSS variable function format
206
 */
207
type CSSVarFunction = `var(--${string})`;
208

209
type Primitive = string | boolean | number | null | undefined;
210
```