Modifiers Overview

Modifiers are composable functions that wrap utility declarations in conditional selectors, generating state-based, responsive, and structural variants of your utility classes. Pass modifiers as the second parameter to any utility creator to generate conditional utility classes automatically.

Why Use Modifier Composables?

Styleframe's approach to modifiers offers several key advantages:

• Type-Safe Generation: Full TypeScript support with auto-complete for all modifier composables
• Composable Architecture: Each modifier is a standalone function that can be combined with any utility
• Consistent Naming: Generated class names follow predictable patterns like _modifier:property:value
• Minimal Code: Register entire modifier categories with a single composable call
• Customizable: Register only the modifiers you need without bloat

Quick Start

When using the Styleframe Vite plugin, the scanner automatically detects modifier-prefixed utility class names in your source files and generates the corresponding CSS. Just register your utility factories and modifiers, then use the classes directly in your templates:

import { styleframe } from 'styleframe';
import { useUtilitiesPreset, useModifiersPreset } from '@styleframe/theme';

const s = styleframe();

// Register all utility factories and modifiers
useUtilitiesPreset(s);
useModifiersPreset(s);

export default s;

<button class="_background-color:blue _hover:background-color:darkblue _focus:outline-color:blue">
    Click me
</button>

The scanner picks up class names like _hover:background-color:darkblue from your source files and auto-generates the CSS — no need to manually pass modifiers to every utility creator.

Pre-generating Modifier Variants

If you want to pre-generate specific modifier variants tied to your design tokens, you can optionally do so:

import { styleframe } from 'styleframe';
import { useColor } from '@styleframe/theme';
import { useBackgroundColorUtility } from '@styleframe/theme';
import { useHoverModifier, useFocusModifier } from '@styleframe/theme';

const s = styleframe();

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

// Register modifiers
const hover = useHoverModifier(s);
const focus = useFocusModifier(s);

// Create utilities with modifier variants
useBackgroundColorUtility(s, {
    primary: s.ref(colorPrimary),
    secondary: s.ref(colorSecondary),
}, [hover, focus]);

export default s;

This generates classes like _background-color:primary, _hover:background-color:primary, and _focus:background-color:primary.

Each modifier category also provides a group registration function that registers all modifiers in the category at once:

import { usePseudoStateModifiers } from '@styleframe/theme';

const { hover, focus, focusVisible, active } = usePseudoStateModifiers(s);

Presets

The useModifiersPreset() function registers all modifier categories in a single call:

import { styleframe } from 'styleframe';
import { useModifiersPreset } from '@styleframe/theme';

const s = styleframe();

// Register all modifiers at once
const { hover, focus, dark, disabled, first, last } = useModifiersPreset(s);

export default s;

The preset returns a flat object containing all registered modifier instances from every category.

Learn more about Modifier Presets →

Modifiers

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

Pseudo-State

Modifiers for interactive pseudo-class states like hover, focus, and active.

Available composables:

• useHoverModifier(): Apply styles on :hover
• useFocusModifier(): Apply styles on :focus
• useFocusWithinModifier(): Apply styles on :focus-within
• useFocusVisibleModifier(): Apply styles on :focus-visible
• useActiveModifier(): Apply styles on :active
• useVisitedModifier(): Apply styles on :visited
• useTargetModifier(): Apply styles on :target

Learn more about Pseudo-State Modifiers →

Form State

Modifiers for form element pseudo-class states like disabled, checked, and valid.

Available composables:

• useDisabledModifier(): Apply styles on :disabled
• useEnabledModifier(): Apply styles on :enabled
• useCheckedModifier(): Apply styles on :checked
• useIndeterminateModifier(): Apply styles on :indeterminate
• useRequiredModifier(): Apply styles on :required
• useOptionalModifier(): Apply styles on :optional
• useValidModifier(): Apply styles on :valid
• useInvalidModifier(): Apply styles on :invalid
• usePlaceholderShownModifier(): Apply styles on :placeholder-shown
• useAutofillModifier(): Apply styles on :autofill
• useReadOnlyModifier(): Apply styles on :read-only

Learn more about Form State Modifiers →

Pseudo-Elements

Modifiers for targeting element sub-parts like ::before, ::after, and ::placeholder.

Available composables:

• useBeforeModifier(): Apply styles to ::before (auto-injects content: '')
• useAfterModifier(): Apply styles to ::after (auto-injects content: '')
• usePlaceholderModifier(): Apply styles to ::placeholder
• useSelectionModifier(): Apply styles to ::selection
• useFirstLetterModifier(): Apply styles to ::first-letter
• useFirstLineModifier(): Apply styles to ::first-line
• useMarkerModifier(): Apply styles to ::marker
• useBackdropModifier(): Apply styles to ::backdrop
• useFileModifier(): Apply styles to ::file-selector-button

Learn more about Pseudo-Element Modifiers →

ARIA State

Modifiers for targeting elements by their ARIA attribute values.

Available composables:

• useAriaBusyModifier(): Apply styles when aria-busy="true"
• useAriaCheckedModifier(): Apply styles when aria-checked="true"
• useAriaDisabledModifier(): Apply styles when aria-disabled="true"
• useAriaExpandedModifier(): Apply styles when aria-expanded="true"
• useAriaHiddenModifier(): Apply styles when aria-hidden="true"
• useAriaPressedModifier(): Apply styles when aria-pressed="true"
• useAriaReadonlyModifier(): Apply styles when aria-readonly="true"
• useAriaRequiredModifier(): Apply styles when aria-required="true"
• useAriaSelectedModifier(): Apply styles when aria-selected="true"

Learn more about ARIA State Modifiers →

Structural

Modifiers for targeting elements by their position in the DOM tree.

Available composables:

• useFirstModifier(): Apply styles to :first-child
• useLastModifier(): Apply styles to :last-child
• useOnlyModifier(): Apply styles to :only-child
• useOddModifier(): Apply styles to :nth-child(odd)
• useEvenModifier(): Apply styles to :nth-child(even)
• useFirstOfTypeModifier(): Apply styles to :first-of-type
• useLastOfTypeModifier(): Apply styles to :last-of-type
• useOnlyOfTypeModifier(): Apply styles to :only-of-type
• useEmptyModifier(): Apply styles to :empty

Learn more about Structural Modifiers →

Media & Preferences

Modifiers for targeting user preferences and media conditions like dark mode and reduced motion.

Available composables:

• useDarkModifier(): Apply styles in prefers-color-scheme: dark
• useMotionSafeModifier(): Apply styles when motion is not reduced
• useMotionReduceModifier(): Apply styles in prefers-reduced-motion: reduce
• useContrastMoreModifier(): Apply styles in prefers-contrast: more
• useContrastLessModifier(): Apply styles in prefers-contrast: less
• usePortraitModifier(): Apply styles in portrait orientation
• useLandscapeModifier(): Apply styles in landscape orientation
• usePrintModifier(): Apply styles for print media
• useForcedColorsModifier(): Apply styles in forced-colors mode

Learn more about Media & Preference Modifiers →

Directional

Modifiers for targeting elements based on text direction (RTL/LTR).

Available composables:

• useRtlModifier(): Apply styles in right-to-left contexts
• useLtrModifier(): Apply styles in left-to-right contexts

Learn more about Directional Modifiers →

Other State

Modifiers for targeting miscellaneous element states.

Available composables:

• useOpenModifier(): Apply styles to open <details> or popover elements
• useInertModifier(): Apply styles to inert elements and their descendants

Learn more about Other State Modifiers →

Modifier Reference

Best Practices

• Use group composables: Register entire categories at once with functions like usePseudoStateModifiers(s) for convenience
• Be selective: Only register the modifiers you actually use to keep your configuration clean
• Combine with utilities: Pass modifiers as the second argument to utility creator functions
• Use the preset: For comprehensive coverage, use useModifiersPreset(s) to register all categories at once
• Use as const: Add as const to value objects for better TypeScript inference

Next Steps

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

• Adding interactivity? Start with Pseudo-State for hover, focus, and active states
• Building forms? Check out Form State for disabled, checked, and validation states
• Supporting dark mode? Explore Media & Preferences for color scheme and motion preferences
• Styling sub-elements? Look at Pseudo-Elements for before, after, and placeholder
• Building lists? Explore Structural for first, last, odd, and even

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