HeroUI

Colors

Color palette and theming system for HeroUI v3

Theme sourceTailwind CSS

HeroUI uses CSS variables for colors that automatically switch between light and dark themes. All colors use the oklch color space for better color transitions.

How It Works

HeroUI's color system is built on top of Tailwind CSS v4's theme. When you import @heroui/styles, it uses Tailwind's built-in color palettes (like --color-neutral-*) and maps them to semantic variables.

Add a theme class to your HTML and apply colors to the body:

<html class="light" data-theme="light">
  <body class="bg-background text-foreground">
    <!-- Your app -->
  </body>
</html>

We follow a simple naming pattern:

  • Colors without a suffix are backgrounds (e.g., --accent)
  • Colors with -foreground are for text on that background (e.g., --accent-foreground)
// This gives you the right background and text colors
<div className="bg-accent text-accent-foreground">Hello</div>

Available Colors

Base Colors

These four colors stay the same in all themes:

White
Black
Snow
Eclipse

Background & Surface

Background
Foreground
Surface
Surface Foreground
Overlay
Overlay Foreground

Primary Colors

  • Accent: Your main brand color (used for primary actions)
  • Accent Soft: A lighter version for secondary actions
Accent
Accent Foreground
Accent Soft
Accent Soft Foreground

Status Colors

For alerts, validation, and status messages:

Success
Success Foreground
Warning
Warning Foreground
Danger
Danger Foreground

Form Field Colors

For consistent form field styling across input components:

Field Background
Field Foreground
Field Placeholder
Field Border

Note: These variables default to existing colors but can be overridden for specialized form styling without affecting other components.

Other Colors

Default
Default Foreground
Muted
Border
Focus
Link
Scrollbar

How to Use Colors

In Your Components

// Use Tailwind classes
<div className="bg-background text-foreground">
  <button className="bg-accent text-accent-foreground hover:bg-accent-hover">
    Click me
  </button>
</div>

In CSS Files

global.css
/* Direct CSS variables */
.my-component {
  background: var(--accent);
  color: var(--accent-foreground);
  border: 1px solid var(--border);
}

/* With @apply and @layer */
@layer components {
  .button {
    @apply bg-accent text-accent-foreground;

    &:hover,
    &[data-hovered="true"] {
      @apply bg-accent-hover;
    }

    &:active,
    &[data-pressed="true"] {
      @apply bg-accent-hover;
      transform: scale(0.97);
    }
  }
}

Default Theme

The complete theme definition can be found in (variables.css). This theme automatically switches between light and dark modes based on the class="dark" or data-theme="dark" attributes.

@layer base {
  /* HeroUI Default Theme */
  :root {
    color-scheme: light;

    /* == Common Variables == */

    /* Primitive Colors (Do not change between light and dark) */
    --white: oklch(100% 0 0);
    --black: oklch(0% 0 0);
    --snow: oklch(0.9911 0 0);
    --eclipse: oklch(0.2103 0.0059 285.89);

    /* Spacing scale */
    --spacing: 0.25rem;

    /* Border */
    --border-width: 0px; /* no border by default */
    --field-border-width: var(--border-width);
    --disabled-opacity: 0.5;

    /* Ring offset - Used for focus ring */
    --ring-offset-width: 2px;

    /* Cursor */
    --cursor-interactive: pointer;
    --cursor-disabled: not-allowed;

    /* Radius */
    --radius: 0.5rem;
    --field-radius: calc(var(--radius) * 1.5);

    /* == Light Theme Variables == */

    /* Base Colors */
    --background: oklch(0.9702 0 0);
    --foreground: var(--eclipse);

    /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
    --surface: var(--white);
    --surface-foreground: var(--foreground);

    /* Overlay: Used for floating/overlay components (tooltips, popovers, modals, menus) */
    --overlay: var(--white);
    --overlay-foreground: var(--foreground);

    --muted: oklch(0.5517 0.0138 285.94);
    --scrollbar: oklch(87.1% 0.006 286.286);

    --default: oklch(94% 0.001 286.375);
    --default-foreground: var(--eclipse);

    --accent: oklch(0.6204 0.195 253.83);
    --accent-foreground: var(--snow);

    /* Form Field Defaults - Colors */
    --field-background: var(--white);
    --field-foreground: oklch(0.2103 0.0059 285.89);
    --field-placeholder: var(--muted);
    --field-border: transparent; /* no border by default on form fields */

    /* Status Colors */
    --success: oklch(0.7329 0.1935 150.81);
    --success-foreground: var(--eclipse);

    --warning: oklch(0.7819 0.1585 72.33);
    --warning-foreground: var(--eclipse);

    --danger: oklch(0.6532 0.2328 25.74);
    --danger-foreground: var(--snow);

    /* Component Colors */
    --segment: var(--white);
    --segment-foreground: var(--eclipse);

    /* Misc Colors */
    --border: oklch(0 0 0 / 0%);
    --divider: oklch(92% 0.004 286.32);
    --focus: var(--accent);
    --link: var(--foreground);

    /* Shadows */
    --surface-shadow:
      0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
      0 0 1px 0 rgba(0, 0, 0, 0.06);
    /* Overlay shadow */
    --overlay-shadow: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);
    --field-shadow:
      0 2px 4px 0 rgba(0, 0, 0, 0.04), 0 1px 2px 0 rgba(0, 0, 0, 0.06),
      0 0 1px 0 rgba(0, 0, 0, 0.06);
    /* Skeleton Default Global Animation */
    --skeleton-animation: shimmer; /* shimmer, pulse, none */
  }

  .dark,
  [data-theme="dark"] {
    color-scheme: dark;
    /* == Dark Theme Variables == */

    /* Base Colors */
    --background: oklch(12% 0.005 285.823);
    --foreground: var(--snow);

    /* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
    --surface: oklch(0.2103 0.0059 285.89);
    --surface-foreground: var(--foreground);

    /* Overlay: Used for floating/overlay components (tooltips, popovers, modals, menus) - lighter for contrast */
    --overlay: oklch(0.22 0.0059 285.89); /* A bit lighter than surface for visibility in dark mode */
    --overlay-foreground: var(--foreground);

    --muted: oklch(70.5% 0.015 286.067);
    --scrollbar: oklch(70.5% 0.015 286.067);

    --default: oklch(27.4% 0.006 286.033);
    --default-foreground: var(--snow);

    /* Form Field Defaults - Colors (only the ones that are different from light theme) */
    --field-background: var(--default);
    --field-foreground: var(--foreground);

    /* Status Colors */
    --warning: oklch(0.8203 0.1388 76.34);
    --warning-foreground: var(--eclipse);

    --danger: oklch(0.594 0.1967 24.63);
    --danger-foreground: var(--snow);

    /* Component Colors */
    --segment: oklch(0.3964 0.01 285.93);
    --segment-foreground: var(--foreground);

    /* Misc Colors */
    --border: oklch(1 0 0 / 0%);
    --divider: oklch(22% 0.006 286.033);
    --focus: var(--accent);
    --link: var(--foreground);

    /* Shadows */
    --surface-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
    --overlay-shadow: 0 0 0 0 transparent inset; /* No shadow on dark mode */
    --field-shadow: 0 0 0 0 transparent inset; /* Transparent shadow to allow ring utilities to work */
  }
}

Note: Colors like --color-neutral-*, --color-white, and --color-black come from Tailwind CSS v4's built-in theme.

Customizing Colors

Add Your Own Colors

:root, 
[data-theme="light"] {
  --info: oklch(0.6 0.15 210);
  --info-foreground: oklch(0.98 0 0);
}

.dark,
[data-theme="dark"] {
  --info: oklch(0.7 0.12 210);
  --info-foreground: oklch(0.15 0 0);
}

/* Make the color available to Tailwind */
@theme inline {
  --color-info: var(--info);
  --color-info-foreground: var(--info-foreground);
}

Now you can use it:

<div className="bg-info text-info-foreground">Info message</div>

Note: To learn more about theme variables and how they work in Tailwind CSS v4, see the Tailwind CSS Theme documentation.

Override Existing Colors

:root {
  /* Override default colors */
  --accent: oklch(0.7 0.15 250);
  --success: oklch(0.65 0.15 155);
}

[data-theme="dark"] {
  /* Override dark theme colors */
  --accent: oklch(0.8 0.12 250);
  --success: oklch(0.75 0.12 155);
}

Tip: Convert colors at oklch.com

Quick Tips

  • Always use color variables, not hard-coded values
  • Use foreground/background pairs for good contrast
  • Test in both light and dark modes
  • The system respects user's theme preference automatically

Showcase

Previous Page

Theming

Customize HeroUI's design system with CSS variables and global styles