Colors

HeroUI Native's color system is built around semantic intent, not visual abundance. Instead of exposing large raw palettes, the system defines a small, meaningful set of color roles that cover the majority of interface needs.

Most colors in the system are derived automatically from a limited number of base values. This allows HeroUI to maintain consistent contrast, hierarchy, and theming behavior while keeping the system easy to reason about and modify.

Colors should communicate purpose and state first. Visual variation comes from scale, emphasis, and context.

Accent

The accent color represents the primary brand or product identity. It is used to draw attention to key actions, highlights, and moments of emphasis.

Accent should be used intentionally and sparingly. Overuse reduces its impact and can harm visual hierarchy. In most cases, components derive multiple accent-related values (hover, subtle backgrounds, focus states) automatically from the base accent color.

Default (neutrals)

Default colors form the neutral backbone of the system. They are used for most non-emphasized UI elements.

Success

Success colors communicate positive outcomes, confirmations, and completed states. They are typically used in feedback components, status indicators, and validation states.

Warning

Warning colors indicate caution, risk, or actions that require attention but are not destructive. They are commonly used for alerts, messages, and transitional states where the user should pause or review information.

Danger

Danger colors represent destructive, irreversible, or critical actions and states. They should be immediately recognizable and used consistently for errors, destructive buttons, and critical alerts.

Foreground

Foreground colors are used for primary content such as text and icons. These colors are optimized for readability and accessibility and adapt automatically to background and surface contexts. Foreground colors should never be hard-coded at the component level.

Background

Background colors define the base canvas of the interface. They establish overall contrast and mood while staying visually quiet.

Surface

Surface colors sit on top of backgrounds and are used for containers such as cards, panels, modals, and dropdown. Surfaces help create visual separation and hierarchy through elevation, contrast, and layering rather than strong color shifts.

Form field

Form field colors are specialized tokens used for inputs, controls, and interactive fields. They account for multiple states such as default, focus, and hover. Isolating them ensures form elements have a distinct visual language from buttons and the rest of the UI.

Separator

Separator colors are used for dividers, outlines, and subtle boundaries. They exist to structure content and guide the eye without adding noise. Separator colors should remain low contrast and unobtrusive.

Other

Other colors serve specific utility roles across the interface. They exist to structure content and guide the eye without adding noise.

Primitive

Primitive colors are mode agnostic values used as foundations for semantic color tokens. They do not change between light and dark themes.

How to Use Colors

In your components:

import { View, Text } from 'react-native';

<View className="bg-background flex-1 p-4">
  <Text className="text-foreground mb-4">Content</Text>
  <Button variant="primary" className="bg-accent">
    <Button.Label className="text-accent-foreground">Click me</Button.Label>
  </Button>
</View>;

In CSS files:

/* Direct CSS variables */
.container {
  flex: 1;
  background-color: var(--accent);
  width: 50px;
  height: 50px;
  border-radius: var(--radius);
}

Default Theme

The complete theme definition can be found in (variables.css). This theme automatically switches between light and dark modes through Uniwind's theming system, which supports system preferences and programmatic theme switching.

@theme {
  /* 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);

Customizing Colors

Override existing colors:

@layer theme {
  @variant light {
    /* Override default colors */
    --accent: oklch(0.65 0.25 270); /* Custom indigo accent */
    --success: oklch(0.65 0.15 155);
  }

  @variant dark {
    /* Override dark theme colors */
    --accent: oklch(0.65 0.25 270);
    --success: oklch(0.75 0.12 155);
  }
}

Tip: Convert colors at oklch.com

Add your own colors:

@layer theme {
  @variant light {
    --info: oklch(0.6 0.15 210);
    --info-foreground: oklch(0.98 0 0);
  }

  @variant dark {
    --info: oklch(0.7 0.12 210);
    --info-foreground: oklch(0.15 0 0);
  }
}

@theme inline {
  --color-info: var(--info);
  --color-info-foreground: var(--info-foreground);
}

Now you can use it:

import { View, Text } from 'react-native';

<View className="bg-info p-4 rounded-lg">
  <Text className="text-info-foreground">Info message</Text>
</View>;

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

useThemeColor Hook

The useThemeColor hook has been enhanced to support multiple colors selection, making it more flexible for complex theming scenarios.

Multiple Colors Selection:

You can now select multiple colors at once, which is useful when you need to work with related color values together:

import { useThemeColor } from 'heroui-native';

// Select multiple colors at once
const [accent, accentForeground, success, danger] = useThemeColor([
  'accent',
  'accentForeground',
  'success',
  'danger',
]);

// Use the selected colors
<View style={{ backgroundColor: accent }}>
  <Text style={{ color: accentForeground }}>Accent Text</Text>
</View>;

This enhancement improves performance when working with multiple color values and makes it easier to manage complex theming scenarios where multiple colors need to be selected and applied together.