PostCSS Helpers Functions

A set of useful PostCSS functions to help you write better CSS. This plugin allows you to simplify complex CSS expressions like grid spacing, responsive font sizes, and viewport-based calculations directly in your CSS.

Installation

npm install postcss-helpers-functions --save-dev

Usage

To use this plugin, include it in your PostCSS configuration file.

Example Configuration

1. PostCSS Configuration (postcss.config.js):

import postcssHelpersFunctions from 'postcss-helpers-functions';

export default {
    plugins: [
        postcssHelpersFunctions()
    ]
};

2. CSS Input Example:

.example {
    width: grid-space(6/12, 1);
    font-size: responsive-value(16px, 32px, 1200);
    height: dvh(100);
    padding: svh(5);
    margin: rem(24px);
}

3. Output CSS:

.example {
    width: calc(0.5 * (calc(var(--vw, 1vw) * 100) - 2 * var(--grid-margin, 0px)) - 0.5 * var(--grid-gutter, 0px) + 1 * var(--grid-gutter, 0px));
    font-size: clamp(16px, calc(0.02666666666666667 * var(--vw, 1vw) * 100), 32px);
    height: calc(100 * var(--dvh, 1dvh));
    padding: calc(5 * var(--svh, 1svh));
    margin: 1.5rem;
}

Features

Helper Functions

This plugin provides several helper functions to streamline CSS calculations.

| Function | Description | Example Usage | Example Output | |-----------------------|-------------------------------------------------------------------------------------------------|---------------------------------------|---------------------------------------------------------------------------------------------------------------| | gridSpace(frac, inset) | Calculates grid spacing based on a fraction of the grid and an optional gutter inset. | grid-space(6/12, 1) | calc(0.5 * (calc(var(--vw) * 100) - 2 * var(--grid-margin)) - 0.5 * var(--grid-gutter) + 1 * var(--grid-gutter)) | | responsiveValue(min, max, breakpoint) | Creates a responsive value using CSS clamp() for fluid scaling. | responsive-value(16px, 32px, 1200) | clamp(16px, calc(0.026666 * var(--vw) * 100), 32px) | | rem(pixels, rootSize) | Converts pixel values to rem units based on a configurable root font size. | rem(24px) or rem(24) | 1.5rem | | dvh(percentage) | Calculates a percentage of the dynamic viewport height. | dvh(100) | calc(100 * var(--dvh, 1dvh)) | | svh(percentage) | Calculates a percentage of the small viewport height. | svh(50) | calc(50 * var(--svh, 1svh)) | | lvh(percentage) | Calculates a percentage of the large viewport height. | lvh(100) | calc(100 * var(--lvh, 1lvh)) | | vw(percentage) | Calculates a percentage of the viewport width. | vw(100) | calc(100 * var(--vw, 1vw)) |

Detailed Function Descriptions

1. Grid Space Calculation (gridSpace)

Generates a CSS calc() string for calculating a fraction of the grid width with an optional gutter inset.

Syntax:

gridSpace(fraction, inset = 0)

Parameters:

• fraction (number): The fraction of the grid (e.g., 6/12 or 0.5 for half the grid).
• inset (number, optional): Multiplier for the grid gutter (default: 0).

Example:

width: grid-space(6/12, 1);

Output:

width: calc(0.5 * (calc(var(--vw) * 100) - 2 * var(--grid-margin)) - 0.5 * var(--grid-gutter) + 1 * var(--grid-gutter));

2. Responsive Value Calculation (responsiveValue)

Generates a CSS clamp() string for scaling values between a minimum and maximum size based on a breakpoint.

Syntax:

responsiveValue(minSize, maxSize, breakpoint)

Parameters:

• minSize (string): Minimum value (e.g., 16px).
• maxSize (string): Maximum value (e.g., 32px).
• breakpoint (number): Maximum breakpoint value (e.g., 1200 for 1200px).

Example:

font-size: responsive-value(16px, 32px, 1200);

Output:

font-size: clamp(16px, calc(0.026666 * var(--vw, 1vw) * 100), 32px);

3. Rem Unit Conversion (rem)

Converts pixel values to rem units based on a configurable root font size.

Syntax:

rem(pixels, rootSize = 16)

Parameters:

• pixels (number | string): The pixel value to convert to rem (accepts both 24 and "24px").
• rootSize (number, optional): The root font size in pixels (default: 16).

Example:

font-size: rem(24px);
margin: rem(16);
padding: rem(8px, 18);

Output:

font-size: 1.5rem;
margin: 1rem;
padding: 0.444rem;

4. Viewport Height Calculations (dvh, svh, lvh)

Generates a CSS calc() string for dynamic viewport height values.

Syntax:

dvh(percentage)
svh(percentage)
lvh(percentage)

Example:

height: dvh(100);
padding: svh(5);

Output:

height: calc(100 * var(--dvh, 1dvh));
padding: calc(5 * var(--svh, 1svh));