0
# Style Loader
1
2
Style Loader is a webpack loader that dynamically injects CSS into the DOM at runtime. It provides multiple injection strategies including individual style tags, singleton style tags, lazy loading capabilities, and link tag insertion. The loader supports various webpack and CSS loader configurations, enables CSS Modules integration with named exports, handles source maps, and offers extensive customization options for DOM insertion behavior.
3
4
## Package Information
5
6
- **Package Name**: style-loader
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install --save-dev style-loader`
10
11
## Important Compatibility Warning
12
13
⚠️ **CSS Experiments Compatibility**: Style Loader is not compatible with webpack's `experiments.css` feature (enabled by default in `experiments.futureDefaults`). If you're using native CSS support via `experiments.css`, disable it or set `{ type: "javascript/auto" }` for rules using style-loader, otherwise style-loader will emit a warning and do nothing.
14
15
## Core Imports
16
17
Style Loader is used as a webpack loader in your webpack configuration, not directly imported in application code:
18
19
```javascript
20
// webpack.config.js
21
module.exports = {
22
module: {
23
rules: [
24
{
25
test: /\.css$/i,
26
use: ["style-loader", "css-loader"],
27
},
28
],
29
},
30
};
31
```
32
33
For CSS Modules, use named imports in your JavaScript:
34
35
```javascript
36
// With CSS Modules enabled
37
import styles from "./component.css";
38
import { className } from "./component.css";
39
```
40
41
For lazy style loading:
42
43
```javascript
44
// Lazy style imports (when using lazy injection types)
45
import styles from "./lazy-styles.lazy.css";
46
47
styles.use(); // Activate styles
48
styles.unuse(); // Deactivate styles
49
```
50
51
## Basic Usage
52
53
```javascript
54
// webpack.config.js - Basic configuration
55
module.exports = {
56
module: {
57
rules: [
58
{
59
test: /\.css$/i,
60
use: ["style-loader", "css-loader"],
61
},
62
],
63
},
64
};
65
66
// component.js - Import styles (automatic injection)
67
import "./styles.css";
68
69
// component.js - CSS Modules usage
70
import styles from "./component.module.css";
71
const element = document.createElement("div");
72
element.className = styles.header;
73
```
74
75
## Architecture
76
77
Style Loader operates through several key components:
78
79
- **Main Loader**: Processes CSS imports and generates runtime injection code
80
- **Injection Strategies**: Seven different modes for inserting CSS into the DOM
81
- **Runtime System**: Collection of modules that handle DOM manipulation
82
- **Options Schema**: JSON schema defining all configuration options
83
- **HMR Support**: Hot Module Replacement integration for development
84
85
## Capabilities
86
87
### Loader Configuration
88
89
Main webpack loader configuration options for controlling CSS injection behavior, DOM insertion strategies, and module output format.
90
91
```javascript { .api }
92
// Loader options interface
93
interface StyleLoaderOptions {
94
injectType?: "styleTag" | "singletonStyleTag" | "autoStyleTag" |
95
"lazyStyleTag" | "lazySingletonStyleTag" | "lazyAutoStyleTag" |
96
"linkTag";
97
attributes?: Record<string, string>;
98
insert?: string;
99
base?: number;
100
esModule?: boolean;
101
styleTagTransform?: string;
102
}
103
```
104
105
[Loader Configuration](./loader-configuration.md)
106
107
### Style Injection Types
108
109
Seven different strategies for injecting CSS into the DOM, from individual style tags to lazy-loaded styles with manual control.
110
111
```javascript { .api }
112
// Injection type examples
113
"styleTag" // Multiple <style> elements (default)
114
"singletonStyleTag" // Single shared <style> element
115
"autoStyleTag" // Auto-detect: multiple in modern browsers, singleton in IE6-9
116
"lazyStyleTag" // Multiple <style> elements with use/unuse control
117
"lazySingletonStyleTag" // Single <style> element with use/unuse control
118
"lazyAutoStyleTag" // Auto-detect with use/unuse control
119
"linkTag" // <link rel="stylesheet"> elements
120
```
121
122
[Style Injection Types](./injection-types.md)
123
124
### CSS Modules Integration
125
126
CSS Modules support with automatic export generation, named exports, and lazy loading integration.
127
128
```javascript { .api }
129
// CSS Modules exports (generated by style-loader)
130
interface CSSModuleExports {
131
[className: string]: string;
132
default?: Record<string, string>;
133
}
134
135
// Lazy CSS Modules exports
136
interface LazyCSSModuleExports extends CSSModuleExports {
137
use(insertOptions?: object): LazyCSSModuleExports;
138
unuse(): void;
139
}
140
```
141
142
[CSS Modules Integration](./css-modules.md)
143
144
### Runtime API
145
146
Low-level runtime functions for DOM manipulation, style injection, and element management.
147
148
```javascript { .api }
149
// Main runtime injection functions
150
function injectStylesIntoStyleTag(list: CSSModule[], options: RuntimeOptions): UpdateFunction;
151
function injectStylesIntoLinkTag(url: string, options: RuntimeOptions): UpdateFunction;
152
153
type UpdateFunction = (newContent?: CSSModule[] | string | null) => void;
154
```
155
156
[Runtime API](./runtime-api.md)
157
158
## Types
159
160
```javascript { .api }
161
// Core types used across the API
162
type CSSModule = [
163
string, // Module ID
164
string, // CSS content
165
string?, // Media query
166
string?, // Source map
167
string?, // Supports rule
168
string? // Layer name
169
];
170
171
interface RuntimeOptions {
172
attributes?: Record<string, string>;
173
insert?: (element: HTMLElement) => void;
174
domAPI?: DOMAPIFunction;
175
insertStyleElement?: (options: object) => HTMLStyleElement;
176
setAttributes?: (element: HTMLElement, attributes?: object) => void;
177
styleTagTransform?: (css: string, element: HTMLStyleElement) => void;
178
}
179
180
interface DOMAPIFunction {
181
(options: RuntimeOptions): {
182
update(obj: CSSModule): void;
183
remove(): void;
184
};
185
}
186
```