0
# Style Injection Types
1

2
Seven different strategies for injecting CSS into the DOM, from individual style tags to lazy-loaded styles with manual control.
3

4
## Capabilities
5

6
### styleTag (Default)
7

8
Automatically injects styles using multiple individual `<style>` elements. Each CSS file gets its own style element.
9

10
```javascript { .api }
11
injectType: "styleTag"
12
```
13

14
**Characteristics:**
15
- Multiple `<style>` elements in the DOM
16
- Full source map support
17
- Each CSS module gets individual element
18
- Automatic injection on import
19

20
**Usage Example:**
21

22
```javascript
23
// webpack.config.js
24
module.exports = {
25
  module: {
26
    rules: [
27
      {
28
        test: /\.css$/i,
29
        use: [
30
          { loader: "style-loader", options: { injectType: "styleTag" } },
31
          "css-loader"
32
        ],
33
      },
34
    ],
35
  },
36
};
37

38
// component.js
39
import "./styles.css";  // Automatically creates <style> element
40
import "./other.css";   // Creates another <style> element
41
```
42

43
### singletonStyleTag
44

45
Injects all styles into a single shared `<style>` element for better performance with many CSS modules.
46

47
```javascript { .api }
48
injectType: "singletonStyleTag"
49
```
50

51
**Characteristics:**
52
- Single `<style>` element contains all CSS
53
- No source map support
54
- Better performance with many modules
55
- Automatic injection on import
56

57
**Usage Example:**
58

59
```javascript
60
// webpack.config.js
61
module.exports = {
62
  module: {
63
    rules: [
64
      {
65
        test: /\.css$/i,
66
        use: [
67
          { loader: "style-loader", options: { injectType: "singletonStyleTag" } },
68
          "css-loader"
69
        ],
70
      },
71
    ],
72
  },
73
};
74
```
75

76
### autoStyleTag
77

78
Automatically chooses between `styleTag` (modern browsers) and `singletonStyleTag` (IE6-9) for optimal compatibility.
79

80
```javascript { .api }
81
injectType: "autoStyleTag"
82
```
83

84
**Characteristics:**
85
- Multiple `<style>` elements in modern browsers
86
- Single `<style>` element in IE6-9
87
- Automatic browser detection
88
- Automatic injection on import
89

90
**Usage Example:**
91

92
```javascript
93
module.exports = {
94
  module: {
95
    rules: [
96
      {
97
        test: /\.css$/i,
98
        use: [
99
          { loader: "style-loader", options: { injectType: "autoStyleTag" } },
100
          "css-loader"
101
        ],
102
      },
103
    ],
104
  },
105
};
106
```
107

108
### lazyStyleTag
109

110
Creates multiple `<style>` elements with manual control via `use()` and `unuse()` methods.
111

112
```javascript { .api }
113
injectType: "lazyStyleTag"
114

115
// Generated API for lazy styles
116
interface LazyStyleAPI {
117
  use(insertOptions?: object): LazyStyleAPI;
118
  unuse(): void;
119
  locals?: Record<string, string>;  // CSS Modules locals
120
}
121
```
122

123
**Characteristics:**
124
- Multiple `<style>` elements (when activated)
125
- Manual activation/deactivation control
126
- Reference counting for multiple use() calls
127
- Full source map support
128

129
**Usage Example:**
130

131
```javascript
132
// webpack.config.js
133
module.exports = {
134
  module: {
135
    rules: [
136
      {
137
        test: /\.lazy\.css$/i,
138
        use: [
139
          { loader: "style-loader", options: { injectType: "lazyStyleTag" } },
140
          "css-loader"
141
        ],
142
      },
143
    ],
144
  },
145
};
146

147
// component.js
148
import styles from "./component.lazy.css";
149

150
// Activate styles (creates <style> elements)
151
styles.use();
152

153
// Optional: pass insertion options
154
styles.use({ 
155
  insertInto: document.head,
156
  insertAt: "top" 
157
});
158

159
// Deactivate styles (removes <style> elements when ref count reaches 0)
160
styles.unuse();
161

162
// CSS Modules integration
163
import styles, { className } from "./component.lazy.css";
164
styles.use();
165
console.log(styles.locals.className); // CSS module class name
166
```
167

168
### lazySingletonStyleTag
169

170
Creates a single shared `<style>` element with manual control via `use()` and `unuse()` methods.
171

172
```javascript { .api }
173
injectType: "lazySingletonStyleTag"
174

175
// Same API as lazyStyleTag
176
interface LazyStyleAPI {
177
  use(insertOptions?: object): LazyStyleAPI;
178
  unuse(): void;
179
  locals?: Record<string, string>;
180
}
181
```
182

183
**Characteristics:**
184
- Single `<style>` element (when activated)
185
- Manual activation/deactivation control
186
- Reference counting for multiple use() calls
187
- No source map support
188

189
**Usage Example:**
190

191
```javascript
192
// webpack.config.js
193
module.exports = {
194
  module: {
195
    rules: [
196
      {
197
        test: /\.lazy\.css$/i,
198
        use: [
199
          { loader: "style-loader", options: { injectType: "lazySingletonStyleTag" } },
200
          "css-loader"
201
        ],
202
      },
203
    ],
204
  },
205
};
206

207
// component.js
208
import styles from "./heavy-styles.lazy.css";
209

210
// Conditionally load styles
211
if (shouldLoadStyles) {
212
  styles.use();
213
}
214

215
// Cleanup when component unmounts
216
styles.unuse();
217
```
218

219
### lazyAutoStyleTag
220

221
Automatically chooses between `lazyStyleTag` and `lazySingletonStyleTag` based on browser capabilities, with manual control.
222

223
```javascript { .api }
224
injectType: "lazyAutoStyleTag"
225

226
// Same API as other lazy types
227
interface LazyStyleAPI {
228
  use(insertOptions?: object): LazyStyleAPI;
229
  unuse(): void;
230
  locals?: Record<string, string>;
231
}
232
```
233

234
**Characteristics:**
235
- Multiple `<style>` elements in modern browsers (when activated)
236
- Single `<style>` element in IE6-9 (when activated)
237
- Manual activation/deactivation control
238
- Automatic browser detection
239

240
**Usage Example:**
241

242
```javascript
243
module.exports = {
244
  module: {
245
    rules: [
246
      {
247
        test: /\.lazy\.css$/i,
248
        use: [
249
          { loader: "style-loader", options: { injectType: "lazyAutoStyleTag" } },
250
          "css-loader"
251
        ],
252
      },
253
    ],
254
  },
255
};
256
```
257

258
### linkTag
259

260
Injects styles using `<link rel="stylesheet">` elements that reference CSS files directly.
261

262
```javascript { .api }
263
injectType: "linkTag"
264
```
265

266
**Characteristics:**
267
- `<link>` elements instead of `<style>` elements
268
- References external CSS files
269
- Suitable for production with file extraction
270
- Automatic injection on import
271

272
**Usage Example:**
273

274
```javascript
275
// webpack.config.js
276
module.exports = {
277
  module: {
278
    rules: [
279
      {
280
        test: /\.css$/i,
281
        use: [
282
          { loader: "style-loader", options: { injectType: "linkTag" } },
283
          "css-loader"
284
        ],
285
      },
286
    ],
287
  },
288
};
289

290
// component.js
291
import "./styles.css";  // Creates <link> element
292
```
293

294
## Injection Type Comparison
295

296
| Type | Elements | Source Maps | Manual Control | IE6-9 Support | Best For |
297
|------|----------|-------------|----------------|---------------|----------|
298
| `styleTag` | Multiple `<style>` | ✅ | ❌ | ✅ | Development, debugging |
299
| `singletonStyleTag` | Single `<style>` | ❌ | ❌ | ✅ | Performance with many modules |
300
| `autoStyleTag` | Auto-detect | Conditional | ❌ | ✅ | Cross-browser compatibility |
301
| `lazyStyleTag` | Multiple `<style>` | ✅ | ✅ | ✅ | Conditional styling |
302
| `lazySingletonStyleTag` | Single `<style>` | ❌ | ✅ | ✅ | Performance + conditional |
303
| `lazyAutoStyleTag` | Auto-detect | Conditional | ✅ | ✅ | Conditional + compatibility |
304
| `linkTag` | `<link>` elements | N/A | ❌ | ✅ | External CSS files |
305
306
## Best Practices
307

308
1. **Development**: Use `styleTag` for full debugging capabilities
309
2. **Production**: Consider `singletonStyleTag` for better performance
310
3. **Large Applications**: Use lazy types for code splitting and conditional styles
311
4. **Legacy Support**: Use auto types for IE6-9 compatibility
312
5. **External CSS**: Use `linkTag` when working with pre-built CSS files