@ignota/susy.js: JavaScript power tools for web layout.

Susy.js is a JavaScript port of the powerful Susy layout toolkit for Sass. It makes the power and flexibility of Susy's venerable grid primitives available to your favorite CSS-in-JS solution---anything from Styled Components to inline React styles---so that you can build your own damn grids with your own damn tools.

Resources

• Release notes.
• Guidelines for contributing.
• Code of conduct.
• GPL-3.0 license.

Installation

yarn add @ignota/susy.js

Usage

import {
    at,
    configure,
    first,
    gutter,
    slice,
    span,
} from '@ignota/susy.js'

configure({
    columns: [1, 2, 1, 1, 3, 1, 3, 2, 1, 4],
    gutters: 0.5,
})

console.log(span(first(3), of(slice(6, at(3))))) // 44.44444444444444%
console.log(gutter(slice(6, at(3))))             // 3.7037037037037033%

Settings

The package exposes a function called configure that takes an object as its only argument. You can customize your default grid by setting the following keys:

• columns. A list of columns, either unitless numbers (e.g., [1, 3, 5]), strings with CSS lengths (e.g., ['1em', '3em', '5em']), or a mix of both (e.g., [1, '3em', 5]). You may import the function repeat to quickly create symmetrical grids: e.g., repeat(10), repeat(10, '1em'), or ['120px', repeat(4), '120px'].
• gutters. A unitless fraction as a number (e.g., 0.5) or an explicit width as a string (e.g., '1em').
• spread and containerSpread. A string, either narrow, wide, or wider, that defines how grid elements and grid containers handle gutters. See the Oddbird blog for more details.

These configuration options may also be passed into the core Susy functions as their final argument.

Susy Functions

The core Susy API is exposed as three functions, gutter, slice, and span, which map to the Sass functions susy-gutter, susy-slice, and susy-span. These can be imported as named imports directly from the package root. All three accept a variadic argument list, which should start with a list of shorthand functions and may optionally end with an object containing settings to be applied to the current calculation.

An additional helper function, halfGutter, is also exposed; it returns half the width of a single gutter, handling the ugly conversion from a string to a number and back.

Shorthand

Susy's Sass implementation turns on a very friendly shorthand for defining grid spans and context:

$col-width: su-span(3 at 2);

Susy.js does its level best to preserve the friendliness of the API through a set of shorthand functions:

• all
• alpha(count)
• at(location)
• first(count)
• last(count)
• narrow
• of(...shorthand)
• omega(count)
• setGutters(gutters)
• wide
• wider

Shorthand may also include bare numbers or arrays, which will be treated as column counts.

Examples

span(2)
span(2, of(6))
span(6, at(3))
span(first(3), of(slice(6, at(3))))

gutter()
gutter(6)
gutter(wider)
gutter(slice(6, at(3)))

Familiarity with the Sass syntax is highly recommended, and will make picking up the JavaScript version a more-or-less breeze.

SVG Grid Plugin

Susy.js also implement's Susy's SVG grid plugin:

import {
    svgGrid,
    wider,
} from '@ignota/susy.js'

<div style={{
    backgroundAttachment: 'scroll',
    backgroundImage: svgGrid(6, wider),
    backgroundRepeat: 'no-repeat',
}}>
    I'm a grid container!
</div>

<div style="background-attachment:scroll;background-image:url("data:image/svg+xml,<svg fill='url(%23susyjs-svg-gradient)' width='100%' xmlns='http://www.w3.org/2000/svg'><defs><linearGradient id='susyjs-svg-gradient' spreadMethod='pad' x1='0%' x2='100%' y1='0%' y2='0%'><stop offset='0%' style='stop-color:hsla(120, 50%, 50%, 0.5);' /><stop offset='100%' style='stop-color:hsla(120, 50%, 75%, 0.5);' /></linearGradient></defs><rect height='100%' width='12.903225806451612%' x='3.225806451612903%' /><rect height='100%' width='12.903225806451612%' x='19.35483870967742%' /><rect height='100%' width='12.903225806451612%' x='35.483870967741936%' /><rect height='100%' width='12.903225806451612%' x='51.612903225806456%' /><rect height='100%' width='12.903225806451612%' x='67.74193548387096%' /><rect height='100%' width='12.903225806451612%' x='83.87096774193547%' /></svg>");background-repeat:no-repeat;">
    I'm a grid container!
</div>

The function svgGrid accepts the same shorthand as the other Susy.js functions and returns the CSS data URL of an SVG illustration visualizing your grid's columns. There are two additional shorthand functions attached to svgGrid:

• svgGrid.colors. Accepts either a single CSS color string (#9CC) for solid-colored columns or an array of same to construct a gradient. Defaults to ['hsla(120, 50%, 50%, 0.5)', 'hsla(120, 50%, 75%, 0.5)'].
• svgGrid.offset. Pass in a CSS length to manually configure the default image offset so as to allow for grid edges.

Pass these in with the other shorthand functions to reconfigure the visual grid.