0
# PostCSS Gap Properties
1

2
PostCSS Gap Properties is a PostCSS plugin that enables you to use modern CSS Grid Layout gap properties (`gap`, `column-gap`, `row-gap`) with automatic fallback generation for older browsers. It transforms modern gap shorthand properties into their legacy `grid-gap` equivalents while maintaining the original syntax for forward compatibility.
3

4
## Package Information
5

6
- **Package Name**: postcss-gap-properties
7
- **Package Type**: npm
8
- **Language**: TypeScript/JavaScript
9
- **Node.js**: Requires Node.js >=18
10
- **Installation**: `npm install postcss-gap-properties --save-dev`
11
- **Peer Dependencies**: postcss ^8.4
12

13
## Core Imports
14

15
ESM (ES Modules):
16

17
```javascript
18
import postcssGapProperties from 'postcss-gap-properties';
19
import { pluginOptions } from 'postcss-gap-properties';
20
```
21

22
CommonJS:
23

24
```javascript
25
const postcssGapProperties = require('postcss-gap-properties');
26
```
27

28
## Basic Usage
29

30
```javascript
31
import postcss from 'postcss';
32
import postcssGapProperties from 'postcss-gap-properties';
33

34
// Use with default options (preserve: true)
35
const result = await postcss([
36
  postcssGapProperties()
37
]).process(css, { from: 'input.css' });
38

39
// Use with custom options
40
const result = await postcss([
41
  postcssGapProperties({ preserve: false })
42
]).process(css, { from: 'input.css' });
43
```
44

45
With TypeScript:
46

47
```typescript
48
import postcss from 'postcss';
49
import postcssGapProperties, { pluginOptions } from 'postcss-gap-properties';
50

51
const options: pluginOptions = { preserve: false };
52
const result = await postcss([
53
  postcssGapProperties(options)
54
]).process(css, { from: 'input.css' });
55
```
56

57
**CSS Transformation Example:**
58

59
Input CSS:
60
```css
61
.standard-grid {
62
  display: grid;
63
  gap: 20px;
64
}
65

66
.spaced-grid {
67
  display: grid;
68
  column-gap: 40px;
69
  row-gap: 20px;
70
}
71
```
72

73
Output CSS (with default options):
74
```css
75
.standard-grid {
76
  display: grid;
77
  grid-gap: 20px;
78
  gap: 20px;
79
}
80

81
.spaced-grid {
82
  display: grid;
83
  grid-column-gap: 40px;
84
  column-gap: 40px;
85
  grid-row-gap: 20px;
86
  row-gap: 20px;
87
}
88
```
89

90
## Capabilities
91

92
### Plugin Creator Function
93

94
Creates a PostCSS plugin instance that transforms gap properties into legacy grid-gap fallbacks.
95

96
```typescript { .api }
97
import type { PluginCreator } from 'postcss';
98

99
/**
100
 * Creates a PostCSS plugin for transforming gap properties
101
 * @param opts - Optional plugin configuration
102
 * @returns PostCSS plugin instance
103
 */
104
declare const postcssGapProperties: PluginCreator<pluginOptions>;
105
export default postcssGapProperties;
106
```
107

108
## Types
109

110
```typescript { .api }
111
/** postcss-gap-properties plugin options */
112
export type pluginOptions = {
113
  /** Preserve the original notation. default: true */
114
  preserve?: boolean;
115
};
116
```
117

118
The plugin automatically:
119
- Detects `gap`, `column-gap`, and `row-gap` properties within grid containers (`display: grid`)
120
- Generates appropriate fallback properties (`grid-gap`, `grid-column-gap`, `grid-row-gap`)
121
- Avoids duplicate fallbacks if they already exist
122
- Optionally preserves or removes original properties based on the `preserve` option
123

124
**Configuration Options:**
125

126
- **`preserve`** (boolean, default: `true`): When `true`, keeps both the original gap property and the generated fallback. When `false`, removes the original property, leaving only the fallback.
127

128
**Usage Examples:**
129

130
```javascript
131
// Preserve original properties (default behavior)
132
postcssGapProperties({ preserve: true });
133

134
// Remove original properties, keep only fallbacks
135
postcssGapProperties({ preserve: false });
136

137
// Use default options
138
postcssGapProperties();
139
```
140

141
### Plugin Properties
142

143
The plugin function includes the standard PostCSS plugin marker:
144

145
```typescript { .api }
146
/** PostCSS plugin marker indicating this is a PostCSS plugin */
147
postcssGapProperties.postcss: true;
148
```
149

150
## Supported CSS Properties
151

152
The plugin transforms these modern CSS gap properties:
153

154
- **`gap`**: Shorthand for both row and column gaps in grid layouts
155
- **`column-gap`**: Specifies the gap between columns in grid layouts  
156
- **`row-gap`**: Specifies the gap between rows in grid layouts
157

158
## Generated Fallback Properties
159

160
For each modern gap property, the plugin generates a corresponding legacy property:
161

162
- `gap` → `grid-gap`
163
- `column-gap` → `grid-column-gap`
164
- `row-gap` → `grid-row-gap`
165

166
## Browser Compatibility
167

168
This plugin enables the use of modern gap properties while maintaining compatibility with older browsers that only support the prefixed `grid-*` variants. The plugin only processes properties within grid containers (`display: grid`) and supports CSS custom properties (variables) in gap values.
169

170
## Error Handling
171

172
The plugin includes built-in safeguards:
173
- Only processes declarations within grid containers
174
- Checks for existing grid-prefixed declarations to prevent duplicates
175
- Safely handles nested CSS structures and CSS nesting syntax
176
- Works with CSS custom properties and complex values