Skip to main content
Digitaltableteur

Design system components

Spacer

Empty layout element that injects a fixed gap on a single axis. Used inside flex/grid containers where adding a token-sized gap as a sibling reads cleaner than the gap utility.

Status: beta. Group: structure. Markdown version: /design-system/components/spacer.md

When to use

Spacer inserts a fixed, aria-hidden gap where you cannot control the parent's layout; between blocks you don't own, or in markup that isn't a Stack. It is the escape hatch, not the default: prefer gap on Stack/FlexBox/Grid first. axis="horizontal" makes it a width in inline rows.

When not to use

  • Do not stack two Spacers; collapse them into the larger size.
  • Do not use as a 'push' element to right-align content; use flex margin-inline-start: auto instead.
  • Do not use Spacer for page-band rhythm; Section's spacing prop owns that.

Look-alikes

  • Divider: Do not use dividers as spacing; if you only need distance, use gap or Spacer.

Props

Spacer props
PropTypeDefaultDescriptionRequired
size"sm" | "md" | "lg" | "xl" | "xs" | "2xl"mdTokenized gap size.No
axis"horizontal" | "vertical"verticalBlock (vertical) or inline (horizontal) axis.No
classNamestringnoneAdditional CSS class names.No

Variants

  • Available sizes: sm, md, lg, xl, xs, 2xl (default sm).
  • Allowed axis values: horizontal, vertical (default vertical).

Invalid combinations

The contract records no invalid combinations.

Keyboard

The contract records no keyboard interaction.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

Spacer rules
LevelRuleHow it is checked
MUSTARIA: Renders as a non-interactive <div>; assistive tech ignores it.Not yet verified: no evidence record. WCAG 4.1.2.
MUSTRequired stories produce no axe violations at the configured severity.Automated by npm run test:stories:matrix:ci. WCAG 2.5.8.
MUSTThe accessibility tree (role, name, state) matches the committed snapshot for every required story.Automated by npm run test:stories:matrix:ci. WCAG 1.3.1, 4.1.2.
MUSTThe component remains legible and operable under a real browser forced-colors: active pass.Automated by npm run test:stories:hc.
MUSTA human completed an end-to-end accessibility review of this component.Manual review, last on 2026-05-28.
SHOULDReach for parent gap first (Stack/FlexBox/Grid); use Spacer only where you cannot own the parent.Not stated in the contract.
SHOULDUse axis="horizontal" inside flex rows; the default vertical axis is for block flow.Not stated in the contract.
SHOULDPick the one size that matches the rhythm step you need; sizes map to the space scale.Not stated in the contract.
SHOULDKeep it aria-hidden (built in); it must never carry content or semantics.Not stated in the contract.
SHOULD NOTDo not stack multiple Spacers to add up space; use the next size.Not stated in the contract.

Install and import

  • Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
  • Import: import { Spacer } from "@digitaltableteur/react";
  • Entry point: @digitaltableteur/react/layout exports it too.
  • Styles: import @digitaltableteur/react/style.css once at the app boundary.
  • Also available as the custom element <dt-spacer>; see the custom elements manifest.

Links