0
# PostCSS Normalize Positions
1

2
PostCSS Normalize Positions is a PostCSS plugin that normalizes CSS position keyword values by converting them to their equivalent length values. It transforms CSS background-position and position properties from human-readable keywords like 'bottom left' to more compact percentage or pixel values like '0 100%', optimizing CSS file size while maintaining the same visual appearance.
3

4
## Package Information
5

6
- **Package Name**: postcss-normalize-positions
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install postcss-normalize-positions`
10
- **Peer Dependencies**: PostCSS ^8.4.32
11

12
## Core Imports
13

14
```javascript
15
const postcssNormalizePositions = require('postcss-normalize-positions');
16
```
17

18
For modern ESM environments:
19

20
```javascript
21
import postcssNormalizePositions from 'postcss-normalize-positions';
22
```
23

24
TypeScript:
25

26
```typescript
27
import postcssNormalizePositions from 'postcss-normalize-positions';
28
import type { Plugin } from 'postcss';
29

30
const plugin: Plugin = postcssNormalizePositions();
31
```
32

33
## Basic Usage
34

35
```javascript
36
const postcss = require('postcss');
37
const postcssNormalizePositions = require('postcss-normalize-positions');
38

39
// Apply the plugin to CSS
40
const result = await postcss([
41
  postcssNormalizePositions()
42
])
43
.process(css, { from: undefined });
44

45
console.log(result.css);
46
```
47

48
**Example transformation:**
49

50
Input CSS:
51
```css
52
div {
53
  background-position: bottom left;
54
}
55
```
56

57
Output CSS:
58
```css
59
div {
60
  background-position: 0 100%;
61
}
62
```
63

64
## Capabilities
65

66
### Plugin Creator Function
67

68
Creates a PostCSS plugin instance that normalizes position keyword values in CSS declarations.
69

70
```javascript { .api }
71
/**
72
 * Creates a PostCSS plugin instance for normalizing position values
73
 * @returns {Plugin} PostCSS plugin object that processes CSS during the OnceExit phase
74
 */
75
function postcssNormalizePositions(): Plugin;
76
```
77

78
The plugin creator function has a marker property that identifies it as a PostCSS plugin:
79

80
```javascript { .api }
81
postcssNormalizePositions.postcss = true;
82
```
83

84
### Plugin Object
85

86
The returned plugin object implements the PostCSS plugin interface:
87

88
```javascript { .api }
89
interface Plugin {
90
  /** Plugin name identifier */
91
  postcssPlugin: "postcss-normalize-positions";
92
  /** Main plugin processing function that runs once after all other processing */
93
  OnceExit(css: Root): void;
94
}
95
```
96

97
## Supported CSS Properties
98

99
The plugin processes the following CSS properties and their values:
100

101
- `background` (background shorthand property)
102
- `background-position`
103
- `perspective-origin`
104
- Vendor-prefixed perspective-origin properties (e.g., `-webkit-perspective-origin`)
105

106
## Position Value Transformations
107

108
The plugin performs the following keyword-to-value transformations:
109

110
### Single Keywords
111
- `center` → `50%`
112
- `left` → `0`
113
- `right` → `100%`
114
- `top` → `0`
115
- `bottom` → `100%`
116

117
### Two-Value Combinations
118
- `left bottom` → `0 100%`
119
- `right top` → `100% 0`
120
- `center left` → `0`
121
- `center right` → `100%`
122
- `top center` → `50% 0`
123
- `bottom center` → `50% 100%`
124

125
### Mixed Value Handling
126
- `30% center` → `30%` (removes redundant center)
127
- Preserves existing percentage and pixel values
128
- Maintains three-value syntax without transformation
129

130
## Preservation Rules
131

132
The plugin preserves certain values without transformation:
133

134
### CSS Functions
135
- Math functions: `calc()`, `min()`, `max()`, `clamp()`
136
- Variable functions: `var()`, `env()`, `constant()`
137

138
### Complex Syntax
139
- Background size values (after `/` separator)
140
- Three-value position syntax
141
- Multiple background declarations (comma-separated)
142

143
### Performance Features
144
- Internal caching of transformed values
145
- Single-pass processing with `OnceExit` hook
146
- Efficient value parsing using postcss-value-parser
147

148
### Plugin Behavior
149
- Processes CSS declarations during PostCSS's `OnceExit` phase
150
- Uses internal Map cache to avoid re-processing identical values
151
- Safely handles malformed or invalid position values by leaving them unchanged
152
- Compatible with all PostCSS plugin ordering configurations
153

154
## Usage Examples
155

156
### Basic PostCSS Configuration
157

158
```javascript
159
// postcss.config.js
160
module.exports = {
161
  plugins: [
162
    require('postcss-normalize-positions')(),
163
    // other plugins...
164
  ]
165
};
166
```
167

168
### With Build Tools
169

170
```javascript
171
// webpack.config.js
172
module.exports = {
173
  module: {
174
    rules: [
175
      {
176
        test: /\.css$/,
177
        use: [
178
          'style-loader',
179
          'css-loader',
180
          {
181
            loader: 'postcss-loader',
182
            options: {
183
              postcssOptions: {
184
                plugins: [
185
                  require('postcss-normalize-positions')(),
186
                ]
187
              }
188
            }
189
          }
190
        ]
191
      }
192
    ]
193
  }
194
};
195
```
196

197
### Programmatic Usage
198

199
```javascript
200
const postcss = require('postcss');
201
const normalizePositions = require('postcss-normalize-positions');
202

203
async function processCSS(inputCSS) {
204
  const result = await postcss([
205
    normalizePositions()
206
  ]).process(inputCSS, { from: undefined });
207
  
208
  return result.css;
209
}
210

211
// Example usage
212
const css = `
213
  .hero {
214
    background: url(hero.jpg) center center no-repeat;
215
    background-position: right bottom;
216
  }
217
  .sidebar {
218
    perspective-origin: left top;
219
  }
220
`;
221

222
processCSS(css)
223
  .then(optimizedCSS => console.log(optimizedCSS));
224
```
225

226
Output:
227
```css
228
.hero {
229
  background: url(hero.jpg) 50% no-repeat;
230
  background-position: 100% 100%;
231
}
232
.sidebar {
233
  perspective-origin: 0 0;
234
}
235
```