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
```