Styling & Theming

Note: The classNames prop has been replaced with className prop in v3. All components now use the standard React className prop instead of the classNames object prop from v2.

Overview

HeroUI v3 introduces significant changes to the styling system:

• CSS-First Architecture: Replaces Tailwind plugin with pure CSS files
• Standard Tailwind Utilities: Custom utilities replaced with standard Tailwind classes
• CSS Variables: New CSS variable naming and structure
• Component Styles: Updated default sizes, spacing, and visual appearance
• No Plugin Required: Removed dependency on Tailwind plugin configuration
• Color System Overhaul: Semantic colors reorganized (primary → accent, secondary removed, numbered scales removed)
• Content Colors Removed: content1-4 replaced with surface and overlay system

Quick Reference

Utility Classes Mapping

Utility Classes Migration

Text Utilities

HeroUI v2 provided custom text size utilities that mapped to CSS variables. v3 uses standard Tailwind text size classes.

v2 Text Utilities:

// v2 - Custom utilities with CSS variables
<div className="text-tiny">Tiny text</div>
<div className="text-small">Small text</div>
<div className="text-medium">Medium text</div>
<div className="text-large">Large text</div>

v3 Text Utilities:

// v3 - Standard Tailwind classes
<div className="text-xs">Tiny text</div>
<div className="text-sm">Small text</div>
<div className="text-base">Medium text</div>
<div className="text-lg">Large text</div>

Mapping Details:

Border Radius Utilities

v2 used custom border radius utilities (rounded-small, rounded-medium, rounded-large) that mapped to CSS variables. v3 uses standard Tailwind border radius classes, but the actual values differ.

v2 Border Radius:

// v2 - Custom utilities
<div className="rounded-small">Small radius</div>
<div className="rounded-medium">Medium radius</div>
<div className="rounded-large">Large radius</div>

v3 Border Radius:

// v3 - Standard Tailwind classes
<div className="rounded-sm">Small radius</div>
<div className="rounded-md">Medium radius</div>
<div className="rounded-lg">Large radius</div>

Value Comparison:

Note: v3 uses smaller default border radius values. If you need the exact v2 values, use arbitrary values:

// Match v2 rounded-small (8px)
<div className="rounded-[8px]">Custom radius</div>

// Match v2 rounded-medium (12px)
<div className="rounded-[12px]">Custom radius</div>

// Match v2 rounded-large (14px)
<div className="rounded-[14px]">Custom radius</div>

Border Width Utilities

v2 provided custom border width utilities (border-small, border-medium, border-large). v3 uses standard Tailwind border width classes.

v2 Border Width:

// v2 - Custom utilities
<div className="border-small border-default">1px border</div>
<div className="border-medium border-primary">2px border</div>
<div className="border-large border-danger">3px border</div>

v3 Border Width:

// v3 - Standard Tailwind classes
<div className="border border-default">1px border</div>
<div className="border-2 border-accent">2px border</div>
<div className="border-[3px] border-danger">3px border</div>

Mapping:

Transition Utilities

v2 provided custom transition utilities for common animation patterns with a default duration of 250ms. v3 removes these utilities in favor of standard Tailwind transition-* utilities, where you specify which properties to transition.

v2 Transition Utilities:

v2 provided custom transition utilities with a default duration of 250ms and ease timing function. The following table shows which CSS properties each utility transitions:

Note: These utilities are no longer available in v3. Use Tailwind's standard transition-* utilities to specify which properties to transition.

Other Utilities

Scrollbar Utilities:

v2 provided .scrollbar-hide and .scrollbar-default utilities. These are not included in v3 by default, but you can use Tailwind's scrollbar plugin or custom CSS.

Animation Utilities:

v2 provided spinner animation utilities (.spinner-bar-animation, .spinner-dot-animation, etc.). These are handled internally by v3 components and are not exposed as utilities.

Custom Utilities:

v2 included utilities like:

• .leading-inherit → Use leading-[inherit]
• .tap-highlight-transparent → Use [-webkit-tap-highlight-color:transparent]
• .input-search-cancel-button-none → Use custom CSS if needed

Theme System Architecture

v2: Plugin-Based System

v2 used a Tailwind CSS plugin that:

1. Generated Utilities: Created custom utility classes via JavaScript
2. CSS Variables: Injected CSS variables through the plugin
3. Theme Configuration: Required configuration in tailwind.config.js
4. Runtime Generation: Utilities generated at build time

v2 Configuration:

// tailwind.config.js
const {heroui} = require("@heroui/react");

module.exports = {
  plugins: [
    heroui({
      layout: {
        fontSize: {
          tiny: "0.75rem",
          small: "0.875rem",
          medium: "1rem",
          large: "1.125rem",
        },
        radius: {
          small: "8px",
          medium: "12px",
          large: "14px",
        },
      },
      themes: {
        light: {
          colors: {
            primary: {
              // color definitions
            },
          },
        },
      },
    }),
  ],
};

v3: CSS-First System

v3 uses a pure CSS approach:

1. CSS Files: Styles defined in CSS files (packages/styles/)
2. CSS Variables: Variables defined in CSS, not generated
3. No Plugin: No Tailwind plugin required
4. Import-Based: Styles imported via CSS imports

v3 Configuration:

/* globals.css */
@import "tailwindcss";
@import "@heroui/styles";

No Tailwind Config Required:

If you only use HeroUI, you can remove tailwind.config.js entirely. If you have custom Tailwind config, keep it but remove the HeroUI plugin.

Architecture Comparison

CSS Variables & Design Tokens

Variable Naming Changes

v2 used the pattern --heroui-{property}-{scale} while v3 uses --{property} or --color-{property}.

v2 CSS Variables:

--heroui-font-size-tiny: 0.75rem;
--heroui-font-size-small: 0.875rem;
--heroui-radius-small: 8px;
--heroui-radius-medium: 12px;
--heroui-border-width-medium: 2px;
--heroui-disabled-opacity: 0.5;

v3 CSS Variables:

/* Typography - handled by Tailwind */
/* No custom font-size variables */

/* Radius */
--radius-xs: calc(var(--radius) * 0.25);
--radius-sm: calc(var(--radius) * 0.5);
--radius-md: calc(var(--radius) * 0.75);
--radius-lg: calc(var(--radius) * 1);
--radius-xl: calc(var(--radius) * 1.5);

/* Colors */
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-accent: var(--accent);
--color-muted: var(--muted);

/* Opacity */
--disabled-opacity: 0.5;

Color System Changes

v2 Color Structure:

--heroui-primary: 210 100% 50%;
--heroui-primary-50: 210 100% 95%;
--heroui-primary-100: 210 100% 90%;
/* ... more shades ... */

v3 Color Structure:

--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: var(--snow);
--accent-hover: color-mix(in oklab, var(--accent) 90%, var(--accent-foreground) 10%);

Key Differences:

1. Color Format: v2 used HSL, v3 uses OKLCH
2. Naming: v2 used numbered shades (50-900), v3 uses semantic names
3. Calculated Colors: v3 uses color-mix() for hover states
4. Foreground Colors: v3 explicitly defines foreground colors
5. Primary → Accent: primary color renamed to accent
6. Secondary Color Removed: secondary semantic color removed (was purple in v2)
7. Numbered Scales Removed: Color scales like primary-50, primary-100, etc. no longer exist

Primary → Accent Rename

v2 used primary as the main brand color. v3 renamed it to accent for better semantic clarity.

v2 Primary Color:

// v2 - Primary color with numbered scales
<Button color="primary">Primary Button</Button>
<div className="bg-primary">Primary background</div>
<div className="bg-primary-50">Light primary</div>
<div className="bg-primary-100">Lighter primary</div>
<div className="text-primary-600">Primary text</div>

v3 Accent Color:

// v3 - Accent color (no numbered scales)
<Button variant="primary">Primary Button</Button>
<div className="bg-accent">Accent background</div>
<div className="bg-accent-soft">Soft accent</div>
<div className="text-accent">Accent text</div>

Migration:

Note: v3 doesn't have numbered color scales (-50, -100, -200, etc.). Use semantic variants like -soft, -hover, or custom Tailwind classes.

Secondary Color Removed

v2 provided a secondary semantic color (purple). This has been removed in v3. Component variants named "secondary" now use different colors.

v2 Secondary Color:

// v2 - Secondary as a semantic color (purple)
<Button color="secondary">Secondary Button</Button>
<div className="bg-secondary">Secondary background</div>
<div className="bg-secondary-50">Light secondary</div>
<div className="text-secondary-600">Secondary text</div>

v3 Secondary Variant:

// v3 - Secondary is a variant, not a color
<Button variant="secondary">Secondary Button</Button>
<div className="bg-default">Default background (used by secondary variant)</div>
<div className="text-accent">Accent text</div>

Migration:

Note: In v3, "secondary" refers to a component variant style (like button--secondary), not a color token. The secondary variant typically uses bg-default and text-accent.

Numbered Color Scales Removed

v2 provided numbered color scales (50-900) for all semantic colors. v3 removed these in favor of semantic variants and calculated colors.

v2 Numbered Scales:

// v2 - Numbered color scales
<div className="bg-primary-50">Lightest</div>
<div className="bg-primary-100">Lighter</div>
<div className="bg-primary-200">Light</div>
<div className="bg-primary-500">Base</div>
<div className="bg-primary-600">Dark</div>
<div className="bg-primary-900">Darkest</div>

v3 Semantic Variants:

// v3 - Semantic variants and calculated colors
<div className="bg-accent-soft">Soft variant</div>
<div className="bg-accent">Base color</div>
<div className="bg-accent-hover">Hover state</div>

Migration:

• Light shades (-50, -100, -200): Use -soft variants or custom Tailwind opacity classes
• Base color (-500): Use base color name (bg-accent, bg-danger, etc.)
• Dark shades (-600, -700, -800, -900): Use hover variants or custom Tailwind classes

Content Colors Removed

v2 provided content1, content2, content3, and content4 colors for layered backgrounds. These have been removed in v3 and replaced with semantic surface colors.

v2 Content Colors:

// v2 - Content colors for layered backgrounds
<div className="bg-content1">Base content</div>
<div className="bg-content2">Secondary content</div>
<div className="bg-content3">Tertiary content</div>
<div className="bg-content4">Quaternary content</div>

v3 Surface Colors:

// v3 - Surface colors for non-overlay components
<div className="bg-surface">Base surface</div>
<div className="bg-surface-secondary">Secondary surface</div>
<div className="bg-surface-tertiary">Tertiary surface</div>
<div className="bg-surface-quaternary">Quaternary surface</div>

// v3 - Overlay colors for floating components
<div className="bg-overlay">Overlay (tooltips, popovers, modals)</div>

Migration Mapping:

Key Changes:

1. Semantic Naming: content1-4 replaced with surface and overlay for clearer semantics
2. Component-Specific: Use bg-surface for page-level components, bg-overlay for floating components
3. Auto-Calculated: Surface levels (secondary, tertiary, quaternary) are automatically calculated from the base surface color using color-mix()

Spacing & Layout Tokens

v2 Layout Tokens:

--heroui-divider-weight: 1px;
--heroui-disabled-opacity: 0.5;
--heroui-hover-opacity: 0.8;

v3 Layout Tokens:

--border-width: 0px;
--field-border-width: var(--border-width);
--disabled-opacity: 0.5;
--cursor-interactive: pointer;
--cursor-disabled: not-allowed;
--radius: 0.5rem;
--field-radius: calc(var(--radius) * 1.5);

Shadow Tokens

v2 Shadows:

--heroui-box-shadow-small: 0px 0px 5px 0px rgb(0 0 0 / 0.02), ...;
--heroui-box-shadow-medium: 0px 0px 15px 0px rgb(0 0 0 / 0.03), ...;
--heroui-box-shadow-large: 0px 0px 30px 0px rgb(0 0 0 / 0.04), ...;

v3 Shadows:

--surface-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), ...;
--overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), ...;
--field-shadow: 0 2px 4px 0 rgba(0, 0, 0, 0.04), ...;

Key Changes:

1. Semantic Naming: v3 uses semantic names (surface-shadow, overlay-shadow) instead of size-based names
2. Component-Specific: Shadows are tied to component types (surface, overlay, field)
3. Dark Mode: Dark mode shadows are transparent in v3

Visual Differences

Alignment Changes

Button Alignment:

• v2: Icons and text aligned with items-center justify-center
• v3: Same alignment, but with responsive height adjustments

Input Alignment:

• v2: Text aligned with text-left
• v3: Same alignment, but padding adjustments may affect visual balance

Spacing Changes

Component Padding:

Most components have increased padding in v3:

• Card: 12px → 16px
• Button: Similar padding, but responsive heights
• Input: Added vertical padding (py-2)

Gap Spacing:

v3 uses more consistent gap spacing:

• Card: gap-3 between header, content, footer
• Button: gap-2 between icon and text
• Chip: gap-1.5 between elements

Size Changes

Button Heights:

• Small: 32px → 36px (mobile) / 32px (desktop)
• Medium: 40px → 40px (mobile) / 36px (desktop)
• Large: 48px → 44px (mobile) / 40px (desktop)

Input Heights:

• Medium: 40px → 36px (default, only size available)

Border Radius Changes

Default Radius:

• v2: Components used rounded-medium (12px) by default
• v3: Components use larger radius values:
  • Button: rounded-3xl (24px)
  • Card: rounded-3xl (24px)
  • Chip: rounded-2xl (16px)
  • Input: rounded-field (typically 12-16px)

Color Appearance Changes

Color System:

• v2: HSL color format
• v3: OKLCH color format (more perceptually uniform)

Default Colors:

• v2: primary, secondary, success, warning, danger
• v3: accent (replaces primary), success, warning, danger

Muted Colors:

• v2: foreground-400, foreground-500 for muted text
• v3: muted color token for muted text

Migration Examples

Utility Class Migration

Example: Text Utilities

<div>
  <h1 className="text-large font-bold">Title</h1>
  <p className="text-small text-foreground-400">Description</p>
  <span className="text-tiny text-foreground-500">Helper</span>
</div>

<div>
  <h1 className="text-lg font-bold">Title</h1>
  <p className="text-sm text-muted">Description</p>
  <span className="text-xs text-muted">Helper</span>
</div>

Border Radius Migration

Example: Matching v2 Radius Values

<Card radius="md">
  <CardBody>Content</CardBody>
</Card>

{/* Option 1: Use standard Tailwind (smaller radius) */}
<Card className="rounded-md">
  <Card.Content>Content</Card.Content>
</Card>

{/* Option 2: Match exact v2 value (12px) */}
<Card className="rounded-[12px]">
  <Card.Content>Content</Card.Content>
</Card>

Theme Customization Migration

Example: Custom Colors

// tailwind.config.js
const {heroui} = require("@heroui/react");

module.exports = {
  plugins: [
    heroui({
      themes: {
        light: {
          colors: {
            primary: {
              DEFAULT: "#006FEE",
              50: "#E6F1FE",
              // ... more shades
            },
          },
        },
      },
    }),
  ],
};

/* globals.css */
@import "tailwindcss";
@import "@heroui/styles";

:root {
  --accent: oklch(0.6204 0.195 253.83);
  --accent-foreground: oklch(0.9911 0 0);
}

Best Practices

1. Use Standard Tailwind: Prefer standard Tailwind utilities over custom ones
2. Match v2 Values: If exact v2 appearance is needed, use arbitrary values
3. Test Responsively: v3 has responsive sizing - test on multiple screen sizes
4. Update CSS Variables: If customizing, update CSS variables instead of Tailwind config
5. Check Component Docs: Refer to individual component migration guides for API changes

Related Guides

• Main Migration Guide
• Theming Documentation
• Styling Guide