# Animation **Category**: react **URL**: https://www.heroui.com/docs/react/getting-started/animation **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/getting-started/(handbook)/animation.mdx > Add smooth animations and transitions to HeroUI v3 components HeroUI components support multiple animation approaches: built-in CSS transitions, custom CSS animations, and JavaScript libraries like Framer Motion. ## Built-in Animations HeroUI components use data attributes to expose their state for animation: ```css /* Popover entrance/exit */ .popover[data-entering] { @apply animate-in zoom-in-90 fade-in-0 duration-200; } .popover[data-exiting] { @apply animate-out zoom-out-95 fade-out duration-150; } /* Button press effect */ .button:active, .button[data-pressed="true"] { transform: scale(0.97); } /* Accordion expansion */ .accordion__panel[aria-hidden="false"] { @apply h-[var(--panel-height)] opacity-100; } ``` **State attributes for styling:** * `[data-hovered="true"]` - Hover state * `[data-pressed="true"]` - Active/pressed state * `[data-focus-visible="true"]` - Keyboard focus * `[data-disabled="true"]` - Disabled state * `[data-entering]` / `[data-exiting]` - Transition states * `[aria-expanded="true"]` - Expanded state ## CSS Animations **Using Tailwind utilities:** ```tsx // Pulse on hover // Fade in entrance Welcome message // Staggered list

Item 1 Item 2

``` **Custom transitions:** ```css /* Slower accordion */ .accordion__panel { @apply transition-all duration-500; } /* Bouncy button */ .button:active { animation: bounce 0.3s; } @keyframes bounce { 50% { transform: scale(0.95); } } ``` ## Framer Motion HeroUI components work seamlessly with Framer Motion for advanced animations. **Basic usage:** ```tsx import { motion } from 'framer-motion'; import { Button } from '@heroui/react'; const MotionButton = motion(Button); Animated Button ``` **Entrance animations:** ```tsx Welcome! ``` **Layout animations:** ```tsx import { AnimatePresence, motion } from 'framer-motion'; function Tabs({ items, selected }) { return (

{items.map((item, i) => ( ))}

); } ``` ## Render Props Apply dynamic animations based on component state: ```tsx ``` ## Accessibility **Respecting motion preferences:** HeroUI automatically respects user motion preferences using Tailwind's `motion-reduce:` utility. All built-in transitions and animations are disabled when users enable "reduce motion" in their system settings. HeroUI extends Tailwind's `motion-reduce:` variant to support both the native `prefers-reduced-motion` media query and the `data-reduce-motion` attribute. ```css /* HeroUI pattern - uses Tailwind's motion-reduce: */ .button { @apply transition-colors motion-reduce:transition-none; } /* Expands to support both approaches: */ @media (prefers-reduced-motion: reduce) { .button { transition: none; } } [data-reduce-motion="true"] .button { transition: none; } ``` With Framer Motion: ```tsx import { useReducedMotion } from 'framer-motion'; function AnimatedCard() { const shouldReduceMotion = useReducedMotion(); return ( Content ); } ``` **Disabling animations globally:** Add `data-reduce-motion="true"` to the `` or `` tag: ```html ``` HeroUI automatically detects the user's `prefers-reduced-motion: reduce` setting and disables animations accordingly. ## Performance Tips **Use GPU-accelerated properties:** Prefer `transform` and `opacity` for smooth animations: ```css /* Good - GPU accelerated */ .slide-in { transform: translateX(-100%); transition: transform 0.3s; } /* Avoid - Triggers layout */ .slide-in { left: -100%; transition: left 0.3s; } ``` **Will-change optimization:** Use `will-change` to optimize animations, but remove it when not animating: ```css .button { will-change: transform; } .button:not(:hover) { will-change: auto; } ``` ## Next Steps * Learn about [Styling](/docs/handbook/styling) approaches * Explore [Component](/docs/react/components) examples * View [Theming](/docs/handbook/theming) documentation # Colors **Category**: react **URL**: https://www.heroui.com/docs/react/getting-started/colors **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/getting-started/(handbook)/colors.mdx > Color palette and theming system for HeroUI v3 import {ColorSectionSideBySide, ColorSectionStacked, ColorSectionFormField, ColorSectionPrimitive} from "@/components/color-section"; HeroUI'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. **Want to create your own theme?** Try the [Theme Builder](/themes) to visually customize colors, radius, fonts, and more — then export the CSS to use in your project. ## 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:** ```jsx

``` **In CSS files:** ```css title="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](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/themes/default/variables.css)). This theme automatically switches between light and dark modes based on the `class="dark"` or `data-theme="dark"` attributes. ```css @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: 1px; --field-border-width: 0px; --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(92% 0.004 286.32); --separator: oklch(92% 0.004 286.32); --focus: var(--accent); --link: var(--foreground); /* Backdrop */ --backdrop: rgba(0, 0, 0, 0.5); /* 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(22% 0.006 286.033); --separator: oklch(22% 0.006 286.033); --focus: var(--accent); --link: var(--foreground); /* Backdrop */ --backdrop: rgba(0, 0, 0, 0.6); /* 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 */ } } ``` ## Customizing Colors **Override existing colors:** ```css :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](https://oklch.com) **Add your own colors:** ```css :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: ```tsx

Info message

Info message

); } ``` HeroUI v3 does not require a provider. Components work directly after installation and style import. ### 3 Locale Setup (Optional) To integrate with Next.js, ensure the locale on the server matches the client. In your root layout, determine the user's preferred language and set the `lang` and `dir` attributes on the `` element. ```tsx // app/layout.tsx import {headers} from 'next/headers'; import {isRTL} from '@heroui/react'; import {ClientProviders} from './provider'; export default async function RootLayout({children}) { // Get the user's preferred language from the Accept-Language header. // You could also get this from a database, URL param, etc. const acceptLanguage = (await headers()).get('accept-language'); const lang = acceptLanguage?.split(/[,;]/)[0] || 'en-US'; return ( {children} ); } ``` Create `app/provider.tsx`. This should render an `I18nProvider` to set the locale used by React Aria. ```tsx // app/provider.tsx "use client"; import {I18nProvider} from '@heroui/react'; export function ClientProviders({lang, children}) { return ( {children} ); } ``` If you are using a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) (CSP) with a nonce, add a `` tag to your document head, setting the content attribute to the generated nonce value. React Aria automatically reads the nonce from this tag. ## Vite ### 1. Create a Vite project ```bash npx heroui-cli@latest init ``` When prompted, select the **Vite** template. Then open your new folder and install dependencies (for example `pnpm install`). ### 2. Use your first HeroUI component Example: `src/App.tsx` ```tsx import {Button} from "@heroui/react"; function App() { return (

Install in Cursor

Or manually add to **Cursor Settings** → **Tools** → **MCP Servers**: ```json title=".cursor/mcp.json" { "mcpServers": { "heroui-react": { "command": "npx", "args": ["-y", "@heroui/react-mcp@latest"] } } } ``` Alternatively, add the following to your `~/.cursor/mcp.json` file. To learn more, see the [Cursor documentation](https://cursor.com/docs/context/mcp). ### Claude Code Run this command in your terminal: ```bash claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest ``` Or manually add to your project's `.mcp.json` file: ```json title=".mcp.json" { "mcpServers": { "heroui-react": { "command": "npx", "args": ["-y", "@heroui/react-mcp@latest"] } } } ``` After adding the configuration, restart Claude Code and run `/mcp` to see the HeroUI MCP server in the list. If you see **Connected**, you're ready to use it. See the [Claude Code MCP documentation](https://docs.claude.com/en/docs/claude-code/mcp) for more details. ### Windsurf Add the HeroUI server to your project's `.windsurf/mcp.json` configuration file: ```json title=".windsurf/mcp.json" { "mcpServers": { "heroui-react": { "command": "npx", "args": ["-y", "@heroui/react-mcp@latest"] } } } ``` After adding the configuration, restart Windsurf to activate the MCP server. See the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp) for more details. ### Zed Add the HeroUI server to your `settings.json` configuration file. Open settings via Command Palette (`zed: open settings`) or use `Cmd-,` (Mac) / `Ctrl-,` (Linux): ```json title="settings.json" { "context_servers": { "heroui-react": { "command": "npx", "args": ["-y", "@heroui/react-mcp@latest"], "env": {} } } } ``` After adding the configuration, restart Zed and open the Agent Panel settings view. Check that the indicator dot next to the heroui server is green with "Server is active" tooltip. See the [Zed MCP documentation](https://zed.dev/docs/ai/mcp) for more details. ### VS Code To configure MCP in VS Code with GitHub Copilot, add the HeroUI server to your project's `.vscode/mcp.json` configuration file: ```json title=".vscode/mcp.json" { "servers": { "heroui-react": { "type": "stdio", "command": "npx", "args": ["-y", "@heroui/react-mcp@latest"] } } } ``` After adding the configuration, open `.vscode/mcp.json` and click **Start** next to the heroui-react server. See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more details. ### Codex Add the HeroUI server to your `~/.codex/config.toml` (or a project-scoped `.codex/config.toml`): ```toml title="config.toml" [mcp_servers.heroui-react] command = "npx" args = ["-y", "@heroui/react-mcp@latest"] ``` After adding the configuration, restart Codex and run `/mcp` in the TUI to verify the server is active. See the [Codex MCP documentation](https://developers.openai.com/codex/mcp) for more details. ### OpenCode Add the HeroUI server to your project's `opencode.json` configuration file: ```json title="opencode.json" { "$schema": "https://opencode.ai/config.json", "mcp": { "heroui-react": { "type": "local", "command": ["npx", "-y", "@heroui/react-mcp@latest"] } } } ``` After adding the configuration, restart OpenCode to activate the MCP server. See the [OpenCode MCP documentation](https://open-code.ai/docs/en/mcp-servers) for more details. ## Usage Once configured, ask your AI assistant questions like: * "Help me install HeroUI v3 in my Next.js/Vite/Astro app" * "Show me all HeroUI components" * "What props does the Button component have?" * "Give me an example of using the Card component" * "Get the source code for the Button component" * "Show me the CSS styles for Card" * "What are the theme variables for dark mode?" ### Automatic Updates The MCP server can help you upgrade to the latest HeroUI version: ```bash "Hey Cursor, update HeroUI to the latest version" ``` Your AI assistant will automatically: * Compare your current version with the latest release * Review the changelog for breaking changes * Apply the necessary code updates to your project This works for any version upgrade, whether you're updating to the latest stable or pre-release version. ## Available Tools The MCP server provides these tools to AI assistants: | Tool | Description | | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_components` | List all available HeroUI v3 components | | `get_component_docs` | Get complete component documentation including anatomy, props, examples, and usage patterns for one or more components | | `get_component_source_code` | Access the React/TypeScript source code (.tsx files) for components | | `get_component_source_styles` | View the CSS styles (.css files) for components | | `get_theme_variables` | Access theme variables for colors, typography, spacing with light/dark mode support | | `get_docs` | Browse the full HeroUI v3 documentation including guides and principles (use path `/docs/react/getting-started/quick-start` for installation instructions) | ## Troubleshooting **Requirements:** Node.js 22 or higher. The package will be automatically downloaded when using `npx`. **Need help?** [GitHub Issues](https://github.com/heroui-inc/heroui-mcp/issues) | [Discord Community](https://discord.gg/heroui) ## Links * [npm Package](https://www.npmjs.com/package/@heroui/react-mcp) * [GitHub Repository](https://github.com/heroui-inc/heroui-mcp) * [Contributing Guide](https://github.com/heroui-inc/heroui-mcp/blob/main/CONTRIBUTING.md)