{"id":19114599,"url":"https://github.com/goodguyry/postcss-tidy-columns","last_synced_at":"2026-03-27T03:40:14.344Z","repository":{"id":32868498,"uuid":"137019787","full_name":"goodguyry/postcss-tidy-columns","owner":"goodguyry","description":"PostCSS plugin to manage column and margin alignment.","archived":false,"fork":false,"pushed_at":"2023-03-02T00:49:12.000Z","size":1695,"stargazers_count":5,"open_issues_count":5,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-26T09:48:33.289Z","etag":null,"topics":["alignment","columns","grid","postcss","postcss-plugin"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/goodguyry.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-06-12T05:07:40.000Z","updated_at":"2022-12-17T03:53:42.000Z","dependencies_parsed_at":"2024-06-21T12:55:32.839Z","dependency_job_id":null,"html_url":"https://github.com/goodguyry/postcss-tidy-columns","commit_stats":null,"previous_names":[],"tags_count":17,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodguyry%2Fpostcss-tidy-columns","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodguyry%2Fpostcss-tidy-columns/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodguyry%2Fpostcss-tidy-columns/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/goodguyry%2Fpostcss-tidy-columns/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/goodguyry","download_url":"https://codeload.github.com/goodguyry/postcss-tidy-columns/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251795387,"owners_count":21645019,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["alignment","columns","grid","postcss","postcss-plugin"],"created_at":"2024-11-09T04:43:54.462Z","updated_at":"2026-03-27T03:40:09.274Z","avatar_url":"https://github.com/goodguyry.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tidy Columns [![Build Status][ci-img]][ci] [![npm version][npmjs-img]][npmjs]\n\n[PostCSS] plugin to manage column alignment.\n\nTidy 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. \n\n**This plugin will not set layout for you. Layout is *your* job**.\n\nSee the [demo page][demo] to see it in action, and check out the [Wiki][wiki] for more about configuring the plugin.\n\n## Install\n\n```shell\nnpm install postcss-tidy-columns\n```\n\n## Example\n\n```js\nrequire('postcss-tidy-columns')({\n  columns: 12,\n  gap: '1.25rem',\n  edge: '2rem',\n  siteMax: '90rem',\n});\n```\n\n```css\n/* Input example, using the above plugins options */\ndiv {\n  tidy-span: 3;\n  tidy-offset-left: 2;\n}\n```\n\n```css\n/* Output example */\ndiv {\n  width: calc((((100vw - 2rem * 2) / 12 - 1.1458rem) * 3) + 1.25rem * 2);\n  max-width: calc((((90rem - 2rem * 2) / 12 - 1.1458rem) * 3) + 1.25rem * 2);\n  margin-left: calc((((100vw - 2rem * 2) / 12 - 1.1458rem) * 2) + 1.25rem * 2);\n}\n\n@media (min-width: 90rem) {\n  div {\n    margin-left: calc((((90rem - 2rem * 2) / 12 - 1.1458rem) * 2) + 1.25rem * 2);\n  }\n}\n```\n\n## Usage\n\n```js\npostcss([ require('postcss-tidy-columns') ]);\n```\n\nSee [PostCSS] docs for examples for your environment.\n\n## Contents\n\n* [Tidy Properties](#tidy-properties)\n* [Tidy Functions](#tidy-functions)\n* [Options](#options)\n* [Options Cascade](#options-cascade)\n* [Using CSS Custom Properties in setting values](#using-css-custom-properties-in-setting-values)\n\nSee the [Wiki][wiki] for additional documentation and tips.\n\n## Tidy Properties\n\n### Span\n\nThe `tidy-span` property specifies the number of columns and adjacent column gaps the element should span. Supports positive integer and decimal values.\n\n\u003e #### Syntax\n\u003e\n\u003e ```\n\u003e tidy-span: \u003cnumber\u003e;\n\u003e ```\n\n### Offsets\n\nThe `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\n\nOffsets use a [`siteMax`](#sitemax) breakpoint, since there's no `max-margin` CSS property.\n\n\u003e #### Syntax\n\u003e\n\u003e ```\n\u003e tidy-offset-left: \u003cnumber\u003e;\n\u003e tidy-offset-right: \u003cnumber\u003e;\n\u003e ```\n\n### Column Shorthand  \n\n`tidy-column` is a shorthand property for setting `tidy-offset-left`, `tidy-span`, and `tidy-offset-right` in one declaration.\n\nUse `none` to bypass a required value. A single offset value applies to both `left` and `right`.\n\n\u003e #### Syntax\n\u003e\n\u003e ```\n\u003e [ \u003cnumber\u003e | none ] / span \u0026\u0026 \u003cnumber\u003e [ / \u003cnumber\u003e ]?\n\u003e ```\n\u003e\n\u003e ```\n\u003e tidy-column: 3 / span 2 / 4;\n\u003e tidy-column: none / span 4 / 1;\n\u003e tidy-column: 1 / span 4;\n\u003e ```\n\n### Offset Shorthand  \n\n`tidy-offset` is a shorthand property for setting `tidy-offset-left` and `tidy-offset-right` in one declaration.\n\nUse `none` to bypass a required value. A single value applies to both `left` and `right`.\n\n\u003e #### Syntax\n\u003e\n\u003e ```\n\u003e  [ \u003cnumber\u003e | none ] [ / \u003cnumber\u003e ]? */\n\u003e ```\n\u003e\n\u003e ```\n\u003e tidy-offset: 3 / 4;\n\u003e tidy-offset: none / 1;\n\u003e tidy-offset: 1;\n\u003e ```\n\n## Tidy Functions\n\nThese 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.\n\nWhen 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.\n\n### Span Function\n\n`tidy-span()` and `tidy-span-full()` functions return the `span` property's `calc()` declaration for use in assigning widths.\n\n\u003e #### Syntax\n\u003e\n\u003e ```css\n\u003e /* property: tidy-span(number) */\n\u003e /* property: calc(tidy-span(number) expression) */\n\u003e\n\u003e div {\n\u003e   width: calc(tidy-span(3) + 4rem);\n\u003e }\n\u003e\n\u003e @media (min-width: 75rem) {\n\u003e   div {\n\u003e     width: calc(tidy-span-full(3) + 4rem);\n\u003e   }\n\u003e }\n\u003e ```\n\n### Offset Function\n\n`tidy-offset()` and `tidy-offset-full()` functions return the `offset` property's `calc()` declaration for use in positioning.\n\n\u003e #### Syntax\n\u003e\n\u003e ```css\n\u003e /* property: tidy-offset(number) */\n\u003e /* property: calc(tidy-offset(number) expression) */\n\u003e\n\u003e div {\n\u003e   left: calc(tidy-offset(1) + 2rem);\n\u003e }\n\u003e\n\u003e @media (min-width: 75rem) {\n\u003e   div {\n\u003e     left: calc(tidy-offset-full(1) + 2rem);\n\u003e   }\n\u003e }\n\u003e ```\n\n### Var Function\n\n`tidy-var()` function returns the specified option value.\n\n\u003e #### Syntax\n\u003e\n\u003e ```css\n\u003e /* property: tidy-var(string) */\n\u003e\n\u003e div {\n\u003e   margin-left: tidy-var(gap);\n\u003e   width: calc(tidy-var(siteMax) + tidy-var(edge) * 2);\n\u003e }\n\u003e ```\n\n## Options\n\n|Name|Type|Default|Description|\n|:--:|:--:|:-----:|:----------|\n|[`columns`](#columns)|`{Number}`|`undefined`|The number of grid columns.|\n|[`gap`](#gap)|`{String}`|`undefined`|The width of grid column gaps.|\n|[`siteMax`](#siteMax)|`{String}`|`undefined`|The max-width of the site.|\n|[`edge`](#edge)|`{String}`|`undefined`|The value of the site's edge padding.|\n|[`debug`](#debug)|`{Boolean}`|`false`|Add debug comments.|\n|[`breakpoints`](#breakpoints)|`{Object}`|`{}`|Breakpoint-specific configuration options.|\n\n_As an alternative to the [PostCSS] JavaScript API, some options may also be passed via stylesheet `@tidy` at-rules._\n\n### `columns`\n\nDeclares the number of columns in your design. Supports any positive integer.\n\n\u003e #### CSS Syntax\n\u003e\n\u003e ```\n\u003e @tidy columns \u003cnumber\u003e;\n\u003e ```\n\n### `gap`\n\nDeclares the width of the gap between each column. Supports any positive integer of unit [`px`|`em`|`rem`].\n\n\u003e #### CSS Syntax\n\u003e\n\u003e ```\n\u003e @tidy gap \u003clength\u003e;\n\u003e ```\n\n### `siteMax`\n\nDeclares 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.\n\nSupports any positive integer of unit [`px`|`em`|`rem`].\n\n\u003e #### CSS Syntax\n\u003e\n\u003e ```\n\u003e @tidy site-max \u003clength\u003e;\n\u003e ```\n\u003e \n\u003e Alternatively, use the camelCased JavaScript property.\n\u003e ```\n\u003e @tidy siteMax \u003clength\u003e;\n\u003e ```\n\n### `edge`\n\nSet `edge` to the non-cumulative value of the space between the content and the edge of the page.\n\nSupports any positive integer of unit [`px`|`em`|`rem`].\n\n\u003e #### CSS Syntax\n\u003e\n\u003e ```\n\u003e @tidy edge \u003clength\u003e;\n\u003e ```\n\n### `debug`\n\nSet `debug` to `true` to maintain the pre-processed CSS declaration as a comment.\n\n```css\ndiv {\n  /* tidy-span: 3 */\n  width: calc((((100vw - 2rem * 2) / 12 - 1.1458rem) * 3) + 1.25rem * 2);\n  max-width: calc((((90rem - 2rem * 2) / 12 - 1.1458rem) * 3) + 1.25rem * 2);\n}\n```\n\n\u003e #### CSS Syntax\n\u003e\n\u003e ```\n\u003e @tidy debug \u003cboolean\u003e;\n\u003e ```\n\n### `breakpoints`\n\nUse the `breakpoints` object to define a grid configuration that will change based on screen size.\n\n1. Define the small-screen grid in the root object.\n2. Define one or more `min-width` breakpoints at which the grid spec will change, and any configuration options that will change.\n4. The configuration settings cascade up from the root to the largest `breakpoint`.\n\n```js\nrequire('postcss-tidy-columns')({\n  columns: 9,\n  edge: '1rem',\n  gap: '0.625rem',\n  breakpoints: {\n    '48rem': {\n      columns: 12,\n      gap: '1rem'\n    },\n    '64rem': {\n      edge: '1.25rem',\n      siteMax: '90rem'\n    }\n  },\n});\n```\n\nSee the [Scoped Settings](https://github.com/goodguyry/postcss-tidy-columns/wiki/Scoped-Settings) Wiki page for more.\n\n## Options Cascade\n\n### Plugin options\n\nOptions passed directly to the plugin via the PostCSS JavaScript API.\n\n### Global at-rules\n\nGlobal options are defined via `@tidy` at-rules _outside_ of any selector blocks. Values declared here take precedence over those passed via the plugin options.\n\n### Local at-rules\n\nLocal 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.\n\n## Using CSS Custom Properties\n\n[CSS Custom Proprties](https://developer.mozilla.org/en-US/docs/Web/CSS/--*) are \nsupported in `@tidy` rules, with the following caveat:\n\n1. 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.\n\nSee the [Tips and Tricks](https://github.com/goodguyry/postcss-tidy-columns/wiki/Tips-and-Tricks) Wiki page for more.\n\n\u003c!-- links --\u003e\n[wiki]: https://github.com/goodguyry/postcss-tidy-columns/wiki\n[PostCSS]: https://github.com/postcss/postcss\n[ci-img]:  https://travis-ci.com/goodguyry/postcss-tidy-columns.svg?branch=master\n[ci]:      https://travis-ci.org/goodguyry/postcss-tidy-columns\n[npmjs-img]: https://badge.fury.io/js/postcss-tidy-columns.svg\n[npmjs]: https://badge.fury.io/js/postcss-tidy-columns\n[demo]: https://goodguyry.github.io/postcss-tidy-columns/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoodguyry%2Fpostcss-tidy-columns","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoodguyry%2Fpostcss-tidy-columns","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoodguyry%2Fpostcss-tidy-columns/lists"}