PostCSS Gap Properties

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.

Package Information

• Package Name: postcss-gap-properties
• Package Type: npm
• Language: TypeScript/JavaScript
• Node.js: Requires Node.js >=18
• Installation: npm install postcss-gap-properties --save-dev
• Peer Dependencies: postcss ^8.4

Core Imports

ESM (ES Modules):

import postcssGapProperties from 'postcss-gap-properties';
import { pluginOptions } from 'postcss-gap-properties';

CommonJS:

const postcssGapProperties = require('postcss-gap-properties');

Basic Usage

import postcss from 'postcss';
import postcssGapProperties from 'postcss-gap-properties';

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

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

With TypeScript:

import postcss from 'postcss';
import postcssGapProperties, { pluginOptions } from 'postcss-gap-properties';

const options: pluginOptions = { preserve: false };
const result = await postcss([
  postcssGapProperties(options)
]).process(css, { from: 'input.css' });

CSS Transformation Example:

Input CSS:

.standard-grid {
  display: grid;
  gap: 20px;
}

.spaced-grid {
  display: grid;
  column-gap: 40px;
  row-gap: 20px;
}

Output CSS (with default options):

.standard-grid {
  display: grid;
  grid-gap: 20px;
  gap: 20px;
}

.spaced-grid {
  display: grid;
  grid-column-gap: 40px;
  column-gap: 40px;
  grid-row-gap: 20px;
  row-gap: 20px;
}

Capabilities

Plugin Creator Function

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

import type { PluginCreator } from 'postcss';

/**
 * Creates a PostCSS plugin for transforming gap properties
 * @param opts - Optional plugin configuration
 * @returns PostCSS plugin instance
 */
declare const postcssGapProperties: PluginCreator<pluginOptions>;
export default postcssGapProperties;

Types

/** postcss-gap-properties plugin options */
export type pluginOptions = {
  /** Preserve the original notation. default: true */
  preserve?: boolean;
};

The plugin automatically:

• Detects gap, column-gap, and row-gap properties within grid containers (display: grid)
• Generates appropriate fallback properties (grid-gap, grid-column-gap, grid-row-gap)
• Avoids duplicate fallbacks if they already exist
• Optionally preserves or removes original properties based on the preserve option

Configuration Options:

• 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.

Usage Examples:

// Preserve original properties (default behavior)
postcssGapProperties({ preserve: true });

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

// Use default options
postcssGapProperties();

Plugin Properties

The plugin function includes the standard PostCSS plugin marker:

/** PostCSS plugin marker indicating this is a PostCSS plugin */
postcssGapProperties.postcss: true;

Supported CSS Properties

The plugin transforms these modern CSS gap properties:

• gap: Shorthand for both row and column gaps in grid layouts
• column-gap: Specifies the gap between columns in grid layouts
• row-gap: Specifies the gap between rows in grid layouts

Generated Fallback Properties

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

• gap → grid-gap
• column-gap → grid-column-gap
• row-gap → grid-row-gap

Browser Compatibility

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.

Error Handling

The plugin includes built-in safeguards:

• Only processes declarations within grid containers
• Checks for existing grid-prefixed declarations to prevent duplicates
• Safely handles nested CSS structures and CSS nesting syntax
• Works with CSS custom properties and complex values