Styleframe Logo
Utilities

Spacing

Create spacing utilities for margin and padding with directional variants and full type safety.

Overview

Spacing utilities help you control the space around and inside elements using margin and padding. These utilities include comprehensive directional variants for fine-grained control.

Why Use Spacing Utilities?

Spacing utilities help you:

  • Create consistent spacing: Reference design tokens for uniform spacing across your application
  • Control direction: Apply spacing to specific sides using directional variants
  • Support RTL layouts: Use logical properties (start/end) for internationalization
  • Build responsive designs: Combine with modifiers for responsive spacing

useMarginUtility

The useMarginUtility() function creates utility classes for setting margins.

styleframe.config.ts
import { styleframe } from "styleframe";
import { useSpacing } from "@styleframe/theme";
import { useMarginUtility } from "@styleframe/theme";

const s = styleframe();
const { ref } = s;

const { spacing, spacingSm, spacingMd, spacingLg, spacingXl } = useSpacing(s, {
    default: '1rem',
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
    xl: '2rem',
} as const);

useMarginUtility(s, {
    '0': '0',
    sm: ref(spacingSm),
    md: ref(spacingMd),
    lg: ref(spacingLg),
    xl: ref(spacingXl),
    auto: 'auto',
});

export default s;

Directional Margin Variants

UtilityCSS PropertyDescription
useMarginUtilitymarginAll sides
useMarginInlineUtilitymargin-left, margin-rightHorizontal (left & right)
useMarginBlockUtilitymargin-top, margin-bottomVertical (top & bottom)
useMarginTopUtilitymargin-topTop only
useMarginRightUtilitymargin-rightRight only
useMarginBottomUtilitymargin-bottomBottom only
useMarginLeftUtilitymargin-leftLeft only
useMarginInlineStartUtilitymargin-inline-startInline start (RTL-aware)
useMarginInlineEndUtilitymargin-inline-endInline end (RTL-aware)
styleframe.config.ts
import { styleframe } from "styleframe";
import {
    useMarginUtility,
    useMarginInlineUtility,
    useMarginBlockUtility,
    useMarginTopUtility,
    useMarginBottomUtility,
} from "@styleframe/theme";

const s = styleframe();

const spacingValues = {
    '0': '0',
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
    auto: 'auto',
};

useMarginUtility(s, spacingValues);
useMarginInlineUtility(s, spacingValues);
useMarginBlockUtility(s, spacingValues);
useMarginTopUtility(s, spacingValues);
useMarginBottomUtility(s, spacingValues);

export default s;

usePaddingUtility

The usePaddingUtility() function creates utility classes for setting padding.

styleframe.config.ts
import { styleframe } from "styleframe";
import { useSpacing } from "@styleframe/theme";
import { usePaddingUtility } from "@styleframe/theme";

const s = styleframe();
const { ref } = s;

const { spacingSm, spacingMd, spacingLg, spacingXl } = useSpacing(s, {
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
    xl: '2rem',
} as const);

usePaddingUtility(s, {
    '0': '0',
    sm: ref(spacingSm),
    md: ref(spacingMd),
    lg: ref(spacingLg),
    xl: ref(spacingXl),
});

export default s;

Directional Padding Variants

UtilityCSS PropertyDescription
usePaddingUtilitypaddingAll sides
usePaddingInlineUtilitypadding-left, padding-rightHorizontal
usePaddingBlockUtilitypadding-top, padding-bottomVertical
usePaddingTopUtilitypadding-topTop only
usePaddingRightUtilitypadding-rightRight only
usePaddingBottomUtilitypadding-bottomBottom only
usePaddingLeftUtilitypadding-leftLeft only
usePaddingInlineStartUtilitypadding-inline-startInline start
usePaddingInlineEndUtilitypadding-inline-endInline end

useSpaceUtility

The useSpaceUtility() creates spacing between child elements using the "lobotomized owl" selector pattern.

styleframe.config.ts
import { styleframe } from "styleframe";
import { useSpaceXUtility, useSpaceYUtility } from "@styleframe/theme";

const s = styleframe();

useSpaceXUtility(s, {
    '0': '0',
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
});

useSpaceYUtility(s, {
    '0': '0',
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
});

export default s;
Pro tip: For flex and grid layouts, prefer gap utilities over space utilities. Gap doesn't require negative margins and works more predictably.

Examples

Card with Consistent Padding

styleframe.config.ts
import { styleframe } from "styleframe";
import { useSpacing } from "@styleframe/theme";
import { usePaddingUtility, useMarginBottomUtility } from "@styleframe/theme";

const s = styleframe();
const { ref } = s;

const { spacingMd, spacingLg } = useSpacing(s, {
    md: '1rem',
    lg: '1.5rem',
} as const);

usePaddingUtility(s, {
    md: ref(spacingMd),
    lg: ref(spacingLg),
});

useMarginBottomUtility(s, {
    md: ref(spacingMd),
});

export default s;

Usage in HTML:

<div class="card _padding:lg">
    <h2 class="_margin-bottom:md">Card Title</h2>
    <p>Card content goes here.</p>
</div>

Centered Container with Auto Margins

styleframe.config.ts
import { styleframe } from "styleframe";
import { useMarginInlineUtility, usePaddingInlineUtility } from "@styleframe/theme";

const s = styleframe();

useMarginInlineUtility(s, { auto: 'auto' });
usePaddingInlineUtility(s, { md: '1rem', lg: '2rem' });

export default s;

Usage in HTML:

<div class="_margin-inline:auto _padding-inline:md" style="max-width: 1200px;">
    Centered content with horizontal padding
</div>

Best Practices

  • Use design tokens: Reference your spacing scale with ref() for consistent spacing
  • Prefer gap over space utilities: For flex/grid, gap is cleaner and more predictable
  • Use logical properties for RTL: margin-inline-start adapts to text direction
  • Keep spacing scales consistent: Use the same scale for both margin and padding
  • Avoid magic numbers: Use named spacing values instead of arbitrary pixel values

FAQ

Sizing

Create sizing utilities for width, height, min/max dimensions with full type safety.

SVG

Create SVG utilities for fill, stroke, and stroke-width with full type safety.