Variants

Comprehensive variant system supporting responsive breakpoints, pseudo-classes, dark mode, arbitrary selectors, and advanced CSS targeting for conditional utility application.

Capabilities

Variants Function

Creates the complete collection of variant handlers for the preset.

/**
 * Creates variants collection with configuration-based customization
 * @param options - Preset configuration options affecting variant behavior
 * @returns Array of variant handlers for the preset
 */
function variants(options: PresetMiniOptions): Variant[];

Usage Example:

import { variants } from "@unocss/preset-mini/variants";
import type { PresetMiniOptions } from "@unocss/preset-mini";

const options: PresetMiniOptions = {
  dark: 'class',
  attributifyPseudo: false,
};

const variantHandlers = variants(options);

Variant Categories

Responsive Breakpoints

Responsive design variants using mobile-first approach with theme-defined breakpoints.

Breakpoint Variants:

• sm: - @media (min-width: 640px)
• md: - @media (min-width: 768px)
• lg: - @media (min-width: 1024px)
• xl: - @media (min-width: 1280px)
• 2xl: - @media (min-width: 1536px)

Custom range variants:

• <sm: - @media (max-width: 639px)
• <md: - @media (max-width: 767px)
• @md: - @media (min-width: 768px) and (max-width: 1023px)

Vertical breakpoint variants (height-based):

• Available when verticalBreakpoints are defined in theme

Usage Examples:

<!-- Responsive width -->
<div class="w-full md:w-1/2 lg:w-1/3">
  Responsive width
</div>

<!-- Responsive text size -->
<h1 class="text-xl md:text-2xl lg:text-3xl">
  Responsive heading
</h1>

Dark Mode Variants

Dark mode support with configurable detection method.

Dark Mode Variants:

• dark: - Applied in dark mode context
• light: - Applied in light mode context (when using custom selectors)

Configuration-dependent behavior:

// Class-based (default)
dark: 'class' // Uses .dark ancestor selector

// Media query-based
dark: 'media' // Uses @media (prefers-color-scheme: dark)

// Custom selectors
dark: {
  dark: '.dark-theme',
  light: '.light-theme'
}

Usage Examples:

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

<!-- Works with any utility -->
<button class="border border-gray-300 dark:border-gray-700 hover:bg-gray-100 dark:hover:bg-gray-800">
  Button with dark mode
</button>

Pseudo-Class Variants

Comprehensive pseudo-class support for interactive states and element targeting.

Interactive States:

• hover: - :hover
• focus: - :focus
• active: - :active
• visited: - :visited
• focus-within: - :focus-within
• focus-visible: - :focus-visible

Form States:

• checked: - :checked
• disabled: - :disabled
• enabled: - :enabled
• required: - :required
• invalid: - :invalid
• valid: - :valid
• in-range: - :in-range
• out-of-range: - :out-of-range

Structural Pseudo-classes:

• first: - :first-child
• last: - :last-child
• odd: - :nth-child(odd)
• even: - :nth-child(even)
• first-of-type: - :first-of-type
• last-of-type: - :last-of-type
• only: - :only-child
• only-of-type: - :only-of-type

Usage Examples:

<!-- Interactive states -->
<button class="bg-blue-500 hover:bg-blue-600 focus:ring-2 focus:ring-blue-300 active:bg-blue-700">
  Interactive button
</button>

<!-- Form validation states -->
<input class="border border-gray-300 valid:border-green-500 invalid:border-red-500" />

<!-- Structural targeting -->
<ul>
  <li class="first:font-bold odd:bg-gray-100">Item 1</li>
  <li class="odd:bg-gray-100">Item 2</li>
  <li class="last:border-b-0 odd:bg-gray-100">Item 3</li>
</ul>

Pseudo-Element Variants

Pseudo-element variants for content generation and styling.

Available Pseudo-elements:

• before: - ::before
• after: - ::after
• first-line: - ::first-line
• first-letter: - ::first-letter
• backdrop: - ::backdrop
• placeholder: - ::placeholder
• file: - ::file-selector-button
• marker: - ::marker
• selection: - ::selection

Usage Examples:

<!-- Decorative elements -->
<div class="before:content-[''] before:absolute before:inset-0 before:bg-gradient-to-r before:from-blue-500 before:to-purple-500">
  Content with gradient overlay
</div>

<!-- Form styling -->
<input class="placeholder:text-gray-400 placeholder:italic" placeholder="Enter text..." />

ARIA and Data Attribute Variants

Support for ARIA states and custom data attributes.

ARIA Variants:

• aria-checked: - [aria-checked="true"]
• aria-disabled: - [aria-disabled="true"]
• aria-expanded: - [aria-expanded="true"]
• aria-hidden: - [aria-hidden="true"]
• aria-pressed: - [aria-pressed="true"]
• aria-readonly: - [aria-readonly="true"]
• aria-required: - [aria-required="true"]
• aria-selected: - [aria-selected="true"]

Data Attribute Variants:

• data-*: - Custom data attribute matching
• Configurable through theme data configuration

Usage Examples:

<!-- ARIA-based styling -->
<button class="aria-expanded:bg-blue-100 aria-pressed:bg-blue-200" aria-expanded="false">
  Expandable button
</button>

<!-- Data attribute styling -->
<div class="data-[state=open]:bg-green-100" data-state="closed">
  State-dependent styling
</div>

Child and Sibling Combinators

Advanced selector combinators for targeting related elements.

Child Combinators:

• *: - > * (direct children)
• first-child: - > :first-child
• last-child: - > :last-child

Group Variants:

• group-hover: - Applied when ancestor with group class is hovered
• group-focus: - Applied when ancestor with group class is focused
• group-active: - Applied when ancestor with group class is active

Usage Examples:

<!-- Group interaction -->
<div class="group">
  <img class="group-hover:scale-110 transition-transform" />
  <p class="group-hover:text-blue-600">Hover the parent to transform both</p>
</div>

<!-- Child targeting -->
<nav class="*:px-4 *:py-2 *:rounded">
  <a href="#">All children get padding and rounded corners</a>
  <a href="#">Automatically applied</a>
</nav>

Container Query Variants

Modern container query support for component-based responsive design.

Container Variants:

• @container: - Container query support
• @xs:, @sm:, @md:, @lg:, @xl: - Container-based breakpoints
• Requires container configuration in theme

Usage Example:

<div class="@container">
  <div class="@md:flex @md:space-x-4">
    Content that responds to container size
  </div>
</div>

Media Query Variants

Custom media query variants for advanced responsive design.

Print Variants:

• print: - @media print

Motion Preferences:

• motion-safe: - @media (prefers-reduced-motion: no-preference)
• motion-reduce: - @media (prefers-reduced-motion: reduce)

Custom Media Queries:

• Configurable through theme media configuration

CSS Supports Variants

Feature query variants for progressive enhancement.

Supports Variants:

• supports-[property:value]: - @supports (property: value)
• Configurable through theme supports configuration

Usage Example:

<div class="grid supports-[display:subgrid]:subgrid">
  Falls back to grid, uses subgrid if supported
</div>

Arbitrary Variants

Powerful arbitrary variant syntax for custom selectors when arbitraryVariants is enabled.

Arbitrary Syntax:

• [selector]: - Custom CSS selector
• [&>*]: - Target direct children
• [&[attr]]: - Target elements with attributes
• [.parent_&]: - Custom parent selector

Usage Examples:

<!-- Target all children -->
<div class="[&>*]:margin-4">
  All direct children get margin
</div>

<!-- Complex selectors -->
<details class="[&[open]>summary]:text-blue-600">
  <summary>Click to expand</summary>
  <p>Content</p>
</details>

<!-- Parent-based styling -->
<div class="[.sidebar_&]:hidden">
  Hidden when inside .sidebar
</div>

Important Modifier

Force important on any utility with the ! prefix.

Important Variants:

• ! - Adds !important to CSS declarations

Usage Example:

<div class="!text-red-500">
  This text color cannot be overridden
</div>

Negative Value Variants

Automatic negative value support for applicable utilities.

Negative Variants:

• - prefix for negative values
• Applied automatically to spacing, transforms, etc.

Usage Example:

<div class="-mt-4 -translate-x-2">
  Negative margin and transform
</div>

Variant Stacking

Variants can be combined and stacked for complex conditional styling:

<!-- Multiple variants -->
<button class="md:hover:focus:bg-blue-600 dark:md:hover:bg-gray-700">
  Complex conditional styling
</button>

<!-- Arbitrary with standard variants -->
<div class="hover:[&>*]:scale-110 focus-within:[&>*]:opacity-75">
  Combined arbitrary and standard variants
</div>

Configuration Integration

Variants respect preset configuration options:

• dark option affects dark mode variant behavior
• attributifyPseudo changes group/peer selector generation
• arbitraryVariants enables/disables arbitrary variant syntax
• Theme configuration extends available breakpoints, media queries, etc.