0
# Props and Style Normalization
1

2
Utilities for normalizing component props, CSS styles, and class names into standardized formats that Vue's runtime can process consistently. These functions handle the variety of ways developers can specify styles and classes.
3

4
## Capabilities
5

6
### Style Normalization
7

8
Functions for converting various style input formats into consistent, processable formats.
9

10
```typescript { .api }
11
/**
12
 * Normalized style object type - string keys with string or number values
13
 */
14
type NormalizedStyle = Record<string, string | number>;
15

16
/**
17
 * Normalize style binding to a consistent format
18
 * Handles arrays, objects, and strings
19
 * @param value - Style value in any supported format
20
 * @returns Normalized style object, string, or undefined
21
 */
22
function normalizeStyle(
23
  value: unknown
24
): NormalizedStyle | string | undefined;
25

26
/**
27
 * Parse CSS string into normalized style object
28
 * Handles CSS comments and various delimiter formats
29
 * @param cssText - CSS string to parse
30
 * @returns Object with CSS properties as keys
31
 */
32
function parseStringStyle(cssText: string): NormalizedStyle;
33

34
/**
35
 * Convert normalized style object back to CSS string
36
 * Automatically converts camelCase properties to kebab-case
37
 * @param styles - Style object or string to stringify
38
 * @returns CSS string representation
39
 */
40
function stringifyStyle(
41
  styles: NormalizedStyle | string | undefined
42
): string;
43
```
44

45
### Class Normalization
46

47
Functions for normalizing class bindings into space-separated class name strings.
48

49
```typescript { .api }
50
/**
51
 * Normalize class binding to a space-separated string
52
 * Handles strings, arrays, and objects with conditional classes
53
 * @param value - Class value in any supported format
54
 * @returns Space-separated class name string
55
 */
56
function normalizeClass(value: unknown): string;
57
```
58

59
### Props Normalization
60

61
Combined normalization function for component props that handles both class and style properties.
62

63
```typescript { .api }
64
/**
65
 * Normalize props object by standardizing class and style properties  
66
 * Applies class and style normalization to props object
67
 * @param props - Props object to normalize (can be null)
68
 * @returns Normalized props object or null
69
 */
70
function normalizeProps(
71
  props: Record<string, any> | null
72
): Record<string, any> | null;
73
```
74

75
### CSS Variable Utilities
76

77
Functions for handling CSS custom properties (variables) in Vue's style binding system.
78

79
```typescript { .api }
80
/**
81
 * Normalize CSS variable value for v-bind in style blocks
82
 * Handles null/undefined values and non-finite numbers
83
 * @param value - CSS variable value to normalize
84
 * @returns Normalized string value for CSS variable
85
 */
86
function normalizeCssVarValue(value: unknown): string;
87
```
88

89
**Usage Examples:**
90

91
```typescript
92
import { 
93
  normalizeClass, 
94
  normalizeStyle, 
95
  parseStringStyle,
96
  stringifyStyle,
97
  normalizeProps,
98
  normalizeCssVarValue
99
} from "@vue/shared";
100

101
// Class normalization
102
const classes1 = normalizeClass("btn primary"); // "btn primary"
103
const classes2 = normalizeClass(["btn", "primary", "active"]); // "btn primary active"
104
const classes3 = normalizeClass({
105
  btn: true,
106
  primary: true,
107
  disabled: false
108
}); // "btn primary"
109
const classes4 = normalizeClass([
110
  "btn", 
111
  { primary: true, disabled: false }, 
112
  "size-large"
113
]); // "btn primary size-large"
114

115
// Style normalization - objects
116
const style1 = normalizeStyle({
117
  color: "red",
118
  fontSize: "14px",
119
  backgroundColor: "blue"
120
});
121
// Returns: { color: "red", fontSize: "14px", backgroundColor: "blue" }
122

123
// Style normalization - arrays
124
const style2 = normalizeStyle([
125
  { color: "red" },
126
  { fontSize: "14px" },
127
  "background-color: blue; margin: 0"
128
]);
129
// Returns: { color: "red", fontSize: "14px", "background-color": "blue", margin: "0" }
130

131
// Style normalization - strings (pass through)
132
const style3 = normalizeStyle("color: red; font-size: 14px");
133
// Returns: "color: red; font-size: 14px"
134

135
// Parse CSS strings
136
const parsed = parseStringStyle("color: red; font-size: 14px; /* comment */ margin: 0");
137
// Returns: { color: "red", "font-size": "14px", margin: "0" }
138

139
// Stringify style objects
140
const cssString = stringifyStyle({
141
  color: "red",
142
  fontSize: 14,
143
  backgroundColor: "blue",
144
  "--custom-var": "value"
145
});
146
// Returns: "color:red;font-size:14;background-color:blue;--custom-var:value;"
147

148
// Props normalization
149
const originalProps = {
150
  id: "my-component",
151
  class: ["btn", { primary: true }],
152
  style: [{ color: "red" }, "font-size: 14px"]
153
};
154

155
const normalized = normalizeProps(originalProps);
156
// Returns: {
157
//   id: "my-component", 
158
//   class: "btn primary",
159
//   style: { color: "red", "font-size": "14px" }
160
// }
161

162
// CSS variable normalization
163
const cssVar1 = normalizeCssVarValue("red"); // "red"
164
const cssVar2 = normalizeCssVarValue(null); // "initial"
165
const cssVar3 = normalizeCssVarValue(""); // " " (single space)
166
const cssVar4 = normalizeCssVarValue(42); // "42"
167
const cssVar5 = normalizeCssVarValue(NaN); // "NaN" (with dev warning)
168
```
169

170
### Style Input Format Support
171

172
The normalization functions support multiple input formats:
173

174
**Class Formats:**
175
- String: `"btn primary active"`
176
- Array: `["btn", "primary", "active"]`
177
- Object: `{ btn: true, primary: true, disabled: false }`
178
- Mixed: `["btn", { primary: true }, "active"]`
179

180
**Style Formats:**
181
- Object: `{ color: "red", fontSize: "14px" }`
182
- String: `"color: red; font-size: 14px"`
183
- Array: `[{ color: "red" }, "font-size: 14px"]`
184

185
### CSS Property Handling
186

187
Style normalization includes intelligent property name handling:
188

189
- **CSS Variables**: Properties starting with `--` are preserved as-is
190
- **camelCase**: Converted to kebab-case (`fontSize` → `font-size`)
191
- **Vendor Prefixes**: Properly handled (`WebkitTransform` → `-webkit-transform`)
192
- **Value Types**: Numbers and strings are properly stringified
193

194
### Performance Optimizations
195

196
- **Pass-through**: String values are returned as-is when possible
197
- **Early Returns**: Functions exit early for null/undefined values
198
- **Minimal Processing**: Only processes values that need normalization