0
# PostCSS Convert Values
1

2
PostCSS Convert Values is a PostCSS plugin that optimizes CSS by converting values to use more efficient units where possible. It reduces CSS file size by converting time values (e.g., 500ms to .5s), length values (e.g., 16px to 1pc), angle values (e.g., degrees to turns), and removing unnecessary units from zero values.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const convertValues = require("postcss-convert-values");
15
```
16

17
For ES modules:
18

19
```javascript
20
import convertValues from "postcss-convert-values";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const postcss = require("postcss");
27
const convertValues = require("postcss-convert-values");
28

29
// Basic usage with default options
30
const result = await postcss([convertValues()])
31
  .process("h1 { font-size: 16px; transition: opacity 500ms; }", {
32
    from: "input.css",
33
    to: "output.css"
34
  });
35
// Result: "h1 { font-size: 1pc; transition: opacity .5s; }"
36

37
// With custom options
38
const customResult = await postcss([
39
  convertValues({
40
    length: true,
41
    time: true,
42
    angle: false,
43
    precision: 2
44
  })
45
]).process(css, { from: undefined });
46
```
47

48
## Capabilities
49

50
### Plugin Creator Function
51

52
Creates a PostCSS plugin instance with optional configuration.
53

54
```javascript { .api }
55
/**
56
 * Creates a PostCSS plugin that converts CSS values to more efficient units
57
 * @param {Options} opts - Plugin configuration options
58
 * @returns {Plugin} PostCSS plugin instance
59
 */
60
function convertValues(opts?: Options): Plugin;
61

62
interface Options {
63
  /** Enable/disable length unit conversions (px ↔ pc/pt/in). Default: true */
64
  length?: boolean;
65
  /** Enable/disable time unit conversions (ms ↔ s). Default: true */
66
  time?: boolean;
67
  /** Enable/disable angle unit conversions (deg ↔ turn). Default: true */
68
  angle?: boolean;
69
  /** Control decimal precision for px values. Default: false */
70
  precision?: false | number;
71
  /** Override browserslist configuration */
72
  overrideBrowserslist?: string | string[];
73
  /** Browserslist stats option */
74
  stats?: any;
75
  /** Browserslist path option */
76
  path?: string;
77
  /** Browserslist environment option */
78
  env?: string;
79
}
80
```
81

82
**Usage Examples:**
83

84
```javascript
85
const postcss = require("postcss");
86
const convertValues = require("postcss-convert-values");
87

88
// Enable all conversions (default)
89
postcss([convertValues()]);
90

91
// Disable specific conversions
92
postcss([convertValues({
93
  length: false,  // Keep px units as-is
94
  time: true,     // Convert ms ↔ s
95
  angle: false    // Keep deg units as-is
96
})]);
97

98
// Set precision for pixel values
99
postcss([convertValues({
100
  precision: 2  // Round to 2 decimal places
101
})]);
102

103
// Override browserslist for IE11 compatibility
104
postcss([convertValues({
105
  overrideBrowserslist: ["ie 11"]
106
})]);
107
```
108

109
### Plugin PostCSS Marker
110

111
Indicates this is a PostCSS plugin.
112

113
```javascript { .api }
114
/** PostCSS plugin marker property */
115
convertValues.postcss: true;
116
```
117

118
## Conversion Behaviors
119

120
### Length Unit Conversions
121

122
When `length: true` (default), the plugin converts between absolute length units to find the shortest representation:
123

124
- **px** (pixels) ↔ **pc** (picas): 16px = 1pc
125
- **px** (pixels) ↔ **pt** (points): 3px = 4pt (1.33px = 1pt)  
126
- **px** (pixels) ↔ **in** (inches): 96px = 1in
127

128
```css
129
/* Input */
130
h1 { font-size: 16px; width: 192px; height: 120px; }
131

132
/* Output */
133
h1 { font-size: 1pc; width: 2in; height: 90pt; }
134
```
135

136
### Time Unit Conversions
137

138
When `time: true` (default), the plugin converts between time units:
139

140
- **ms** (milliseconds) ↔ **s** (seconds): 1000ms = 1s
141

142
```css
143
/* Input */
144
.fade { transition: opacity 500ms, transform 1500ms; }
145

146
/* Output */
147
.fade { transition: opacity .5s, transform 1.5s; }
148
```
149

150
### Angle Unit Conversions
151

152
When `angle: true` (default), the plugin converts between angle units:
153

154
- **deg** (degrees) ↔ **turn** (turns): 360deg = 1turn
155

156
```css
157
/* Input */
158
.rotate { transform: rotate(180deg); }
159

160
/* Output */
161
.rotate { transform: rotate(.5turn); }
162
```
163

164
### Zero Unit Removal
165

166
The plugin removes unnecessary units from zero values:
167

168
```css
169
/* Input */
170
.box { margin: 0px 0em 0% 0pc; }
171

172
/* Output */
173
.box { margin: 0 0 0 0; }
174
```
175

176
### Precision Control
177

178
When `precision` is set to a number, pixel values are rounded to that many decimal places:
179

180
```css
181
/* Input with precision: 2 */
182
.element { width: 6.66667px; }
183

184
/* Output */
185
.element { width: 6.67px; }
186
```
187

188
### Opacity Clamping
189

190
The plugin ensures `opacity` and `shape-image-threshold` values stay within the valid 0-1 range:
191

192
```css
193
/* Input */
194
.element { opacity: 1.5; }
195

196
/* Output */
197
.element { opacity: 1; }
198
```
199

200
## Browser Compatibility
201

202
The plugin respects browserslist configuration for IE11 compatibility. Certain properties retain percentage units on zero values when IE11 is targeted:
203

204
- `max-height`, `height`, `min-width` retain `0%` instead of `0` for IE11 compatibility
205

206
```javascript
207
// Target IE11 specifically
208
postcss([convertValues({
209
  overrideBrowserslist: ["ie 11"]
210
})]);
211
```
212

213
## Property Exclusions
214

215
The plugin automatically skips processing for:
216

217
- **Flex properties**: Properties containing "flex" maintain their original units
218
- **Custom properties**: CSS variables (starting with `--`) are not processed
219
- **Percentage-only properties**: `descent-override`, `ascent-override`, `font-stretch`, `size-adjust`, `line-gap-override`
220
- **Special zero cases**: `stroke-dashoffset`, `stroke-width`, `line-height` retain units even when zero
221
- **IE11 percentage preservation**: `max-height`, `height`, `min-width` retain `0%` instead of `0` when IE11 is targeted
222
- **Function contexts**: Within `calc()`, `color-mix()`, `min()`, `max()`, `clamp()`, `hsl()`, `hsla()`, `hwb()`, `linear()` functions, percentages are preserved
223
- **Keyframe properties**: `border-image-width`, `stroke-dasharray` in `@keyframes` contexts retain percentage units
224

225
## Types
226

227
```javascript { .api }
228
interface Plugin {
229
  postcssPlugin: string;
230
  prepare(result: Result): {
231
    OnceExit(css: Root): void;
232
  };
233
}
234

235
interface Result {
236
  opts?: {
237
    file?: string;
238
    from?: string;
239
    stats?: any;
240
    env?: string;
241
    path?: string;
242
  };
243
}
244

245
interface Root {
246
  walkDecls(callback: (decl: Declaration) => void): void;
247
}
248

249
interface Declaration {
250
  prop: string;
251
  value: string;
252
  parent?: any;
253
}
254
```