Grid

npm install @vrembem/grid

@use "@vrembem/grid";

Options

Grid is built as a Sass module. Sass options are used to control CSS output, while design token CSS variables control the styling of the component. Below are the available configuration options.

Sass

Grid comes with the following Sass configuration options that can be set using either the config module or Sass with clause methods.

@use "@vrembem/grid" with (
  $config: (
    // Map for outputting grid--cols-[num] modifier and col-[num] utility variants
    // @type map
    "grid-cols": (
      "breakpoints": true,
      "default": 1,
      "total": 6
    ),

    // Map for outputting grid--rows-[num] modifier and row-[num] utility variants
    // @type map
    "grid-rows": (
      "breakpoints": true,
      "default": 1,
      "total": 6
    ),

    // Map for outputting the grid--gap-[key] modifier variants
    // @type map
    "grid-gap": (
      "breakpoints": true,
      "default": calc(tokens.get("spacing") * 8),
      "0": 0,
      "xs": calc(tokens.get("spacing") * 2),
      "sm": calc(tokens.get("spacing") * 4),
      "md": calc(tokens.get("spacing") * 8),
      "lg": calc(tokens.get("spacing") * 12),
      "xl": calc(tokens.get("spacing") * 16)
    ),

    // Map for outputting the grid--flow-[key] modifier variants
    // @type map
    "grid-flow": (
      "default": dense,
      "row": row,
      "col": column,
      "row-dense": row dense,
      "col-dense": column dense
    )
  )
);

Design tokens

Grid uses design token CSS variables in a reference and fallback pattern. Variables are referenced in the component's styles but are not directly defined; instead, they are provided with sensible fallbacks.

--vb-grid-gap

2em

--vb-grid-gap-x

var(--vb-grid-gap)

--vb-grid-gap-y

var(--vb-grid-gap)

--vb-grid-flow

dense

--vb-grid-cols

1

--vb-grid-rows

1

Basic usage

The most basic implementation of the grid layout consists of the grid container and it's children (grid items). Apply the grid class to the desired grid container with an optional grid--cols-[num] modifier to create a grid layout.

<div class="grid grid--cols-3">
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

grid--inline

Also available is the grid--inline modifier. This sets the display property to inline-grid instead of grid.

<div class="grid grid--inline grid--cols-3">
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

grid--cols-[num]

By default the grid class only defines a single column. To add additional columns to the grid layout, use the grid--cols-[num] modifiers. The number of variants available is controlled by the grid-cols config option (default: 6).

<div class="grid grid--cols-3">
  ...
</div>

Available variants

• grid--cols-1
• grid--cols-2
• grid--cols-3
• grid--cols-4
• grid--cols-5
• grid--cols-6

Breakpoint variants

These modifiers come with media breakpoint variants. This allows changing styles based on a specific breakpoint key in the breakpoints config options map.

<div class="grid lg:grid--cols-3">
  ...
</div>

Available variants

• xs:grid--cols-[num]
• sm:grid--cols-[num]
• md:grid--cols-[num]
• lg:grid--cols-[num]
• xl:grid--cols-[num]

grid--rows-[num]

By default the grid class only defines a single row. To add additional rows to the grid layout, use the grid--rows-[num] modifiers. The number of variants available is controlled by the grid-rows config option (default: 6).

<div class="grid grid--cols-2 grid--rows-2">
  <div class="row-full">...</div>
  <div>...</div>
</div>

Available variants

• grid--rows-1
• grid--rows-2
• grid--rows-3
• grid--rows-4
• grid--rows-5
• grid--rows-6

Breakpoint variants

These modifiers come with media breakpoint variants. This allows changing styles based on a specific breakpoint key in the breakpoints config options map.

<div class="grid grid--cols-2 lg:grid--rows-2">
  <div class="row-full">...</div>
  <div>...</div>
</div>

Available variants

• xs:grid--rows-[num]
• sm:grid--rows-[num]
• md:grid--rows-[num]
• lg:grid--rows-[num]
• xl:grid--rows-[num]

grid--gap-[key]

Modifiers used to set the gap property of a grid component. These modifiers are generated using key/value pairs of the grid-gap config options map. The default key sets the provided value on the flex component itself and is not output as a modifier.

<div class="grid grid--cols-2 grid--gap-xs">
  ...
</div>

Available variants

• grid--gap-0
• grid--gap-xs
• grid--gap-sm
• grid--gap-md
• grid--gap-lg
• grid--gap-xl

grid--gap-x-[key]

Modifiers to set the column-gap value on a grid component. These modifiers are generated using key/value pairs of the grid-gap config options map.

<div class="grid grid--cols-2 grid--gap-x-xs">
  ...
</div>

Available variants

• grid--gap-x-0
• grid--gap-x-xs
• grid--gap-x-sm
• grid--gap-x-md
• grid--gap-x-lg
• grid--gap-x-xl

grid--gap-y-[key]

Modifiers to set the row-gap value on a grid component. These modifiers are generated using key/value pairs of the grid-gap config options map.

<div class="grid grid--cols-2 grid--gap-y-xs">
  ...
</div>

Available variants

• grid--gap-y-0
• grid--gap-y-xs
• grid--gap-y-sm
• grid--gap-y-md
• grid--gap-y-lg
• grid--gap-y-xl

Breakpoint variants

These modifiers come with media breakpoint variants. This allows changing styles based on a specific breakpoint key in the breakpoints config options map.

Available variants

grid--flow-[key]

Modifiers used to set the grid-auto-flow property of a grid component. By default, the grid component has auto-flow set to dense. These modifiers are generated using key/value pairs of the grid-flow config options map. The default key sets the provided value on the grid component itself and is not output as a modifier.

<div class="grid grid--cols-3 grid--rows-3 grid--flow-row">
  ...
</div>

Available variants

• grid--flow-row
• grid--flow-col
• grid--flow-row-dense
• grid--flow-col-dense

Utilities

Grid utilities are intended to be used directly on the children of a grid component or grid container (elements with display: grid or display: inline-grid). Since these only change a single CSS property, utility classes are used instead of BEM element classes.

grid-col-[num]

A utility used to control the grid-column property which handles a grid item's size and location within a grid column. The number of variants available is controlled by the grid-cols config option (Default: 6).

<div class="grid grid--cols-6">
  <div class="grid-col-3">...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

Available variants

Breakpoint variants

This utility also come with media breakpoint variants. This allows changing styles based on a specific breakpoint key in the breakpoints config options map.

<div class="grid grid--cols-6">
  <div class="grid-col-6 md:grid-col-3 lg:grid-col-2">...</div>
  <div class="grid-col-6 md:grid-col-3 lg:grid-col-2">...</div>
  <div class="grid-col-3 md:grid-col-6 lg:grid-col-2">...</div>
  <div class="grid-col-3 md:grid-col-3 lg:grid-col-3">...</div>
  <div class="grid-col-6 md:grid-col-3 lg:grid-col-3">...</div>
</div>

Available variants

• xs:grid-col-[num]
• sm:grid-col-[num]
• md:grid-col-[num]
• lg:grid-col-[num]
• xl:grid-col-[num]

grid-row-[num]

A utility used to control the grid-row property which handles a grid item's size and location within a grid row. The number of variants available is controlled by the grid-rows config option (Default: 6).

<div class="grid grid--cols-6 grid--rows-6">
  <div class="grid-row-2">...</div>
  <div>...</div>
  <div>...</div>
  <div>...</div>
</div>

Available variants

Breakpoint variants

This utility also come with media breakpoint variants. This allows changing styles based on a specific breakpoint key in the breakpoints config options map.

<div class="grid grid--cols-3 grid--rows-3 grid--flow-col-dense">
  <div class="md:grid-row-2 lg:grid-row-3">1</div>
  <div class="md:grid-row-2 lg:grid-row-3">2</div>
  <div class="md:grid-row-1">3</div>
  <div class="md:grid-row-1">4</div>
  <div class="md:grid-row-3 lg:grid-row-1">5</div>
</div>

Available variants

• xs:grid-row-[num]
• sm:grid-row-[num]
• md:grid-row-[num]
• lg:grid-row-[num]
• xl:grid-row-[num]