Spacer
Declarative whitespace block bound to `--space-*` tokens. Use when sibling spacing can't come from a parent's `gap`.
Vertical between sections
Horizontal — push siblings apart in a flex row
Size scale
xssmmdlgxlInstallation
pnpm dlx @hex-core/cli add spacerHorizontal flex spacer
Push siblings to opposite ends of a flex row.
<div className="flex items-center">
<Logo />
<Spacer axis="horizontal" size="lg" />
<Nav />
</div>Hero spacing inside a flex column
Inside a tall flex column, an xl Spacer pushes the CTA away from the heading without forcing the parent to manage gap. Common for marketing hero blocks.
<section className="flex min-h-[480px] flex-col items-center text-center">
<h1 className="text-4xl font-semibold tracking-tight">Ship faster.</h1>
<p className="max-w-md text-muted-foreground">
A registry-driven component library that already speaks your design tokens.
</p>
<Spacer size="xl" />
<Button size="lg">Start building</Button>
</section>Variant values
sizeSpacer extent bound to `--space-*` tokens.xssmmdlgxl| Value | Description |
|---|---|
xs | 0.25rem — micro-gap. |
sm | 0.5rem — tight separation. |
mddefault | 1rem — default; standard breathing room. |
lg | 2rem — section-scale separation. |
xl | 4rem — major separation between hero areas. |
axisWhich axis the spacer extends along.verticalhorizontalboth| Value | Description |
|---|---|
verticaldefault | Default — fixed height, 1px width. |
horizontal | Fixed width, 1px height — for flex rows. |
both | Square block — rare; usually pick one axis. |
API Reference
| Prop | Type | Default | Description |
|---|---|---|---|
size | "xs" | "sm" | "md" | "lg" | "xl" | md | Spacing token (xs=0.25rem, sm=0.5rem, md=1rem, lg=2rem, xl=4rem). Bound to `--space-*`. |
axis | "vertical" | "horizontal" | "both" | vertical | Which axis to expand. Vertical = height; horizontal = width; both = square. |
AI Guidance
When to use
Use as an explicit whitespace primitive when you can't (or don't want to) use `gap` on the parent — typically: pushing siblings apart inside a flex row that already has gap-0, or inserting one-off vertical breathing room between top-level sections that aren't wrapped in a Stack.
When not to use
Don't use Spacer when a `Stack` or `Cluster` parent's `gap` would do the same thing — that scales better and keeps the spacing concern with the layout primitive. Don't use Spacer to flush content to one edge of a flex container — use `ml-auto` / `justify-between` directly.
Common mistakes
- Using `<Spacer />` between every child in a Stack — just set the Stack's `gap` instead
- Using `axis="both"` and getting a square block where you wanted a line — `both` is rare, usually you want vertical or horizontal
- Setting size="lg" on a horizontal spacer and getting nothing visible because the parent isn't a flex row — Spacer reserves space, it doesn't push siblings on its own
Accessibility
Spacer is `aria-hidden="true"` — screen readers skip it. Don't use a Spacer where a `Separator` would convey meaning (a thematic break should be `Separator`, not `Spacer`).
Token budget: 200
Verified against @hex-core/components@1.12.0