0
# Style Attribute Processing
1

2
Transform inline CSS style attributes with minification and dependency analysis for HTML processing, enabling CSS optimization directly within HTML documents.
3

4
## Capabilities
5

6
### Transform Style Attribute Function
7

8
Processes inline CSS declaration lists such as HTML style attributes with transformation and minification.
9

10
```typescript { .api }
11
/**
12
 * Compiles a single CSS declaration list, such as an inline style attribute in HTML
13
 * @param options - Style attribute transformation configuration
14
 * @returns Transformation result with optimized declarations and dependencies
15
 */
16
function transformStyleAttribute(
17
  options: TransformAttributeOptions
18
): TransformAttributeResult;
19

20
interface TransformAttributeOptions {
21
  /** The filename in which the style attribute appeared. Used for error messages and dependencies. */
22
  filename?: string;
23
  /** The source code to transform. */
24
  code: Uint8Array;
25
  /** Whether to enable minification. */
26
  minify?: boolean;
27
  /** The browser targets for the generated code. */
28
  targets?: Targets;
29
  /**
30
   * Whether to analyze `url()` dependencies.
31
   * When enabled, `url()` dependencies are replaced with hashed placeholders
32
   * that can be replaced with the final urls later (after bundling).
33
   * Dependencies are returned as part of the result.
34
   */
35
  analyzeDependencies?: boolean;
36
  /**
37
   * Whether to ignore invalid rules and declarations rather than erroring.
38
   * When enabled, warnings are returned, and the invalid rule or declaration is
39
   * omitted from the output code.
40
   */
41
  errorRecovery?: boolean;
42
  /**
43
   * An AST visitor object. This allows custom transforms or analysis to be implemented in JavaScript.
44
   * Multiple visitors can be composed into one using the `composeVisitors` function.
45
   * For optimal performance, visitors should be as specific as possible about what types of values
46
   * they care about so that JavaScript has to be called as little as possible.
47
   */
48
  visitor?: Visitor<never>;
49
}
50

51
interface TransformAttributeResult {
52
  /** The transformed code. */
53
  code: Uint8Array;
54
  /** `url()` dependencies, if enabled. */
55
  dependencies: Dependency[] | void;
56
  /** Warnings that occurred during compilation. */
57
  warnings: Warning[];
58
}
59
```
60

61
**Usage Examples:**
62

63
```typescript
64
import { transformStyleAttribute } from "lightningcss";
65

66
// Basic style attribute transformation
67
const result = transformStyleAttribute({
68
  code: new TextEncoder().encode("color: red; background-color: #ffffff; margin: 10px 20px 10px 20px"),
69
  minify: true
70
});
71

72
console.log(new TextDecoder().decode(result.code));
73
// Output: "color:red;background:#fff;margin:10px 20px"
74

75
// Style attribute with browser targets
76
const modernResult = transformStyleAttribute({
77
  filename: "component.html",
78
  code: new TextEncoder().encode("display: flex; gap: 1rem; color: lab(50% 20 -30)"),
79
  targets: {
80
    chrome: 80 << 16,
81
    firefox: 75 << 16
82
  },
83
  minify: true
84
});
85

86
// Style attribute with dependency analysis
87
const dependencyResult = transformStyleAttribute({
88
  filename: "page.html",
89
  code: new TextEncoder().encode(`
90
    background-image: url('./assets/bg.jpg'); 
91
    font-family: 'custom-font', sans-serif;
92
    background-size: cover
93
  `),
94
  analyzeDependencies: true,
95
  minify: true
96
});
97

98
console.log(dependencyResult.dependencies); // Contains url() dependencies
99
```
100

101
### HTML Integration Examples
102

103
Common patterns for integrating style attribute transformation with HTML processing.
104

105
**Server-Side HTML Processing:**
106

107
```typescript
108
import { transformStyleAttribute } from "lightningcss";
109
import { parse } from "node-html-parser";
110

111
function processHtmlStyles(html: string, targets?: Targets): string {
112
  const root = parse(html);
113
  
114
  // Find all elements with style attributes
115
  const styledElements = root.querySelectorAll('[style]');
116
  
117
  styledElements.forEach(element => {
118
    const styleAttr = element.getAttribute('style');
119
    if (styleAttr) {
120
      try {
121
        const result = transformStyleAttribute({
122
          filename: 'inline-styles.html',
123
          code: new TextEncoder().encode(styleAttr),
124
          targets,
125
          minify: true,
126
          errorRecovery: true
127
        });
128
        
129
        const transformedStyle = new TextDecoder().decode(result.code);
130
        element.setAttribute('style', transformedStyle);
131
        
132
        // Log any warnings
133
        if (result.warnings.length > 0) {
134
          console.warn(`Style attribute warnings in ${element.tagName}:`, result.warnings);
135
        }
136
      } catch (error) {
137
        console.error('Failed to transform style attribute:', error);
138
      }
139
    }
140
  });
141
  
142
  return root.toString();
143
}
144

145
// Usage
146
const htmlInput = `
147
  <div style="color: red; background-color: #ffffff; margin: 10px 20px 10px 20px;">
148
    <p style="display: flex; gap: 1rem; color: lab(50% 20 -30);">Content</p>
149
  </div>
150
`;
151

152
const optimizedHtml = processHtmlStyles(htmlInput, {
153
  chrome: 90 << 16,
154
  firefox: 88 << 16
155
});
156
```
157

158
**Build Tool Integration:**
159

160
```typescript
161
import { transformStyleAttribute } from "lightningcss";
162

163
class StyleAttributeProcessor {
164
  constructor(private targets?: Targets) {}
165
  
166
  async processFile(filePath: string): Promise<void> {
167
    const html = await fs.readFile(filePath, 'utf8');
168
    const processed = await this.processHtml(html, filePath);
169
    await fs.writeFile(filePath, processed);
170
  }
171
  
172
  private async processHtml(html: string, filename: string): Promise<string> {
173
    const styleRegex = /style="([^"]*)"/g;
174
    
175
    return html.replace(styleRegex, (match, styleContent) => {
176
      try {
177
        const result = transformStyleAttribute({
178
          filename,
179
          code: new TextEncoder().encode(styleContent),
180
          targets: this.targets,
181
          minify: true,
182
          errorRecovery: true
183
        });
184
        
185
        const optimized = new TextDecoder().decode(result.code);
186
        return `style="${optimized}"`;
187
      } catch (error) {
188
        console.warn(`Failed to optimize style in ${filename}:`, error);
189
        return match; // Return original on error
190
      }
191
    });
192
  }
193
}
194

195
// Usage in build script
196
const processor = new StyleAttributeProcessor({
197
  chrome: 90 << 16,
198
  firefox: 88 << 16
199
});
200

201
await processor.processFile('dist/index.html');
202
```
203

204
### Error Recovery in Style Attributes
205

206
Handle invalid CSS in style attributes gracefully while preserving valid declarations.
207

208
```typescript
209
const invalidStyleResult = transformStyleAttribute({
210
  filename: "component.html",
211
  code: new TextEncoder().encode(`
212
    color: red;
213
    invalid-property: bad-value;
214
    background: blue;
215
    another-invalid: ;
216
    font-size: 16px
217
  `),
218
  errorRecovery: true,
219
  minify: true
220
});
221

222
console.log(new TextDecoder().decode(invalidStyleResult.code));
223
// Output: valid declarations only, e.g., "color:red;background:blue;font-size:16px"
224

225
console.log(invalidStyleResult.warnings);
226
// Contains warnings about invalid properties
227
```
228

229
### Style Attribute Visitor Pattern
230

231
Apply custom transformations to style attribute CSS using the visitor pattern.
232

233
```typescript
234
import { transformStyleAttribute, composeVisitors } from "lightningcss";
235

236
// Custom visitor to replace specific colors
237
const colorReplacementVisitor = {
238
  Color(color) {
239
    // Replace red with brand color
240
    if (color.type === 'rgb' && 
241
        color.r === 255 && color.g === 0 && color.b === 0) {
242
      return {
243
        type: 'rgb',
244
        r: 42,
245
        g: 96,
246
        b: 153
247
      };
248
    }
249
    return color;
250
  }
251
};
252

253
const result = transformStyleAttribute({
254
  code: new TextEncoder().encode("color: red; background: blue; border-color: red"),
255
  visitor: colorReplacementVisitor,
256
  minify: true
257
});
258

259
console.log(new TextDecoder().decode(result.code));
260
// Red colors are replaced with brand color
261
```