Utilities Overview

Utility classes are single-purpose CSS classes that apply a specific style. Styleframe's utility composables make it easy to generate these classes programmatically with full type safety and seamless integration with your design tokens.

Why Use Utility Composables?

Styleframe's approach to utilities offers several key advantages:

• Type-Safe Generation: Full TypeScript support with auto-complete for all utility values
• Design Token Integration: Reference your design tokens directly in utility values using ref()
• Modifier Support: Apply state modifiers like hover, focus, and active to any utility
• Consistent Naming: Generated class names follow predictable patterns like _property:value
• Minimal Code: Generate comprehensive utility sets with just a few lines of code
• Customizable: Define exactly the utilities you need without bloat

Quick Start

Here's a minimal example showing how utilities work:

import { styleframe } from 'styleframe';
import { useSpacing } from '@styleframe/theme';
import { useMarginUtility, usePaddingUtility, useDisplayUtility } from '@styleframe/theme';

const s = styleframe();

// Define spacing design tokens
const { spacing, spacingSm, spacingMd, spacingLg } = useSpacing(s, {
    default: '1rem',
    sm: '0.5rem',
    md: '1rem',
    lg: '1.5rem',
} as const);

// Create margin utilities with your spacing values
useMarginUtility(s, {
    sm: s.ref(spacingSm),
    md: s.ref(spacingMd),
    lg: s.ref(spacingLg),
    auto: 'auto',
});

// Create padding utilities
usePaddingUtility(s, {
    sm: s.ref(spacingSm),
    md: s.ref(spacingMd),
    lg: s.ref(spacingLg),
});

// Create display utilities (uses built-in defaults)
useDisplayUtility(s);

export default s;

This generates utility classes like:

._margin\:sm { margin: var(--spacing--sm); }
._margin\:md { margin: var(--spacing--md); }
._margin\:lg { margin: var(--spacing--lg); }
._margin\:auto { margin: auto; }

._padding\:sm { padding: var(--spacing--sm); }
._padding\:md { padding: var(--spacing--md); }
._padding\:lg { padding: var(--spacing--lg); }

._display\:flex { display: flex; }
._display\:block { display: block; }
._display\:grid { display: grid; }
/* ... more display values */

Utility Categories

These composables are organized into categories following common CSS property groupings.

Accessibility

Utilities for accessibility features like screen reader visibility and forced color adjustments.

Available composables:

• useForcedColorAdjustUtility(): Control forced-color-adjust behavior
• useSrOnlyUtility(): Visually hide content while keeping it accessible
• useNotSrOnlyUtility(): Undo screen-reader-only styles

Learn more about Accessibility Utilities →

Backgrounds

Utilities for controlling background properties.

Available composables:

• useBackgroundColorUtility(): Set background colors
• useBackgroundImageUtility(): Set background images
• useBackgroundSizeUtility(): Control background sizing
• useBackgroundPositionUtility(): Set background position
• useBackgroundRepeatUtility(): Control background repeat behavior
• useBackgroundAttachmentUtility(): Set scroll behavior
• useBackgroundClipUtility(): Control background clipping
• useBackgroundOriginUtility(): Set background origin

Learn more about Background Utilities →

Borders

Utilities for borders, outlines, dividers, and focus rings.

Available composables:

• useBorderColorUtility(): Set border colors (with directional variants)
• useBorderWidthUtility(): Control border width
• useBorderRadiusUtility(): Set border radius
• useBorderStyleUtility(): Define border styles
• useDivideUtility(): Add divider lines between children
• useOutlineUtility(): Control outline styles
• useRingUtility(): Create focus rings

Learn more about Border Utilities →

Effects

Utilities for visual effects like shadows, opacity, and blend modes.

Available composables:

• useBoxShadowUtility(): Apply box shadows
• useBoxShadowColorUtility(): Set shadow colors
• useOpacityUtility(): Control element opacity
• useTextShadowUtility(): Add text shadows
• useMixBlendModeUtility(): Set blend modes
• useBackgroundBlendModeUtility(): Control background blending

Learn more about Effect Utilities →

Filters

Utilities for CSS filter effects and backdrop filters.

Available composables:

• useBlurUtility(): Apply blur effects
• useBrightnessUtility(): Adjust brightness
• useContrastUtility(): Control contrast
• useGrayscaleUtility(): Apply grayscale
• useHueRotateUtility(): Rotate hue
• useInvertUtility(): Invert colors
• useSaturateUtility(): Adjust saturation
• useSepiaUtility(): Apply sepia tone
• useDropShadowUtility(): Add drop shadows
• useBackdropBlurUtility(): Blur backdrop (+ other backdrop filters)

Learn more about Filter Utilities →

Flexbox & Grid

Utilities for flexbox and grid layout systems.

Available composables:

• useFlexUtility(): Flex shorthand values
• useFlexDirectionUtility(): Set flex direction
• useFlexWrapUtility(): Control flex wrapping
• useFlexGrowUtility(), useFlexShrinkUtility(): Control flex growth/shrink
• useGridTemplateColumnsUtility(), useGridTemplateRowsUtility(): Define grid templates
• useGapUtility(): Set gaps between items
• useAlignUtility(), useJustifyUtility(), usePlaceUtility(): Alignment utilities
• useOrderUtility(): Control item order

Learn more about Flexbox & Grid Utilities →

Interactivity

Utilities for user interaction properties.

Available composables:

• useCursorUtility(): Set cursor styles
• usePointerEventsUtility(): Control pointer events
• useUserSelectUtility(): Manage text selection
• useScrollBehaviorUtility(): Set scroll behavior
• useTouchActionUtility(): Control touch interactions
• useResizeUtility(): Enable element resizing
• useAccentColorUtility(), useCaretColorUtility(): Form element colors

Learn more about Interactivity Utilities →

Layout

Utilities for element layout and positioning.

Available composables:

• useDisplayUtility(): Set display types
• usePositionUtility(): Set positioning mode
• useInsetUtility(): Control inset values (+ directional variants)
• useZIndexUtility(): Set stacking order
• useOverflowUtility(): Control overflow behavior
• useVisibilityUtility(): Toggle visibility
• useAspectRatioUtility(): Set aspect ratios
• useColumnsUtility(): Multi-column layouts

Learn more about Layout Utilities →

Sizing

Utilities for width and height properties.

Available composables:

• useWidthUtility(), useMinWidthUtility(), useMaxWidthUtility(): Width control
• useHeightUtility(), useMinHeightUtility(), useMaxHeightUtility(): Height control
• useSizeUtility(): Set both dimensions at once

Learn more about Sizing Utilities →

Spacing

Utilities for margin and padding.

Available composables:

• useMarginUtility(): Set margins (+ directional variants)
• usePaddingUtility(): Set padding (+ directional variants)
• useSpaceUtility(): Space between children

Learn more about Spacing Utilities →

SVG

Utilities for SVG-specific properties.

Available composables:

• useFillUtility(): Set SVG fill color
• useStrokeUtility(): Set SVG stroke color
• useStrokeWidthUtility(): Control stroke width

Learn more about SVG Utilities →

Tables

Utilities for table layout properties.

Available composables:

• useBorderCollapseUtility(): Control border collapsing
• useBorderSpacingUtility(): Set border spacing
• useTableLayoutUtility(): Set table layout algorithm
• useCaptionSideUtility(): Position table captions

Learn more about Table Utilities →

Transforms

Utilities for CSS transforms.

Available composables:

• useRotateUtility(): Rotate elements
• useScaleUtility(): Scale elements
• useTranslateUtility(): Translate position
• useSkewXUtility(), useSkewYUtility(): Skew elements
• useTransformOriginUtility(): Set transform origin
• usePerspectiveUtility(): Set 3D perspective

Learn more about Transform Utilities →

Transitions & Animation

Utilities for transitions and animations.

Available composables:

• useTransitionPropertyUtility(): Set which properties transition
• useTransitionDurationUtility(): Set transition duration
• useTransitionTimingFunctionUtility(): Set easing functions
• useTransitionDelayUtility(): Set transition delays
• useAnimationUtility(): Apply CSS animations

Learn more about Transition & Animation Utilities →

Typography

Utilities for text and font styling.

Available composables:

• useFontFamilyUtility(), useFontSizeUtility(), useFontWeightUtility(): Font properties
• useTextColorUtility(): Set text color
• useTextAlignUtility(): Control text alignment
• useLineHeightUtility(), useLetterSpacingUtility(): Text spacing
• useTextDecorationUtility(): Add text decorations
• useTextTransformUtility(): Transform text case
• useLineClampUtility(): Truncate text with ellipsis

Learn more about Typography Utilities →

Utility Reference

Best Practices

• Use design tokens: Reference your design token variables using ref() for consistent styling
• Start small: Only generate the utilities you actually need to keep CSS bundle size minimal
• Leverage defaults: Many utilities have sensible default values you can use directly
• Apply modifiers: Use modifier composables like hover to generate state variants
• Use as const: Add as const to value objects for better TypeScript inference
• Follow naming conventions: Use semantic names that describe purpose, not appearance

Next Steps

Ready to start using utilities? Begin with these common categories:

• Building layouts? Start with Layout and Flexbox & Grid
• Styling text? Check out Typography
• Adding spacing? Explore Spacing and Sizing
• Creating effects? Look at Effects and Filters

Each utility composable is designed to work seamlessly with Styleframe's design tokens and theming system.