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
  • Use multiplier values: Generate spacing based on a base variable multiplied by any factor

Multiplier Values

Spacing utilities support multiplier values that automatically generate calc() expressions based on your base --spacing variable. This allows you to use arbitrary spacing multipliers without defining every possible value upfront.

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

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

// Define the base spacing variable
const { spacing, spacingSm, spacingMd } = useSpacing(s, {
    default: '1rem',
    sm: '0.5rem',
    md: '1rem',
} as const);

// Create margin utility with named values
const createMargin = useMarginUtility(s, {
    sm: ref(spacingSm),
    md: ref(spacingMd),
});

// Add multiplier values using array syntax (with @ prefix)
createMargin(["@1.5", "@2", "@0.5", "@-1"]);

export default s;

Supported Multiplier Formats

Use the @ prefix followed by a numeric value:

FormatExampleDescription
Integers@1, @2, @3Whole number multipliers
Decimals@0.5, @1.5, @2.25Fractional multipliers
Negative@-1, @-0.5Negative spacing (useful for pulling elements)
Multiplier values work with all spacing utilities including useMarginUtility, usePaddingUtility, useSpaceUtility, and useGapUtility. The base variable defaults to --spacing with a fallback of 1rem if not defined. Both the base variable and fallback can be customized.

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
useMarginXUtilitymargin-left, margin-rightHorizontal (left & right)
useMarginYUtilitymargin-top, margin-bottomVertical (top & bottom)
useMarginInlineUtilitymargin-left, margin-rightHorizontal (left & right, logical)
useMarginBlockUtilitymargin-top, margin-bottomVertical (top & bottom, logical)
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
usePaddingXUtilitypadding-left, padding-rightHorizontal (left & right)
usePaddingYUtilitypadding-top, padding-bottomVertical (top & bottom)
usePaddingInlineUtilitypadding-left, padding-rightHorizontal (left & right, logical)
usePaddingBlockUtilitypadding-top, padding-bottomVertical (top & bottom, logical)
usePaddingTopUtilitypadding-topTop only
usePaddingRightUtilitypadding-rightRight only
usePaddingBottomUtilitypadding-bottomBottom only
usePaddingLeftUtilitypadding-leftLeft only
usePaddingInlineStartUtilitypadding-inline-startInline start (RTL-aware)
usePaddingInlineEndUtilitypadding-inline-endInline end (RTL-aware)

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.