0
# PostCSS Initial
1

2
PostCSS Initial is a PostCSS plugin that provides fallback functionality for the CSS `initial` keyword. It transforms CSS rules containing the `initial` keyword into their explicit fallback values, ensuring cross-browser compatibility for modern CSS cascade features.
3

4
## Package Information
5

6
- **Package Name**: postcss-initial  
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install postcss-initial`
10

11
## Core Imports
12

13
```javascript
14
const postcssInitial = require('postcss-initial');
15
```
16

17
For ES modules:
18

19
```javascript
20
import postcssInitial from 'postcss-initial';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const postcss = require('postcss');
27
const postcssInitial = require('postcss-initial');
28

29
// Basic usage with default options
30
const result = postcss([postcssInitial()])
31
  .process(cssString);
32

33
// With custom options
34
const result = postcss([
35
  postcssInitial({
36
    reset: 'inherited',  // Only reset inherited properties  
37
    replace: true        // Replace 'initial' instead of adding fallback
38
  })
39
]).process(cssString);
40
```
41

42
**Input CSS:**
43
```css
44
a {
45
  animation: initial;
46
  background: initial;
47
  white-space: initial;
48
}
49
```
50

51
**Output CSS (default options):**
52
```css
53
a {
54
  animation: none 0s ease 0s 1 normal none running;
55
  animation: initial;
56
  background: transparent none repeat 0 0 / auto auto padding-box border-box scroll;
57
  background: initial;
58
  white-space: normal;
59
  white-space: initial;
60
}
61
```
62

63
## Capabilities
64

65
### Plugin Factory Function
66

67
Creates a PostCSS plugin instance with the specified configuration options.
68

69
```javascript { .api }
70
/**
71
 * Creates a PostCSS plugin instance
72
 * @param {Object} opts - Configuration options (optional)
73
 * @param {string} opts.reset - Subset of rules for 'all' property. Values: 'all' | 'inherited'. Default: 'all'
74
 * @param {boolean} opts.replace - Replace 'initial' with fallback instead of adding it. Default: false
75
 * @returns {Object} PostCSS plugin object
76
 */
77
function postcssInitial(opts);
78
```
79

80
**Plugin Object Properties:**
81

82
```javascript { .api }
83
/** PostCSS plugin object returned by the factory function */
84
{
85
  /** Plugin identifier for PostCSS */
86
  postcssPlugin: 'postcss-initial',
87
  /** CSS Declaration processor function */
88
  Declaration: function(decl) { /* ... */ }
89
}
90

91
/** PostCSS 8+ compatibility flag on the exported function */
92
postcssInitial.postcss = true;
93
```
94

95
### Configuration Options
96

97
```javascript { .api }
98
/**
99
 * Configuration options for postcss-initial
100
 * @typedef {Object} PostCSSInitialOptions
101
 * @property {string} [reset='all'] - Subset of rules for 'all' property. Values: 'all' | 'inherited'
102
 * @property {boolean} [replace=false] - Replace 'initial' with fallback instead of adding it
103
 */
104
```
105

106
## Usage Examples
107

108
### Standard Fallback (Default Behavior)
109

110
```javascript
111
const postcss = require('postcss');
112
const postcssInitial = require('postcss-initial');
113

114
const css = `
115
  .reset {
116
    color: initial;
117
    margin: initial;
118
  }
119
`;
120

121
const result = postcss([postcssInitial()])
122
  .process(css);
123

124
// Result adds fallbacks before the original declarations:
125
// .reset {
126
//   color: #000;
127
//   color: initial;
128
//   margin: 0;
129
//   margin: initial;
130
// }
131
```
132

133
### Inherited Properties Only
134

135
```javascript
136
const result = postcss([
137
  postcssInitial({ reset: 'inherited' })
138
]).process(css);
139

140
// When using 'all: initial', only inherited properties are reset
141
```
142

143
### Replace Mode  
144

145
```javascript
146
const result = postcss([
147
  postcssInitial({ replace: true })
148
]).process(css);
149

150
// Result replaces 'initial' with fallback values:
151
// .reset {
152
//   color: #000;
153
//   margin: 0;
154
// }
155
```
156

157
### Universal Reset
158

159
The plugin's killer feature - universal CSS reset using the `all` property:
160

161
```javascript
162
const css = `
163
  a {
164
    all: initial;
165
  }
166
`;
167

168
const result = postcss([postcssInitial()])
169
  .process(css);
170

171
// Expands to 50+ individual property resets covering:
172
// - Animation properties
173
// - Background properties  
174
// - Border properties
175
// - Font properties
176
// - Layout properties
177
// - And many more...
178
```
179

180
## Integration with PostCSS
181

182
This plugin follows the standard PostCSS plugin pattern and is compatible with PostCSS 8+:
183

184
```javascript
185
// As part of a PostCSS plugin chain
186
const postcss = require('postcss');
187
const autoprefixer = require('autoprefixer');
188
const postcssInitial = require('postcss-initial');
189

190
postcss([
191
  postcssInitial({ reset: 'inherited' }),
192
  autoprefixer
193
]).process(css);
194
```
195

196
## Browser Compatibility
197

198
The plugin transforms the `initial` keyword into explicit fallback values for browsers that don't support it. This is particularly useful for:
199

200
- Internet Explorer (which doesn't support `initial`)
201
- Older mobile browsers
202
- Legacy browser environments
203

204
The fallback values are based on CSS specifications and provide the same reset behavior as the `initial` keyword.