0
# PostCSS Normalize Display Values
1

2
PostCSS Normalize Display Values is a PostCSS plugin that normalizes CSS display property values by converting multiple-value display syntaxes into their equivalent single-value forms. This enables better browser compatibility and reduces CSS file size by transforming modern CSS display syntax into legacy-compatible values.
3

4
## Package Information
5

6
- **Package Name**: postcss-normalize-display-values
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install postcss-normalize-display-values`
10

11
## Core Imports
12

13
```javascript
14
const postcssNormalizeDisplayValues = require("postcss-normalize-display-values");
15
```
16

17
For ES modules (TypeScript/modern JavaScript projects use CommonJS export format):
18

19
```javascript
20
import postcssNormalizeDisplayValues from "postcss-normalize-display-values";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const postcss = require("postcss");
27
const postcssNormalizeDisplayValues = require("postcss-normalize-display-values");
28

29
// Use with PostCSS
30
const result = await postcss([
31
  postcssNormalizeDisplayValues()
32
]).process(css, { from: undefined });
33

34
console.log(result.css);
35
```
36

37
With a build tool like Webpack or Vite:
38

39
```javascript
40
// postcss.config.js
41
module.exports = {
42
  plugins: [
43
    require("postcss-normalize-display-values")(),
44
    // other plugins...
45
  ],
46
};
47
```
48

49
## Capabilities
50

51
### Plugin Creator
52

53
Creates a PostCSS plugin instance that processes CSS display property values and converts multi-value syntaxes to single-value equivalents.
54

55
```typescript { .api }
56
/**
57
 * Creates a PostCSS plugin that normalizes display property values
58
 * This is the default export of the postcss-normalize-display-values package
59
 * @returns PostCSS Plugin instance
60
 */
61
function pluginCreator(): Plugin;
62
```
63

64
**Usage Example:**
65

66
```css
67
/* Input */
68
div {
69
  display: inline flow-root;
70
}
71

72
/* Output */
73
div {
74
  display: inline-block;
75
}
76
```
77

78
### Display Value Transformations
79

80
The plugin automatically converts the following display value combinations:
81

82
#### Block-level Display Values
83

84
```css
85
/* Multi-value → Single-value */
86
display: block flow;           /* → block */
87
display: block flow-root;      /* → flow-root */
88
display: list-item block flow; /* → list-item */
89
display: block flex;           /* → flex */
90
display: block grid;           /* → grid */
91
display: block table;          /* → table */
92
```
93

94
#### Inline-level Display Values
95

96
```css
97
/* Multi-value → Single-value */
98
display: inline flow;          /* → inline */
99
display: inline flow-root;     /* → inline-block */
100
display: inline flex;          /* → inline-flex */
101
display: inline grid;          /* → inline-grid */
102
display: inline table;         /* → inline-table */
103
display: inline ruby;          /* → ruby */
104
display: inline flow list-item; /* → inline list-item */
105
```
106

107
#### Special Display Values
108

109
```css
110
/* Multi-value → Single-value */
111
display: run-in flow;          /* → run-in */
112
display: table-cell flow;      /* → table-cell */
113
display: table-caption flow;   /* → table-caption */
114
display: ruby-base flow;       /* → ruby-base */
115
display: ruby-text flow;       /* → ruby-text */
116
```
117

118
### Plugin Behavior
119

120
The plugin:
121

122
- **Processes only `display` properties** (case-insensitive matching)
123
- **Uses caching** to avoid redundant transformations of duplicate values
124
- **Preserves original values** when no transformation mapping exists
125
- **Handles CSS variables** and complex expressions by passing them through unchanged
126
- **Ignores empty or malformed values** gracefully
127
- **Executes during PostCSS OnceExit phase** for optimal performance
128

129
## Types
130

131
```typescript { .api }
132
/**
133
 * PostCSS Plugin type from the postcss package
134
 */
135
interface Plugin {
136
  postcssPlugin: string;
137
  prepare(): {
138
    OnceExit(css: Root): void;
139
  };
140
}
141

142
/**
143
 * Plugin creator function signature
144
 */
145
type PluginCreator = () => Plugin;
146

147
/**
148
 * Plugin marker property indicating PostCSS compatibility
149
 */
150
interface PluginCreator {
151
  postcss: true;
152
}
153
```
154

155
## Error Handling
156

157
The plugin is designed to be fault-tolerant:
158

159
- **Invalid display values**: Passed through unchanged
160
- **CSS variables**: Preserved as-is (e.g., `display: var(--my-display)`)
161
- **Complex expressions**: Left untouched (e.g., `display: var(--foo) var(--bar)`)
162
- **Non-display properties**: Ignored completely
163
- **Empty values**: Skipped without error
164

165
## Browser Compatibility
166

167
This plugin helps maintain compatibility by converting newer CSS Display Level 3 multi-value syntax to widely-supported single-value equivalents. The transformations are based on the [CSS Display Level 3 specification](https://drafts.csswg.org/css-display/#the-display-properties).
168

169
Modern browsers support both syntaxes, but older browsers and some CSS minifiers work better with single-value display properties.