# Spacer

> Explicit whitespace as a component. Step 0–8 maps onto the token scale, any other number is treated as raw pixels.

- Category: primitive
- Status: stable (since 0.1.0)
- Tokens: --space-0, --space-1, --space-2, --space-3, --space-4, --space-5, --space-6, --space-7, --space-8
- Playground: https://design.freecodecamp.org/playground#spacer
- npm dependencies: `react@>=18 <20`
- Registry dependencies: [theme](https://design.freecodecamp.org/registry/theme.md)
- Files:
  - `Spacer.tsx` → `src/ui/spacer/Spacer.tsx` (raw: https://design.freecodecamp.org/registry/spacer/Spacer.tsx)
  - `spacer.css` → `src/ui/spacer/spacer.css` (raw: https://design.freecodecamp.org/registry/spacer/spacer.css)

## Install (copy source)

1. Ensure the theme is installed once per project - tokens.css + base.css imported globally, fonts available. See https://design.freecodecamp.org/registry/theme.md and https://design.freecodecamp.org/registry/starter.md.
2. Copy the files below into `src/ui/spacer/` (adjust to your project layout) and import the CSS once from your global stylesheet, e.g. `@import './ui/spacer/spacer.css';`.
3. Colors, spacing and type come from tokens - tailor the component by editing the copied source; recolour by editing tokens.css, not the component CSS.

## Usage

`<Spacer>` is explicit layout gap. Reach for it when the surrounding
components should not carry margin of their own - typical in MDX
content where paragraphs and code blocks already own their spacing.

## Accessibility

Renders a presentation-only `<span>` with `aria-hidden="true"`. Screen
readers skip it entirely. Don't rely on it for semantic separation -
use a heading or landmark for that.

## Example

```tsx
import { Spacer } from './ui/spacer/Spacer';

<div style={{ display: 'flex' }}>
  <span>start</span>
  <Spacer size={6} />
  <span>end</span>
</div>
```

## Props

| Prop | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `size` | `number` | no | `4` | Step 0–8 maps onto the token scale (0, 4, 8, 12, 16, 24, 32, 48, 64 px). Any other number is treated as a raw pixel value. |
| `axis` | `enum` | no | `horizontal` |  |

## Source: Spacer.tsx

```tsx
import React, { forwardRef } from 'react';

const STEPS: readonly number[] = [0, 4, 8, 12, 16, 24, 32, 48, 64];

export type SpacerStep = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;

export interface SpacerProps extends React.HTMLAttributes<HTMLSpanElement> {
  /**
   * Step 0–8 maps onto the token scale (0, 4, 8, 12, 16, 24, 32, 48, 64 px).
   * Any other number is treated as a raw pixel value.
   */
  size?: SpacerStep | number;
  axis?: 'horizontal' | 'vertical';
}

export const Spacer = forwardRef<HTMLSpanElement, SpacerProps>(
  ({ size = 4, axis = 'horizontal', className = '', style, ...rest }, ref) => {
    const px =
      Number.isInteger(size) && size >= 0 && size <= 8 ? STEPS[size] : size;
    const dim =
      axis === 'horizontal'
        ? { width: px, height: 1 }
        : { width: 1, height: px };
    const classes = ['spacer', className].filter(Boolean).join(' ');
    return (
      <span
        ref={ref}
        aria-hidden='true'
        className={classes}
        style={{ ...dim, ...style }}
        {...rest}
      />
    );
  }
);
Spacer.displayName = 'Spacer';
```

## Source: spacer.css

```css
.spacer {
  display: block;
}
```

## HTML / vanilla variant

```html
<span class="spacer" style="width:48px"></span>
```

Interactive behaviours for plain HTML come from the vanilla runtime (data-uikit-* attributes): https://design.freecodecamp.org/registry/vanilla.md - or download https://design.freecodecamp.org/cdn/uikit.global.js once and self-host it (do not hotlink).

## For coding agents

This library is distributed as copyable source, not an npm package. Start at https://design.freecodecamp.org/registry/starter.md, discover components via https://design.freecodecamp.org/llms.txt, and copy files into the consuming project. Keep token names intact; recolour by editing the copied tokens.css.