postcss-tidy-columns

PostCSS Tidy Columns

PostCSS plugin to manage column alignment.

PostCSS Tidy Columns sets an element's width based on a user-defined grid of columns and gaps using calculations based on vw units, which allows for easy vertical alignment of elements.

PostCSS Tidy Columns does not set layout. Positioning elements is your job.

Install

npm install postcss-tidy-columns

Example

/* Input example */
@tidy columns 12;
@tidy gap 1.25rem;
@tidy edge 2rem;
@tidy site-max 90rem;

div {
	tidy-span: 3;
	tidy-offset-left: 2;
}

/* Output example */
div {
	width: calc((((100vw - 2rem * 2) / 12 - 1.1458rem) * 3) + 1.25rem * 2);
	max-width: calc((((90rem - 2rem * 2) / 12 - 1.1458rem) * 3) + 1.25rem * 2);
	margin-left: calc((((100vw - 2rem * 2) / 12 - 1.1458rem) * 2) + 1.25rem * 2);
}

@media (min-width: 90rem) {
	div {
		margin-left: calc((((90rem - 2rem * 2) / 12 - 1.1458rem) * 2) + 1.25rem * 2);
	}
}

Usage

postcss([ require('postcss-tidy-columns') ])

See PostCSS docs for examples for your environment.

Contents

• Tidy Properties
• Tidy Functions
• Options
• Options Cascade
• Using CSS Custom Properties in setting values

See the Wiki for additional documentation and tips.

Tidy Properties

Span

The tidy-span property specifies the number of columns and adjacent column gaps the element should span. Supports positive and decimal values.

Syntax

tidy-span: <number>;

Offsets

The tidy-offset-left and tidy-offset-right properties specify the number of columns and adjacent column gaps the element's margin should span. Supports positive, negative, and decimal values

Offsets use a siteMax breakpoint, since there's no max-margin CSS property.

Syntax

tidy-offset-left: <number>;
tidy-offset-right: <number>;

Column Shorthand

tidy-column is a shorthand property for setting tidy-offset-left, tidy-span, and tidy-offset-right in one declaration.

Use none to bypass a required value.

Syntax

/* [ <number> | none ] / span && <number> [ / <number> ]? */

tidy-column: 3 / span 2 / 4;
tidy-column: none / span 4 / 1;
tidy-column: 1 / span 4;

Offset Shorthand

tidy-offset is a shorthand property for setting tidy-offset-left and tidy-offset-right in one declaration.

Use none to bypass a required value.

Syntax

/* [ <number> | none ] [ / <number> ]? */

tidy-offset: 3 / 4;
tidy-offset: none / 1;
tidy-offset: 1; /* 1 / none */

Tidy Functions

These functions are provided for incorporating the tidy- properties' output without using the properties. These can be used on their own or nested inside a calc() function, and allow for more control over the declarations added by the plugin.

When using these functions, the siteMax-based static value will not be output. Use the tidy-span-full() and tidy-offset-full() functions to set the static span and offset widths, respectively.

Span Function

tidy-span() and tidy-span-full() functions return the span property's calc() declaration for use in assigning widths.

Syntax

/* property: tidy-span(number) */
/* property: calc(tidy-span(number) expression) */

div {
	width: calc(tidy-span(3) + 4rem);
}

@media (min-width: 75rem) {
	div {
		width: calc(tidy-span-full(3) + 4rem);
	}
}

Offset Function

tidy-offset() and tidy-offset-full() functions return the offset property's calc() declaration for use in positioning.

Syntax

/* property: tidy-offset(number) */
/* property: calc(tidy-offset(number) expression) */

div {
	left: calc(tidy-offset(1) + 2rem);
}

@media (min-width: 75rem) {
	div {
		left: calc(tidy-offset-full(1) + 2rem);
	}
}

Options

Name	Type	Default	Description
columns	{Number}	12	The number of grid columns.
gap	{String}	undefined	The width of grid column gaps.
siteMax	{String}	undefined	The max-width of the site.
edge	{String}	undefined	The value of the site's edge padding.
addGap	{Boolean}	false	Add a right gap margin to column declarations.

As an alternative to the PostCSS JavaScript API, options may also be passed via stylesheet @tidy at-rules.

columns

Declares the number of columns in your design. Supports any positive integer.

CSS Syntax

@tidy columns <number>;

gap

Declares the width of the gap between each column. Supports any positive integer of unit [px|em|rem].

CSS Syntax

@tidy gap <length> [ / <boolean> ]?;

See addGap for more about the CSS syntax.

siteMax

Declares the max-width of the site, at which point the site transitions from fluid width to static width. Setting a siteMax value ensures the column and margin widths are correct once the site width is static.

Supports any positive integer of unit [px|em|rem].

CSS Syntax

@tidy site-max <length>;

/* Alternatively use the camelCased JavaScript property */
@tidy siteMax <length>;

edge

Set edge to the non-cumulative value of the space between the content and the edge of the page.

Supports any positive integer of unit [px|em|rem].

CSS Syntax

@tidy edge <length>;

addGap

Declares whether or not to add a gap-wide margin-right to the columns.

When this is set to true, a :last-of-type rule will be added to reset the margin-right to 0 for the last item.

CSS Syntax

/**
 * Declared as a boolean value after the `gap` value.
 * Must be preceeded by a slash.
 */
@tidy gap <length> / <boolean>;

Options Cascade

Plugin options

Options passed directly to the plugin via the PostCSS JavaScript API.

Global at-rules

Global options are defined via @tidy at-rules outside of any selector blocks. Values declared here take precedence over those passed via the plugin options.

Local at-rules

Local options are defined via @tidy at-rules inside a selector block and are scoped to that rule block. Values declared here take precedence over the global at-rules.

Using CSS Custom Properties in setting values

CSS Custom Proprties are supported in @tidy rules, with the following caveats:

1. Due to the nature of CSS Custom Properties, particularly the inability to use them in media query parmeters, a CSS Custom Property used as the @tidy site-max value will throw an error.
2. The @tidy gap custom property value must only contain its length, and not its boolean addGap portion of the gap shorthand.

See the Tips and Tricks Wiki page for more.

Changelog

0.3.4

Fixed

• Fixes an issue where only the first of multiple tidy- functions in the same declaration value was being processed (#22)