@heroui/styles
Advanced tools
The core HeroUI styles package containing CSS files for components, themes, and utilities. This package provides the foundation for HeroUI's design system using Tailwind CSS v4 and is framework-agnostic.
It's the heroui.com website for the latest version of HeroUI.
npm install @heroui/styles
# or
pnpm add @heroui/styles
# or
yarn add @heroui/styles
Import the HeroUI styles in your main CSS file:
@import "@heroui/styles";
This will import:
The package exports CSS files organized into:
@heroui/styles/
├── index.css # Main entry point
├── base/ # Base styles and CSS variables
│ └── base.css # Layout tokens, typography, scrollbar
├── components/ # Component-specific styles
│ ├── accordion.css
│ ├── avatar.css
│ ├── button.css
│ ├── chip.css
│ ├── link.css
│ ├── popover.css
│ └── tooltip.css
├── themes/ # Theme definitions
│ ├── default/ # Default theme
│ │ ├── index.css # Theme entry point
│ │ └── variables.css # Theme variables (light/dark)
│ └── shared/ # Shared theme utilities
│ └── theme.css # Calculated variables and utilities
└── utilities/ # Utility classes
├── backdrop.css
└── index.css
Instead of importing everything, you can import only what you need:
/* Import Tailwind CSS base */
@import "tailwindcss";
/* Import only specific components */
@import "@heroui/styles/components/button.css" layer(components);
@import "@heroui/styles/components/chip.css" layer(components);
/* Import theme */
@import "@heroui/styles/themes/default" layer(base);
Components use a BEM-like naming convention:
.button.button--primary, .button--danger.button--sm, .button--lg.button--icon-only<!-- Basic button -->
<button class="button">Click me</button>
<!-- Primary variant -->
<button class="button button--primary">Save</button>
<!-- Small size -->
<button class="button button--sm">Small</button>
<!-- Icon-only button -->
<button class="button button--icon-only">
<svg>...</svg>
</button>
<!-- Combining classes -->
<button class="button button--primary button--sm">Small Primary</button>
The default theme provides automatic light/dark mode support:
:root.dark class or [data-theme="dark"] attribute<!-- Dark mode with class -->
<html class="dark">
<!-- Dark mode with data attribute -->
<html data-theme="dark"></html>
</html>
The package provides a comprehensive set of CSS variables for customization:
:root {
/* Spacing */
--spacing: 0.25rem;
/* Border */
--border-width: 0px; /* no border by default */
--field-border-width: var(--border-width);
--disabled-opacity: 0.5;
/* Radius */
--radius: 0.5rem;
--field-radius: calc(var(--radius) * 1.5);
/* Ring offset - Used for focus ring */
--ring-offset-width: 2px;
/* Cursor */
--cursor-interactive: pointer;
--cursor-disabled: not-allowed;
}
:root {
/* 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);
/* 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);
/* Interactive Colors */
--accent: oklch(0.6204 0.195 253.83);
--accent-foreground: var(--snow);
/* 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);
/* UI Colors */
--border: oklch(0 0 0 / 0%);
--separator: 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: 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);
}
Note: Dark mode overrides specific variables (like --background, --surface, --overlay, --muted, --scrollbar, --default, --warning, --danger, --segment, --separator, and shadow values) when .dark class or [data-theme="dark"] attribute is applied.
:root {
/* Form field defaults */
--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 */
--field-border-width: var(--border-width);
--field-radius: calc(var(--radius) * 1.5);
}
Providing any of these knobs automatically updates the generated utilities (bg-field, placeholder:text-field-placeholder, rounded-field, etc.) along with the calculated hover/focus variants.
The theme also provides calculated variables for hover states, soft colors, and surface levels (defined in themes/shared/theme.css):
--color-accent-hover, --color-success-hover, --color-warning-hover, --color-danger-hover, --color-default-hover--color-accent-soft, --color-danger-soft, --color-warning-soft, --color-success-soft (with their foreground and hover variants)--color-surface-secondary, --color-surface-tertiary--radius-xs through --radius-4xl (calculated from --radius)--ease-smooth, --ease-out-fuild, etc.The package provides:
index.css: Main unminified CSS fileheroui.min.css: Minified production-ready CSS (generated during build)This package is designed to work with any framework. For React-specific components, use @heroui/react which builds on top of these core styles.
MIT
FAQs
HeroUI core styles and Tailwind plugin
We found that @heroui/styles demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
pnpm 11.10 hardens registry auth to block token redirection, tightens pack-app and deploy, and makes the Rust port (v12) installable.
Security News
/Research
Socket uncovered 17 malicious npm and PyPI packages typosquatting Paysafe, Skrill, and Neteller SDKs to steal developer secrets.
Security News
Node.js is debating whether AI-driven security report volume warrants moving more vulnerability reports into public workflows.