Flex Gap Polyfill

This is a pure CSS polyfill using PostCSS to emulate flex gap using margins.

Known limitations

Must use a wrapper div when using margin: auto or background.
Percentage gaps aren't reliable if the container is not full width of parent container
Width of flex items with percentages vary slightly from spec because of negative margin on container.

View the demo page for various test cases of the polyfill in action.

Example

.container {
    display: flex;
    gap: 40px;
}

Becomes:

/* Output simplified for purpose of example */

.container > * {
    --fgp-parent-gap-row: 40px;
    --fgp-parent-gap-column: 40px;
    --fgp-margin-top: calc(var(--fgp-gap-row) + var(--orig-margin-top, 0px));
    --fgp-margin-left: calc(
        var(--fgp-gap-column) + var(--orig-margin-left, 0px)
    );
    margin-top: var(--fgp-margin-top);
    margin-left: var(--fgp-margin-left);
}

.container {
    --fgp-gap: var(--has-fgp, 40px);
    --fgp-gap-row: 40px;
    --fgp-gap-column: 40px;
    --fgp-margin-top: calc(
        var(--fgp-parent-gap-row, 0px) - var(--fgp-gap-row) + var(--orig-margin-top, 0px)
    );
    --fgp-margin-left: calc(
        var(--fgp-parent-gap-column, 0px) - var(--fgp-gap-column) + var(--orig-margin-left, 0px)
    );
    display: flex;
    gap: var(--fgp-gap, 0px);
    margin-top: var(--fgp-margin-top, var(--orig-margin-top));
    margin-left: var(--fgp-margin-left, var(--orig-margin-left));
}

The polyfill emulates flex gap by adding margins to each child element and applying a negative margin to the container.

NEW Now works regardless of whether display: flex and gap are used in the same rule (see Options for ways to optimise)
Works with unlimited nested elements with any combination of units, px > px, px > %, % > %, etc
No additional class names or divs needed (except when using margin: auto or background)
Works even when margin already exists on element (inline styles not supported)
Style margin, borders and padding as normal
Supports gap, row-gap and column-gap

Browser support

Supports all current modern browsers, Edge, Firefox, Chrome, Safari, Opera (any browser that supports calc() and var()).

Usage

Add Flex Gap Polyfill to your project:

npm install flex-gap-polyfill postcss --save-dev

Use Flex Gap Polyfill to process your CSS:

const flexGapPolyfill = require("flex-gap-polyfill");

flexGapPolyfill.process(YOUR_CSS /*, processOptions, pluginOptions */);

Or use it as a PostCSS plugin:

const postcss = require("postcss");
const flexGapPolyfill = require("flex-gap-polyfill");

postcss([flexGapPolyfill(/* pluginOptions */)]).process(
    YOUR_CSS /*, processOptions */
);

Options

only

Type: Array Default: undefined

When true polyfill will only apply when display: flex | inline-flex and gap are used in the same rule. Provide an array of selectors to match additional rules. Can be strings or regexes. Inlcude /* apply fgp */ within a rule to manually apply the polyfill.
flexGapNotSupported

Type: String Default: false

Manually specify a selector to use when flex gap is not supported by detection via JavaScript, eg flexGapNotSupported: '.flex-gap-not-supported'.