postcss-tidy-columns

Tidy Columns

PostCSS plugin to manage column alignment.

Tidy Columns sets widths and margins, based on a user-defined configuration, with the goal that any elements along the vertical axis that should be aligned, are.

This plugin will not set layout for you. Layout is your job.

See the demo page to see it in action, and check out the Wiki for more about configuring the plugin.

Install

npm install postcss-tidy-columns

Example

require('postcss-tidy-columns')({
  columns: 12,
  gap: '1.25rem',
  edge: '2rem',
  siteMax: '90rem',
});

/* Input example, using the above plugins options */
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 integer 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 and negative integer 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. A single offset value applies to both left and right.

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. A single value applies to both left and right.

Syntax

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

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

Tidy Functions

These functions are provided for incorporating the tidy- properties' output without using the properties themselves. 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);
  }
}

Var Function

tidy-var() function returns the specified option value.

Syntax

/* property: tidy-var(string) */

div {
  margin-left: tidy-var(gap);
  width: calc(tidy-var(siteMax) + tidy-var(edge) * 2);
}

Options

Name	Type	Default	Description
columns	{Number}	undefined	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.
debug	{Boolean}	false	Add debug comments.
breakpoints	{Object}	{}	Breakpoint-specific configuration options.

As an alternative to the PostCSS JavaScript API, some 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>;

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>;

debug

Set debug to true to maintain the pre-processed CSS declaration as a comment.

div {
  /* tidy-span: 3 */
  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);
}

CSS Syntax

@tidy debug <boolean>;

breakpoints

Use the breakpoints object to define a grid configuration that will change based on screen size.

• Define the small-screen grid in the root object.
• Define one or more min-width breakpoints at which the grid spec will change, and any configuration options that will change.
• The configuration settings cascade up from the root to the largest breakpoint.

require('postcss-tidy-columns')({
  columns: 9,
  edge: '1rem',
  gap: '0.625rem',
  breakpoints: {
    '48rem': {
      columns: 12,
      gap: '1rem'
    },
    '64rem': {
      edge: '1.25rem',
      siteMax: '90rem'
    }
  },
});

See the Scoped Settings Wiki page for more.

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

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

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

See the Tips and Tricks Wiki page for more.

Changelog

0.4.0

Added

• Support for configuring different grid specs across multiple breakpoints (#20)
• Use the tidy-var() function to retrieve option values in declarations (#27, #32)
• Use the debug option to maintain the input declaration as a comment (#45, #48)

Changed

• Single offset values in tidy-column and tidy-offset shorthand properties will now apply to all missing values (#25, #36)

Fixed

• Updates dependencies to fix known vulnerabilities (#26, #42)
• tidy-* functions nested within a calc() function are properly detected and escaped (#34)
• Shorthand properties now accept documented values (#36)
• Corrects an issue with unitless non-zero config values not being ignored (#39)

Removed

• The addGap option for automatically adding the grid gap margin to column elements (#24)
• Support for Node 6 (#41)