Variants System

Comprehensive variant system providing responsive breakpoints, pseudo-classes, dark mode support, and CSS combinators for conditional styling.

Capabilities

Variants Function

Creates variant configurations based on preset options, combining multiple variant categories.

function variants(options: PresetWindOptions): Variant<Theme>[];

type Variant = (matcher: VariantMatcherContext) => VariantHandlerContext | string | undefined;

interface VariantMatcherContext {
  matcher: string;
  generator: UnoGenerator;
}

interface VariantHandlerContext {
  matcher: string;
  handle?: VariantHandler;
  multiPass?: boolean;
  sort?: number;
  layer?: string;
}

type VariantHandler = (input: VariantHandlerInput, next: VariantHandlerNext) => VariantHandlerReturn;

Variant Categories

Combinator Variants

CSS combinator variants for selecting related elements.

// From variants/combinators
const combinatorVariants: Variant[];

Features:

• Child combinator variants (>)
• Adjacent sibling variants (+)
• General sibling variants (~)
• Descendant selector variants

Dark Mode Variants

Dark and light mode variants using class-based and media query approaches.

const variantColorsScheme: Variant[];

Class-based Variants:

• .dark - Applies styles when .dark class is present on parent
• .light - Applies styles when .light class is present on parent

Media Query Variants:

• @dark - Applies styles when system prefers dark color scheme
• @light - Applies styles when system prefers light color scheme

Usage Examples:

<!-- Class-based dark mode -->
<div class="bg-white dark:bg-gray-900">
  <p class="text-black dark:text-white">Content</p>
</div>

<!-- Media query dark mode -->
<div class="bg-white @dark:bg-gray-900">
  <p class="text-black @dark:text-white">Content</p>
</div>

Default Variants

Core variant set from preset-mini including responsive breakpoints and pseudo-classes.

// From variants/default  
const defaultVariants: Variant[];

Features:

• Responsive breakpoints (sm:, md:, lg:, xl:, 2xl:)
• Pseudo-classes (:hover, :focus, :active, etc.)
• Pseudo-elements (::before, ::after, ::placeholder)
• State variants (:checked, :disabled, :required)

Media Query Variants

Extended media query variants for user preferences and device capabilities.

// From variants/media
const mediaVariants: Variant[];

Features:

• Orientation variants (portrait:, landscape:)
• Color scheme variants (os-dark:, os-light:)
• Motion preference variants (motion-ok:, motion-not-ok:)
• Contrast preference variants (high-contrast:, low-contrast:)
• Transparency preference variants (opacity-ok:, opacity-not-ok:)
• Data usage variants (use-data-ok:, use-data-not-ok:)
• Input method variants (touch:, stylus:, pointer:, mouse:)
• Color gamut variants (hd-color:)

Miscellaneous Variants

Additional utility variants for special cases.

// From variants/misc
const miscVariants: Variant[];

Features:

• Print media variants
• Container query variants
• CSS supports variants
• Custom selector variants

Placeholder Variants

Placeholder pseudo-element variants for input styling.

// From variants/placeholder
const placeholderVariants: Variant[];

Features:

• ::placeholder pseudo-element styling
• Placeholder-specific color and typography utilities

Variant Usage Patterns

Responsive Design

<!-- Responsive utility classes -->
<div class="w-full md:w-1/2 lg:w-1/3">
  <p class="text-sm sm:text-base lg:text-lg">Responsive text</p>
</div>

Interactive States

<!-- Hover and focus states -->
<button class="bg-blue-500 hover:bg-blue-700 focus:ring-2 focus:ring-blue-300">
  Click me
</button>

Dark Mode

<!-- Dark mode variants -->
<div class="bg-white dark:bg-gray-800">
  <h1 class="text-gray-900 dark:text-white">Title</h1>
</div>

User Preferences

<!-- Motion and accessibility -->
<div class="animate-pulse motion-not-ok:animate-none">
  <p class="text-base high-contrast:text-lg">Accessible content</p>
</div>

Device Capabilities

<!-- Touch and input method variants -->
<button class="p-2 touch:p-4 mouse:hover:bg-gray-100">
  Adaptive button
</button>

Variant Ordering

Variants are applied in a specific order to ensure proper CSS cascade:

1. Responsive breakpoints
2. User preference media queries
3. Interactive states
4. Dark/light mode
5. Pseudo-elements
6. Combinators

Usage Example:

import { variants } from "@unocss/preset-wind";

// Create variants with options
const variantList = variants({
  important: false
});

// Variants are used internally by the preset
// Individual variant access for advanced use cases