Styleframe Logo
Utilities

Backgrounds

Create background utilities for colors, images, sizing, positioning, and more with full type safety.

Overview

Background utilities help you control the background styling of elements including colors, images, sizing, positioning, repeat behavior, and more.

Why Use Background Utilities?

Background utilities help you:

  • Integrate with design tokens: Reference your color system directly using ref()
  • Handle responsive images: Control how background images scale and position
  • Create consistent patterns: Generate reusable background styles across your application
  • Support theming: Background colors can automatically adapt to theme changes

useBackgroundColorUtility

The useBackgroundColorUtility() function creates utility classes for setting background colors.

styleframe.config.ts
import { styleframe } from "styleframe";
import { useColor } from "@styleframe/theme";
import { useBackgroundColorUtility } from "@styleframe/theme";

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

// Define colors
const { colorPrimary, colorSecondary } = useColor(s, {
    primary: '#006cff',
    secondary: '#6c757d',
} as const);

// Create background color utilities
useBackgroundColorUtility(s, {
    inherit: 'inherit',
    current: 'currentColor',
    transparent: 'transparent',
    primary: ref(colorPrimary),
    secondary: ref(colorSecondary),
    white: '#fff',
    black: '#000',
});

export default s;
Pro tip: Use ref() to reference your color design tokens so background colors automatically update with theme changes.

useBackgroundImageUtility

The useBackgroundImageUtility() function creates utility classes for setting background images.

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

const s = styleframe();

useBackgroundImageUtility(s, {
    none: 'none',
    'gradient-primary': 'linear-gradient(to right, #006cff, #00b4d8)',
    'gradient-dark': 'linear-gradient(to bottom, #1a1a1a, #2d2d2d)',
});

export default s;

useBackgroundSizeUtility

The useBackgroundSizeUtility() function creates utility classes for controlling background image sizing.

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

const s = styleframe();

// Uses built-in defaults: auto, cover, contain
useBackgroundSizeUtility(s);

export default s;

Default Values

KeyValueDescription
autoautoDefault size, image displays at original dimensions
covercoverScale to cover entire element, may crop
containcontainScale to fit within element, may leave gaps

useBackgroundPositionUtility

The useBackgroundPositionUtility() function creates utility classes for positioning background images.

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

const s = styleframe();

// Uses built-in defaults for all position combinations
useBackgroundPositionUtility(s);

export default s;

Default Values

KeyValueDescription
bottombottomAlign to bottom center
centercenterCenter horizontally and vertically
leftleftAlign to left center
left-bottomleft bottomAlign to bottom left corner
left-topleft topAlign to top left corner
rightrightAlign to right center
right-bottomright bottomAlign to bottom right corner
right-topright topAlign to top right corner
toptopAlign to top center

useBackgroundRepeatUtility

The useBackgroundRepeatUtility() function creates utility classes for controlling how background images repeat.

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

const s = styleframe();

useBackgroundRepeatUtility(s, {
    repeat: 'repeat',
    'no-repeat': 'no-repeat',
    'repeat-x': 'repeat-x',
    'repeat-y': 'repeat-y',
    round: 'round',
    space: 'space',
});

export default s;

useBackgroundAttachmentUtility

The useBackgroundAttachmentUtility() function creates utility classes for controlling how background images scroll.

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

const s = styleframe();

// Uses built-in defaults: fixed, local, scroll
useBackgroundAttachmentUtility(s);

export default s;

Default Values

KeyValueDescription
fixedfixedBackground stays fixed relative to viewport
locallocalBackground scrolls with element's content
scrollscrollBackground scrolls with the element

useBackgroundClipUtility

The useBackgroundClipUtility() function creates utility classes for controlling how far the background extends.

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

const s = styleframe();

useBackgroundClipUtility(s, {
    border: 'border-box',
    padding: 'padding-box',
    content: 'content-box',
    text: 'text',
});

export default s;
Gradient text: Use background-clip: text with a gradient background and transparent text color to create gradient text effects.

useBackgroundOriginUtility

The useBackgroundOriginUtility() function creates utility classes for setting the background's origin point.

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

const s = styleframe();

useBackgroundOriginUtility(s, {
    border: 'border-box',
    padding: 'padding-box',
    content: 'content-box',
});

export default s;

Examples

Hero Section with Background Image

styleframe.config.ts
import { styleframe } from "styleframe";
import {
    useBackgroundColorUtility,
    useBackgroundImageUtility,
    useBackgroundSizeUtility,
    useBackgroundPositionUtility,
    useBackgroundRepeatUtility,
} from "@styleframe/theme";

const s = styleframe();

// Background utilities for hero sections
useBackgroundColorUtility(s, {
    overlay: 'rgba(0, 0, 0, 0.5)',
});

useBackgroundImageUtility(s, {
    hero: 'url("/images/hero.jpg")',
    none: 'none',
});

useBackgroundSizeUtility(s);
useBackgroundPositionUtility(s);
useBackgroundRepeatUtility(s, { 'no-repeat': 'no-repeat' });

export default s;

Usage in HTML:

<section class="_background-image:hero _background-size:cover _background-position:center _background-repeat:no-repeat">
    <div class="_bg:overlay">
        <h1>Welcome</h1>
    </div>
</section>

Gradient Text Effect

styleframe.config.ts
import { styleframe } from "styleframe";
import { useBackgroundImageUtility, useBackgroundClipUtility } from "@styleframe/theme";

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

useBackgroundImageUtility(s, {
    'gradient-rainbow': 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #8b00ff)',
});

useBackgroundClipUtility(s, {
    text: 'text',
});

// Create a reusable gradient text class
selector('.gradient-text', {
    backgroundImage: 'linear-gradient(90deg, #ff0000, #ff7f00, #ffff00, #00ff00, #0000ff, #8b00ff)',
    backgroundClip: 'text',
    WebkitBackgroundClip: 'text',
    color: 'transparent',
});

export default s;

Best Practices

  • Use design tokens for colors: Reference your color system with ref() for consistent backgrounds
  • Optimize background images: Use appropriate image formats and sizes for performance
  • Consider accessibility: Ensure sufficient contrast between backgrounds and foreground content
  • Use cover for hero images: background-size: cover is usually best for full-width hero sections
  • Test fixed attachments on mobile: background-attachment: fixed can cause issues on some mobile browsers
  • Prefer CSS gradients: Use CSS gradients instead of image files when possible for better performance

FAQ

Accessibility

Create accessibility utilities for screen reader visibility and forced color adjustments with full type safety.

Borders

Create border utilities for colors, widths, radiuses, styles, outlines, and focus rings with full type safety.