# Introduction **Category**: native **URL**: https://v3.heroui.com/docs/native/getting-started **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/index.mdx > An open-source UI component library for building beautiful and accessible user interfaces. HeroUI Native is a component library built on [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4) via [Uniwind](https://uniwind.dev/) and modern mobile development technologies. Every component comes with smooth animations, polished details, and built-in accessibility—ready to use, fully customizable. ## Why HeroUI Native? **Beautiful by default** — Professional look out of the box, no extra styling needed. **Accessible** — Accessibility is managed following mobile development best practices, with proper focus management, touch accessibility, and screen reader support built into every component. **Flexible** — Each component is made of customizable parts. Change what you need, leave the rest. **Developer-friendly** — Fully typed APIs, predictable patterns, and excellent autocompletion. **Maintained** — We handle updates, bug fixes, and new features. Just update the package. **Lightweight** — Tree-shaken. Only what you use goes into your app. **Future-proof** — Compatible with the latest [Expo](https://expo.dev/) and on [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4) via [Uniwind](https://uniwind.dev/), designed for AI-assisted development. ## A Living Library, Not Copy-Paste Copy-paste code works until it breaks. You're left maintaining outdated dependencies that stop evolving. HeroUI Native is different. It's a living library that grows with you: * Automatic updates and fixes * New features without extra work * Components stay current with React Native, Tailwind, and mobile platforms * Deep customization, not shallow theme tweaks * AI-friendly APIs for code generation HeroUI Native is not a snapshot—it's a garden that keeps growing. 🌱 ## HeroUI Ecosystem * **🌐 HeroUI v3** (web) — React components with Tailwind CSS v4 * **📱 HeroUI Native (mobile)** — Beautiful components for React Native * **🤖 [HeroUI Chat](https://heroui.chat?ref=heroui-v3)** (text-to-app) — Create apps with natural language * **🧠 UI for LLMs** — New platform & MCPs coming soon ## FAQ **Is HeroUI Native free?** Yes, completely free and open source under the MIT license. **Is it production-ready?** Currently in **beta**. We're actively working towards a stable release with community feedback. **Can I customize the components?** Yes! Update default styles, animations or compose component parts differently. Every slot is customizable. **Does it work with TypeScript?** Fully typed with excellent IDE support and autocompletion. **What about accessibility?** Accessibility follows mobile development best practices with proper focus management, touch accessibility, and screen reader support built into every component. **Is there a Figma file?** Yes! Access our design system at [HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429). ## Get Involved Join the community, share feedback, or contribute: * [GitHub Discussions](https://github.com/heroui-inc/heroui-native/discussions) * [Discord](https://discord.gg/9b6yyZKmH4) * [X/Twitter](https://x.com/hero_ui) * [Contributing Guidelines](https://github.com/heroui-inc/heroui-native/blob/main/CONTRIBUTING.md) HeroUI Native is released under the [MIT License](https://github.com/heroui-inc/heroui-native/blob/main/LICENSE). # All Components **Category**: native **URL**: https://v3.heroui.com/docs/native/components **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/index.mdx > Explore the full list of components available in HeroUI Native. More are on the way. # All Components **Category**: react **URL**: https://v3.heroui.com/docs/react/components **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/index.mdx > Explore the full list of components available in the library. More are on the way. # Introduction **Category**: react **URL**: https://v3.heroui.com/docs/react/getting-started **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/getting-started/index.mdx > An open-source UI component library for building beautiful and accessible user interfaces. HeroUI is a React component library built on [Tailwind CSS v4](https://tailwindcss.com/) and [React Aria Components](https://react-spectrum.adobe.com/react-aria/index.html). Every component comes with smooth animations, polished details, and built-in accessibility—ready to use, fully customizable. ## Why HeroUI? **Beautiful by default** — Professional look out of the box, no extra styling needed. **Accessible** — Built on [React Aria Components](https://react-spectrum.adobe.com/react-aria/components.html) with focus management, keyboard navigation, and screen reader support. **Flexible** — Each component is made of customizable parts. Change what you need, leave the rest. **Developer-friendly** — Fully typed APIs, predictable patterns, and excellent autocompletion. **Maintained** — We handle updates, bug fixes, and new features. Just update the package. **Lightweight** — Tree-shaken. Only what you use goes into your app. **Future-proof** — Built for [React 19](https://react.dev/blog/2024/12/05/react-19) and [Tailwind v4](https://tailwindcss.com/blog/tailwindcss-v4), designed for AI-assisted development. ## A Living Library, Not Copy-Paste Copy-paste code works until it breaks. You're left maintaining outdated dependencies that stop evolving. HeroUI is different. It's a living library that grows with you: * Automatic updates and fixes * New features without extra work * Components stay current with React, Tailwind, and browsers * Deep customization, not shallow theme tweaks * AI-friendly APIs for code generation HeroUI v3 is not a snapshot—it's a garden that keeps growing. 🌱 ## HeroUI Ecosystem * **🌐 HeroUI v3** (web) — You're here! React components with Tailwind CSS v4 * **📱 [HeroUI Native](https://link.heroui.com/native)** (mobile) — Beautiful components for React Native * **🤖 [HeroUI Chat](https://heroui.chat?ref=heroui-v3)** (text-to-app) — Create apps with natural language * **🧠 UI for LLMs** — New platform & MCPs coming soon **Why React Aria?** We chose React Aria for accessibility at scale. We've used it since HeroUI v2, and v3 keeps familiar API conventions like `isDisabled` and `onPress`. Thanks to [Devon Govett](https://x.com/devongovett) and the Adobe team. ## FAQ **Is HeroUI free?** Yes, completely free and open source under the MIT license. **Is it production-ready?** Currently in **beta**. We're actively working towards a stable release with community feedback. **Can I customize the components?** Yes! Use Tailwind utilities, CSS variables, [BEM](https://getbem.com/) modifiers, or compose component parts differently. Every slot is customizable. **Does it work with TypeScript?** Fully typed with excellent IDE support and autocompletion. **What about accessibility?** Built on React Aria Components for WCAG compliance. Keyboard navigation, focus management, and screen reader support included. **Can I use the styles without React?** Yes, the CSS can be applied to plain HTML. See our [Tailwind Play example](https://play.tailwindcss.com/Ioomj2xdce). **Is there a Figma file?** Yes! Access our design system at [HeroUI Figma Kit V3](https://www.figma.com/community/file/1546526812159103429). ## Get Involved Join the community, share feedback, or contribute: * [GitHub Discussions](https://github.com/heroui-inc/heroui/discussions) * [Discord](https://discord.gg/9b6yyZKmH4) * [X/Twitter](https://x.com/hero_ui) * [Contributing Guidelines](https://github.com/heroui-inc/heroui/blob/main/CONTRIBUTING.md) HeroUI is released under the [MIT License](https://github.com/heroui-inc/heroui/blob/main/LICENSE). # All Releases **Category**: react **URL**: https://v3.heroui.com/docs/react/releases **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/index.mdx > All updates and changes to HeroUI v3, including new features, fixes, and breaking changes. **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server). ## Latest Release ### v3.0.0-beta.3 **December 19, 2025** This release introduces seven new components ([ButtonGroup](/docs/components/button-group), [DateField](/docs/components/date-field), [ErrorMessage](/docs/components/error-message), [ScrollShadow](/docs/components/scroll-shadow), [SearchField](/docs/components/search-field), [TagGroup](/docs/components/tag-group), [TimeField](/docs/components/time-field)), adds `fullWidth` support for form and input components, introduces `hideSeparator` to [Tabs](/docs/components/tabs), [ButtonGroup](/docs/components/button-group), and [Accordion](/docs/components/accordion) for cleaner layouts, includes styling fixes, and ⚠️ **breaking changes** removing the `asChild` prop and updating [AlertDialog](/docs/components/alert-dialog) & [Modal](/docs/components/modal) backdrop variant. [Read full release notes →](/docs/releases/v3-0-0-beta-3) ### v3.0.0-beta.2 **November 20, 2025** This release introduces six essential new components ([AlertDialog](/docs/components/alert-dialog), [ComboBox](/docs/components/combobox), [Dropdown](/docs/components/dropdown), [InputGroup](/docs/components/input-group), [Modal](/docs/components/modal), [NumberField](/docs/components/number-field)), enhances theme compatibility and motion preferences, improves the [Select](/docs/components/select) component API with a ⚠️ **breaking change**, plus various refinements and bug fixes. [Read full release notes →](/docs/releases/v3-0-0-beta-2) ### v3.0.0-beta.1 **November 6, 2025** This release introduces a comprehensive redesign of HeroUI v3, merging v2's beauty and animations with v3's simplicity. All components have been redesigned, 8 new components added ([Alert](/docs/compoenents/alert), [Checkbox](/docs/components/checkbox), [InputOTP](/docs/components/input-otp), [ListBox](/docs/components/listbox), [Select](/docs/components/select), [Slider](/docs/components/slider), [Surface](/docs/components/surface)), and the design system has been completely overhauled with better color tokens, shadows, and architecture. Includes breaking changes to design system variables, component APIs, and flexible component patterns. [Read full release notes →](/docs/releases/v3-0-0-beta-1) ## Previous Releases ### v3.0.0-alpha.35 **October 21, 2025** #### React Server Components Support * Fixed critical issue where compound components didn't work in React Server Components (RSC) * Moved compound pattern logic from components to index files, resolving `"use client"` conflicts * **(⚠️ Breaking change)**: Main component now requires `.Root` suffix (e.g., `` → ``) * Named exports remain unchanged and fully supported #### React 19 Improvements * Removed `forwardRef` (now native in [React 19](https://react.dev/blog/2024/12/05/react-19#ref-as-a-prop)) * Simplified Context usage (`Context.Provider` → [React 19](https://react.dev/blog/2024/12/05/react-19#context-as-a-provider)) #### Switch Component Refactoring * **(⚠️ Breaking change)**: Split Switch and SwitchGroup into separate components * Cleaner API: `` replaces `` and `` * Matches Radio/RadioGroup pattern for consistency * Separate styles, types, and implementations #### Affected Components All compound components now require `.Root` suffix: `Accordion`, `Avatar`, `Card`, `Disclosure`, `Fieldset`, `Kbd`, `Link`, `Popover`, `Radio`, `Switch`, `Tabs`, `Tooltip` [Read full release notes →](/docs/releases/v3-0-0-alpha-35) ### v3.0.0-alpha.34 **October 15, 2025** * Added Form-based components: [Description](/docs/components/description), [FieldError](/docs/components/field-error), [Fieldset](/docs/components/fieldset), [Form](/docs/components/form), [Input](/docs/components/input), [Label](/docs/components/label), [RadioGroup](/docs/components/radio-group), [TextField](/docs/components/text-field), and [TextArea](/docs/components/textarea). * Introduced form field tokens `--field-*` * Reorganized Storybook by category * **(Breaking change)**: Renamed `--skeleton-default-animation-type` to `--skeleton-animation` in [Skeleton](/docs/components/skeleton) * Aligned data-slot markers across components * Improved documentation [Read full release notes →](/docs/releases/v3-0-0-alpha-34) ### v3.0.0-alpha.33 **October 5, 2025** * Upgraded RAC with [October 2, 2025 Release](https://react-spectrum.adobe.com/releases/2025-10-02.html) * Reordered [Tabs](/docs/components/tabs) Indicator (**Breaking change**) * Updated [Tabs](/docs/components/tabs) component to use React Aria's `SelectionIndicator`, now supports SSR * Updated [Disclosure](/docs/components/disclosure) and [Disclosure Group](/docs/components/disclosure-group) components to use RAC CSS variables for the expand and collapse animations * Updated [Switch](/docs/components/switch) component styles and animations * Added `size` variants and added demo in [Switch](/docs/components/switch#sizes) * Added related showcases in [Button](/docs/components/button), [Tabs](/docs/components/tabs), [Disclosure](/docs/components/disclosure), [Disclosure Group](/docs/components/disclosure-group) * Improved documentation [Read full release notes →](/docs/releases/v3-0-0-alpha-33) ### v3.0.0-alpha.32 **October 1, 2025** Card component redesigned with [new variants](/docs/components/card), added [CloseButton](/docs/components/close-button) component, [MCP Server](/docs/ui-for-agents/mcp-server) for AI coding assistants, and improved documentation. [Read full release notes →](/docs/releases/v3-0-0-alpha-32) ### v3.0.0-alpha.31 **September 22, 2025** * 🎨 **Showcases page** - Gallery of sites built with HeroUI * 🌀 **DisclosureGroup component** - Groups multiple disclosures together * 📇 **Card component** (preview) - First version of card component * 🔀 **Switch component** (preview) - Toggle switch for settings ## Release Schedule HeroUI v3 follows a regular release cycle: * **Alpha releases**: Weekly to bi-weekly during active development * **Beta releases**: Monthly stabilization releases - In progress * **Stable releases**: Quarterly major versions (Q4 2025 target) ## Contributing Found an issue or want to contribute? Check out our [GitHub repository](https://github.com/heroui-inc/heroui). # v3.0.0-alpha.32 **Category**: react **URL**: https://v3.heroui.com/docs/react/releases/v3-0-0-alpha-32 **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-alpha-32.mdx > Card component redesign, CloseButton, MCP Server for AI assistants

October 1, 2025

This release adds AI development tools, updates the [Card component](/docs/components/card) API, and improves the developer experience. ## Installation Update to the latest version: ```bash npm i @heroui/styles@alpha @heroui/react@alpha ``` ```bash pnpm add @heroui/styles@alpha @heroui/react@alpha ``` ```bash yarn add @heroui/styles@alpha @heroui/react@alpha ``` ```bash bun add @heroui/styles@alpha @heroui/react@alpha ``` ## What's New ### MCP Server HeroUI now includes an [MCP server](/docs/ui-for-agents/mcp-server) that lets AI assistants like Cursor, Claude Code, and VS Code Copilot access HeroUI v3 documentation and component information directly. **Quick Setup:** ### Cursor

Or manually add to **Cursor Settings** → **Tools** → **MCP Servers**: ```json { "mcpServers": { "heroui-react": { "command": "npx", "args": ["-y", "@heroui/react-mcp@latest"] } } } ``` ### Claude Code Run this command in your terminal: ```bash claude mcp add heroui-react -- npx -y @heroui/react-mcp@latest ``` [Learn more](/docs/ui-for-agents/mcp-server) ### Card Component API Redesign The [Card component](/docs/components/card) has been updated with a new variant system that makes it more flexible. **Breaking Changes:** * Replaced `surface` prop with new `variant` system * Removed `Card.Image`, `Card.Details`, and `Card.CloseButton` (use composition instead) * New variants: `flat`, `outlined`, `elevated`, `filled` **Before:** ```tsx Old Card ``` **After:** ```tsx Card image

New Card ``` **New Features:** * Horizontal layout support * Avatar integration * Background image support * Improved accessibility with semantic HTML [View Card documentation](/docs/components/card) ### CloseButton Component Added a [CloseButton component](/docs/components/close-button) for closing dialogs, modals, and other dismissible elements. ```tsx import {CloseButton} from "@heroui/react"; // Basic usage console.log("Closed")} /> // With custom icon ``` ## Documentation Improvements ### UI for Agents * **[MCP Server documentation](/docs/ui-for-agents/mcp-server)** for development with AI assistants * **[llms.txt](/docs/ui-for-agents/llms-txt)** file for LLM-friendly documentation * Setup guides for popular AI coding tools ### Component Documentation * **[Card](/docs/components/card)**: Rewrote documentation with anatomy, variants, and more examples * **[Switch](/docs/components/switch)**: Added anatomy diagrams and better examples * **[CloseButton](/docs/components/close-button)**: New documentation with usage examples ## Migration Guide ### Card Component Migration 1. **Update variant prop:** * `surface="1"` → `variant="flat"` * `surface="2"` → `variant="outlined"` * `surface="3"` → `variant="elevated"` * `surface="4"` → `variant="filled"` * Custom surfaces → Use new variant system 2. **Update component structure:** * Replace `Card.Image` with `` in `Card.Header` * Replace `Card.Details` with `Card.Body` * Move `Card.CloseButton` to use new `CloseButton` component 3. **Update imports:** ```tsx // Add CloseButton if needed import {Card, CloseButton} from "@heroui/react"; ``` ## Links * [GitHub PR #5747](https://github.com/heroui-inc/heroui/pull/5747) * [MCP Server Documentation](/docs/ui-for-agents/mcp-server) * [Card Component Guide](/docs/components/card) * [CloseButton Component](/docs/components/close-button) ## Contributors Thanks to everyone who contributed to this release! # v3.0.0-alpha.33 **Category**: react **URL**: https://v3.heroui.com/docs/react/releases/v3-0-0-alpha-33 **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-alpha-33.mdx > RAC upgrade, Tabs indicator redesign, Switch size variant, Related showcase

October 5, 2025

This release upgrades React Aria Components, redesigns the Tabs indicator, adds Switch sizes, and includes component showcases. ## Installation Update to the latest version: ```bash npm i @heroui/styles@alpha @heroui/react@alpha ``` ```bash pnpm add @heroui/styles@alpha @heroui/react@alpha ``` ```bash yarn add @heroui/styles@alpha @heroui/react@alpha ``` ```bash bun add @heroui/styles@alpha @heroui/react@alpha ``` ## What's New ### RAC Upgrade Upgraded React Aria Components to the [October 2, 2025 Release](https://react-spectrum.adobe.com/releases/2025-10-02.html). This release includes: * CSS variables for animations * Better SSR support * Performance improvements for selection indicators ### Disclosure and Disclosure Group Updates [Disclosure](/docs/components/disclosure) and [Disclosure Group](/docs/components/disclosure-group) now use React Aria's CSS variables for animations. The components use `--disclosure-panel-width` and `--disclosure-panel-height` variables that track the panel's actual size during expand/collapse. ### Tabs Indicator Redesign [Tabs](/docs/components/tabs) now uses React Aria's `SelectionIndicator` and supports SSR. This fixes layout shifts on initial render. **🚧 Breaking Changes:** * Moved `Tabs.Indicator` inside each `Tabs.Tab` **Before:** ```diff tsx + - ``` ### Switch Updates [Switch](/docs/components/switch) has updated styles and animations. Added `size` prop with options: `sm`, `md`, `lg`. ```tsx import {Label, Switch} from "@heroui/react"; export function Sizes() { return (

Small Medium Large

); } ``` ### Related showcases Related showcases have been added in [Button](/docs/components/button), [Disclosure](/docs/components/disclosure), [Disclosure Group](/docs/components/disclosure-group) and [Tabs](/docs/components/tabs). ## Documentation Improvements ### Component Documentation * **[Tabs](/docs/components/tabs)**: Updated anatomy, revised examples with new indicator design and added related showcase * **[Switch](/docs/components/switch)**: Added size example and revised with-icon example * **[Button](/docs/components/button)**, **[Disclosure](/docs/components/disclosure)**, **[Disclosure Group](/docs/components/disclosure-group)**: Added related showcase ## Migration Guide ### Tabs Component Migration 1. **Update component structure:** * move `` inside each `` ## Links * [GitHub PR #5777](https://github.com/heroui-inc/heroui/pull/5777) * [Tabs Component](/docs/components/tabs) * [Switch Component](/docs/components/switch) * [Button Component](/docs/components/button) * [Disclosure Component](/docs/components/disclosure) * [Disclosure Group Component](/docs/components/disclosure-group) ## Contributors Thanks to everyone who contributed to this release! # v3.0.0-alpha.34 **Category**: react **URL**: https://v3.heroui.com/docs/react/releases/v3-0-0-alpha-34 **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-alpha-34.mdx > Essentials for building forms with a clean API Form, TextField, RadioGroup, Label, Input, Fieldset and more.

October 15, 2025

This release introduces Form-based components, form field tokens, reorganizes Storybook, and aligns data-slot markers across components. ## Installation Update to the latest version: ```bash npm i @heroui/styles@alpha @heroui/react@alpha ``` ```bash pnpm add @heroui/styles@alpha @heroui/react@alpha ``` ```bash yarn add @heroui/styles@alpha @heroui/react@alpha ``` ```bash bun add @heroui/styles@alpha @heroui/react@alpha ``` **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server). ## What's New ### Form-based Components We've introduced a comprehensive set of form-based components built on React Aria Components, providing accessible and composable building blocks for creating forms. These components include [Description](/docs/components/description), [FieldError](/docs/components/field-error), [Fieldset](/docs/components/fieldset), [Form](/docs/components/form), [Input](/docs/components/input), [Label](/docs/components/label), [RadioGroup](/docs/components/radio-group), [TextField](/docs/components/text-field), and [TextArea](/docs/components/textarea). #### Description ```tsx import {Description, Input, Label} from "@heroui/react"; export function Basic() { return (

Email We'll never share your email with anyone else.

); } ``` #### FieldError ```tsx "use client"; import {FieldError, Input, Label, TextField} from "@heroui/react"; import {useState} from "react"; export function Basic() { const [value, setValue] = useState("jr"); const isInvalid = value.length > 0 && value.length < 3; return ( Username setValue(e.target.value)} /> Username must be at least 3 characters ); } ``` #### Fieldset ```tsx "use client"; import {FloppyDisk} from "@gravity-ui/icons"; import { Button, Description, FieldError, FieldGroup, Fieldset, Form, Input, Label, TextArea, TextField, } from "@heroui/react"; export function Basic() { const onSubmit = (e: React.FormEvent) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record = {}; // Convert FormData to plain object formData.forEach((value, key) => { data[key] = value.toString(); }); alert("Form submitted successfully!"); }; return (

Profile Settings Update your profile information. { if (value.length < 3) { return "Name must be at least 3 characters"; } return null; }} > Name Email { if (value.length < 10) { return "Bio must be at least 10 characters"; } return null; }} > Bio

<Description>Minimum 10 characters</Description>
            <FieldError />
          </TextField>
        </FieldGroup>
        <Fieldset.Actions>
          <Button type="submit">
            <FloppyDisk />
            Save changes
          </Button>
          <Button type="reset" variant="secondary">
            Cancel
          </Button>
        </Fieldset.Actions>
      </Fieldset>
    </Form>
  );
}

```

#### Form

```tsx
"use client";

import {Check} from "@gravity-ui/icons";
import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react";

export function Basic() {
  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const data: Record<string, string> = {};

// Convert FormData to plain object
    formData.forEach((value, key) => {
      data[key] = value.toString();
    });

alert(`Form submitted with: ${JSON.stringify(data, null, 2)}`);
  };

return (
    <Form className="flex w-96 flex-col gap-4" onSubmit={onSubmit}>
      <TextField
        isRequired
        name="email"
        type="email"
        validate={(value) => {
          if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(value)) {
            return "Please enter a valid email address";
          }

return null;
        }}
      >
        <Label>Email</Label>
        <Input placeholder="john@example.com" />
        <FieldError />
      </TextField>

<TextField
        isRequired
        minLength={8}
        name="password"
        type="password"
        validate={(value) => {
          if (value.length < 8) {
            return "Password must be at least 8 characters";
          }
          if (!/[A-Z]/.test(value)) {
            return "Password must contain at least one uppercase letter";
          }
          if (!/[0-9]/.test(value)) {
            return "Password must contain at least one number";
          }

return null;
        }}
      >
        <Label>Password</Label>
        <Input placeholder="Enter your password" />
        <Description>Must be at least 8 characters with 1 uppercase and 1 number</Description>
        <FieldError />
      </TextField>

<div className="flex gap-2">
        <Button type="submit">
          <Check />
          Submit
        </Button>
        <Button type="reset" variant="secondary">
          Reset
        </Button>
      </div>
    </Form>
  );
}

```

#### Input

```tsx
import {Input} from "@heroui/react";

export function Basic() {
  return <Input aria-label="Name" className="w-64" placeholder="Enter your name" />;
}

```

#### Label

```tsx
import {Input, Label} from "@heroui/react";

export function Basic() {
  return (
    <div className="flex flex-col gap-1">
      <Label htmlFor="name">Name</Label>
      <Input className="w-64" id="name" placeholder="Enter your name" type="text" />
    </div>
  );
}

```

#### RadioGroup

```tsx
import {Description, Label, Radio, RadioGroup} from "@heroui/react";

export function Basic() {
  return (
    <RadioGroup defaultValue="premium" name="plan">
      <Label>Plan selection</Label>
      <Description>Choose the plan that suits you best</Description>
      <Radio value="basic">
        <Radio.Control>
          <Radio.Indicator />
        </Radio.Control>
        <Radio.Content>
          <Label>Basic Plan</Label>
          <Description>Includes 100 messages per month</Description>
        </Radio.Content>
      </Radio>
      <Radio value="premium">
        <Radio.Control>
          <Radio.Indicator />
        </Radio.Control>
        <Radio.Content>
          <Label>Premium Plan</Label>
          <Description>Includes 200 messages per month</Description>
        </Radio.Content>
      </Radio>
      <Radio value="business">
        <Radio.Control>
          <Radio.Indicator />
        </Radio.Control>
        <Radio.Content>
          <Label>Business Plan</Label>
          <Description>Unlimited messages</Description>
        </Radio.Content>
      </Radio>
    </RadioGroup>
  );
}

```

#### TextField

```tsx
import {Input, Label, TextField} from "@heroui/react";

export function Basic() {
  return (
    <TextField className="w-full max-w-64" name="email" type="email">
      <Label>Email</Label>
      <Input placeholder="Enter your email" />
    </TextField>
  );
}

```

#### TextArea

```tsx
import {TextArea} from "@heroui/react";

export function Basic() {
  return (
    <TextArea
      aria-label="Quick project update"
      className="h-32 w-96"
      placeholder="Share a quick project update..."
    />
  );
}

```

### Form Field Tokens

Introduced form field tokens `--field-*` for consistent styling across form components. See [Theming](/docs/handbook/theming#calculated-variables-tailwind) for the `--field-*` variables.

### Storybook Organization

Reorganized Storybook by category for better navigation and component discovery.

### Skeleton Animation Token

**🚧 Breaking Changes:** Renamed `--skeleton-default-animation-type` to `--skeleton-animation` in [Skeleton](/docs/components/skeleton) for consistency with other component tokens.

### Data-Slot Alignment

Aligned data-slot markers across components for consistent styling and customization. This standardization makes it easier to target specific component parts with CSS selectors and improves the overall developer experience when customizing component styles.

Components now use consistent `data-slot` attributes like:

* `data-slot="base"` for the root element
* `data-slot="label"` for label text
* `data-slot="description"` for description text
* `data-slot="error"` for error messages

This allows for predictable CSS targeting across all form components:

```css
.radio {
  [data-slot="label"] {
    /* Styles apply to radio labels */
  }
}
```

## Documentation Improvements

### Component Documentation

* **[Link](/docs/components/link)**: Added Anatomy, and examples with Icon. Updated Link and Link.Icon props section.
* **[Description](/docs/components/description)**, **[FieldError](/docs/components/field-error)**, **[Fieldset](/docs/components/fieldset)**, **[Form](/docs/components/form)**, **[Input](/docs/components/input)**, **[Label](/docs/components/label)**, **[RadioGroup](/docs/components/radio-group)**, **[TextField](/docs/components/text-field)**, and **[TextArea](/docs/components/textarea)**: New documentation with usage examples

## Migration Guide

### Skeleton Component Migration

1. **Update animation token:**
   * Replace `--skeleton-default-animation-type` with `--skeleton-animation`

## Links

* [GitHub PR #5780](https://github.com/heroui-inc/heroui/pull/5780)
* [Description Component](/docs/components/description)
* [FieldError Component](/docs/components/field-error)
* [Fieldset Component](/docs/components/fieldset)
* [Form Component](/docs/components/form)
* [Input Component](/docs/components/input)
* [Label Component](/docs/components/label)
* [RadioGroup Component](/docs/components/radio-group)
* [TextField Component](/docs/components/text-field)
* [TextArea Component](/docs/components/textarea)
* [Skeleton Component](/docs/components/skeleton)

## Contributors

Thanks to everyone who contributed to this release!

</page>

<page url="/docs/react/releases/v3-0-0-alpha-35">
# v3.0.0-alpha.35

**Category**: react
**URL**: https://v3.heroui.com/docs/react/releases/v3-0-0-alpha-35
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-alpha-35.mdx
> React Server Components support for compound components, React 19 improvements, and critical bug fixes.

<div className="flex items-center gap-3 mb-6">
  <span className="text-sm text-muted">October 21, 2025</span>
</div>

This release fixes a critical issue where **compound components didn't work correctly in React Server Components (RSC)**. Additionally, this release adopts React 19 best practices by removing `forwardRef` and simplifying context usage. The Switch component has been refactored to match the Radio/RadioGroup pattern, providing a cleaner and more consistent API.

## Installation

Update to the latest version:

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    ```bash
    npm i @heroui/styles@alpha @heroui/react@alpha
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm add @heroui/styles@alpha @heroui/react@alpha
    ```
  </Tab>

<Tab value="yarn">
    ```bash
    yarn add @heroui/styles@alpha @heroui/react@alpha
    ```
  </Tab>

<Tab value="bun">
    ```bash
    bun add @heroui/styles@alpha @heroui/react@alpha
    ```
  </Tab>
</Tabs>

<Callout type="info">
  **Using AI assistants?** Simply prompt "Hey Cursor, update HeroUI to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the [HeroUI MCP Server](/docs/ui-for-agents/mcp-server).
</Callout>

## What's New

### React Server Components Support

Compound components now work correctly in React Server Components. The previous implementation had the compound pattern logic inside components, which conflicted with the `"use client"` directive. This has been fixed by moving the pattern logic to component index files.

### React 19 Improvements

This release adopts React 19 best practices:

1. **Removed `forwardRef`**: No longer needed in React 19, where `ref` is now a prop ([React 19 docs](https://react.dev/blog/2024/12/05/react-19#ref-as-a-prop))
2. **Simplified Context**: `Context.Provider` replaced with just `Context` ([React 19 docs](https://react.dev/blog/2024/12/05/react-19#context-as-a-provider))

### Switch Component Architecture Improvement

The Switch component has been refactored to follow the same clean separation pattern as Radio/RadioGroup:

* **Separate Components**: Switch and SwitchGroup are now independent components (previously combined)
* **Cleaner API**: `<SwitchGroup>` replaces the nested `<Switch.Group>` and `<Switch.GroupItems>` pattern
* **Better Organization**: Separate styles, types, and implementations for each component
* **Consistent Pattern**: Matches the Radio/RadioGroup architecture for a more predictable API

**Before:**

```tsx
<Switch.Group>
  <Switch.GroupItems>
    <Switch.Root>...</Switch.Root>
  </Switch.GroupItems>
</Switch.Group>

```

**After:**

```tsx
<SwitchGroup>
  <Switch.Root>...</Switch.Root>
  <Switch.Root>...</Switch.Root>
</SwitchGroup>

```

## ⚠️ Breaking Changes

### Main Component Requires `.Root` Suffix

To support React Server Components, the compound component pattern has been restructured. The main component now requires the `.Root` suffix when using the compound pattern.

**Before:**

```tsx
import { Avatar } from "@heroui/react"

```

**After:**

```tsx
import { Avatar } from "@heroui/react"

<Avatar.Root>
  <Avatar.Image src="/images/avatar.jpeg" alt="Junior Garcia" />
  <Avatar.Fallback>JR</Avatar.Fallback>
</Avatar.Root>

```

**Note:** Named exports (e.g., `<Avatar>`, `<AvatarImage>`, `<AvatarFallback>`) remain unchanged and fully supported.

### Switch Component API Changes

The Switch component grouping API has been restructured to match the Radio/RadioGroup pattern:

**Before:**

```tsx
import { Switch } from "@heroui/react"

<Switch.Group orientation="horizontal">
  <Switch.GroupItems>
    <Switch.Root name="notifications">
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      <Label>Notifications</Label>
    </Switch.Root>
    <Switch.Root name="marketing">
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      <Label>Marketing</Label>
    </Switch.Root>
  </Switch.GroupItems>
</Switch.Group>

```

**After:**

```tsx
import { Switch, SwitchGroup } from "@heroui/react"

<SwitchGroup orientation="horizontal">
  <Switch.Root name="notifications">
    <Switch.Control>
      <Switch.Thumb />
    </Switch.Control>
    <Label>Notifications</Label>
  </Switch.Root>
  <Switch.Root name="marketing">
    <Switch.Control>
      <Switch.Thumb />
    </Switch.Control>
    <Label>Marketing</Label>
  </Switch.Root>
</SwitchGroup>

```

This change helps to:

**Migration Steps:**

1. Import `SwitchGroup` separately: `import { Switch, SwitchGroup } from "@heroui/react"`
2. Replace `<Switch.Group>` with `<SwitchGroup>`
3. Remove the nested `<Switch.GroupItems>` wrapper
4. Individual `Switch.Root` components remain unchanged

#### Affected Components

All compound components are affected:

* `Accordion` → `Accordion.Root`
* `Avatar` → `Avatar.Root`
* `Card` → `Card.Root`
* `Disclosure` → `Disclosure.Root`
* `Fieldset` → `Fieldset.Root`
* `Kbd` → `Kbd.Root`
* `Link` → `Link.Root`
* `Popover` → `Popover.Root`
* `RadioGroup` → `RadioGroup.Root`
* `Switch` → `Switch.Root`
* `Tabs` → `Tabs.Root`
* `Tooltip` → `Tooltip.Root`

## Migration Guide

You have two options for using HeroUI compound components:

### Option 1: Update to Use `.Root` (Compound Pattern)

If you're using the compound pattern (dot notation), update your code to use `.Root` for the main component:

**Card Example:**

```tsx
import { Card } from "@heroui/react"

<Card.Root>
  <Card.Header>
    <Card.Title>Card Title</Card.Title>
    <Card.Description>Card description</Card.Description>
  </Card.Header>
  <Card.Content>
    Card content
  </Card.Content>
  <Card.Footer>
    Card footer
  </Card.Footer>
</Card.Root>

```

**Tabs Example:**

```tsx
import { Tabs } from "@heroui/react"

<Tabs.Root>
  <Tabs.ListWrapper>
    <Tabs.List>
      <Tabs.Tab id="tab1">Tab 1<Tabs.Indicator /></Tabs.Tab>
      <Tabs.Tab id="tab2">Tab 2<Tabs.Indicator /></Tabs.Tab>
    </Tabs.List>
  </Tabs.ListWrapper>
  <Tabs.Panel id="tab1">Panel 1</Tabs.Panel>
  <Tabs.Panel id="tab2">Panel 2</Tabs.Panel>
</Tabs.Root>

```

[See more examples in the documentation](/docs/components/card)

**Avatar Example:**

```tsx
import { Avatar } from "@heroui/react"

<Avatar.Root>
  <Avatar.Image alt="John Doe" src="..." />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>

```

[See more examples in the documentation](/docs/components/avatar)

### Option 2: Use Named Exports

We added support for named exports for all compound components. You can use them like this:

**Card Example:**

```tsx
import {
  CardRoot,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
} from "@heroui/react"

<CardRoot>
  <CardHeader>
    <CardTitle>Card Title</CardTitle>
    <CardDescription>Card description</CardDescription>
  </CardHeader>
  <CardContent>
    Card content
  </CardContent>
  <CardFooter>
    Card footer
  </CardFooter>
</CardRoot>

```

**Tabs Example:**

```tsx
import { TabsRoot, TabListContainer, TabList, Tab, TabIndicator, TabPanel } from "@heroui/react"

<TabsRoot>
  <TabListContainer>
    <TabList>
      <Tab id="tab1">Tab 1<TabIndicator /></Tab>
      <Tab id="tab2">Tab 2<TabIndicator /></Tab>
    </TabList>
  </TabListContainer>
  <TabPanel id="tab1">Panel 1</TabPanel>
  <TabPanel id="tab2">Panel 2</TabPanel>
</TabsRoot>

```

**Avatar Example:**

```tsx
import { Avatar, AvatarImage, AvatarFallback } from "@heroui/react"

```

### Migration Steps

If you're using the compound pattern, you only need to update the main component to use `.Root`:

1. **Find all instances of compound components** (e.g., `<Avatar>` with `<Avatar.Image>` inside)

2. **Add `.Root` to the main component**:
   ```tsx
   // Before
   <Avatar>
     <Avatar.Image ... />
   </Avatar>

// After
   <Avatar.Root>
     <Avatar.Image ... />
   </Avatar.Root>
   ```

3. **That's it!** All child components (e.g., `Avatar.Image`, `Avatar.Fallback`) remain unchanged.

### Complete Migration Reference

| Component      | Named Export Pattern            | Compound Pattern (with `.Root`)       | Additional Changes                                      |
| -------------- | ------------------------------- | ------------------------------------- | ------------------------------------------------------- |
| **Accordion**  | `<Accordion>`                   | `<Accordion.Root>`                    | -                                                       |
| **Avatar**     | `<Avatar>`                      | `<Avatar.Root>`                       | -                                                       |
| **Card**       | `<Card>`                        | `<Card.Root>`                         | -                                                       |
| **Disclosure** | `<Disclosure>`                  | `<Disclosure.Root>`                   | -                                                       |
| **Fieldset**   | `<Fieldset>`                    | `<Fieldset.Root>`                     | -                                                       |
| **Kbd**        | `<Kbd>`                         | `<Kbd.Root>`                          | -                                                       |
| **Link**       | `<Link>`                        | `<Link.Root>`                         | -                                                       |
| **Popover**    | `<Popover>`                     | `<Popover.Root>`                      | -                                                       |
| **Radio**      | `<Radio>`                       | `<Radio.Root>`                        | -                                                       |
| **Switch**     | `<Switch>`, `<SwitchControl>`   | `<Switch.Root>`, `<Switch.Control>`   | `<Switch.Group>` → `<SwitchGroup>` (separate component) |
| **Tabs**       | `<Tabs>`, `<TabList>`           | `<Tabs.Root>`, `<Tabs.List>`          | -                                                       |
| **Tooltip**    | `<Tooltip>`, `<TooltipTrigger>` | `<Tooltip.Root>`, `<Tooltip.Trigger>` | -                                                       |

### Automated Migration

For large codebases using the compound pattern, you can use find-and-replace:

```bash
# Example for Avatar component
# Update the main component to use .Root
sed -i 's/<Avatar>/<Avatar.Root>/g' **/*.tsx
sed -i 's/<\/Avatar>/<\/Avatar.Root>/g' **/*.tsx

# Switch component requires additional steps
# First, ensure SwitchGroup is imported
# Then replace Switch.Group with SwitchGroup
sed -i 's/<Switch\.Group/<SwitchGroup/g' **/*.tsx
sed -i 's/<\/Switch\.Group>/<\/SwitchGroup>/g' **/*.tsx

# Remove Switch.GroupItems wrapper
sed -i 's/<Switch\.GroupItems>//g' **/*.tsx
sed -i 's/<\/Switch\.GroupItems>//g' **/*.tsx

# Repeat for other compound components (Card, Tabs, etc.)
# Note: This only affects files using the compound pattern

```

**Important:**

* Be careful with automated replacements. Make sure you're only replacing compound pattern usage, not named exports.
* For Switch migrations, verify that `SwitchGroup` is imported: `import { Switch, SwitchGroup } from "@heroui/react"`
* Test your code after running automated migrations to ensure all changes are correct.

## Why This Change?

This change was necessary to fix React Server Components compatibility. The previous implementation had architectural limitations:

1. **RSC Compatibility**: Compound pattern logic conflicted with `"use client"` directives
2. **React 19 Readiness**: Removes deprecated patterns like `forwardRef` and `Context.Provider`
3. **Cleaner Architecture**: Pattern logic is now in index files, not component files
4. **Better Separation**: Server and client components can now work together seamlessly

## Documentation Updates

Component documentation will be updated to reflect the new patterns:

* Examples will show the compound pattern with `.Root`
* Named export examples remain valid and supported
* Migration guides will help you transition smoothly
* Both patterns are fully supported and work identically

## Need Help?

If you encounter any issues during migration:

1. **Compound pattern users**: Update the main component to use `.Root` (e.g., `<Avatar>` → `<Avatar.Root>`)
2. **Named export users**: No changes needed - your code continues to work as-is
3. Check the component documentation for examples
4. Report issues at: [GitHub Issues](https://github.com/heroui-inc/heroui/issues)

## Links

* [Component Documentation](https://heroui.com/docs/components)
* [React Server Components](https://react.dev/reference/rsc/server-components)
* [React 19 Release](https://react.dev/blog/2024/12/05/react-19)
* [GitHub Repository](https://github.com/heroui-inc/heroui)

## Contributors

Thanks to everyone who contributed to this release, improving React Server Components support and React 19 compatibility!

</page>

<page url="/docs/react/releases/v3-0-0-beta-1">
# v3.0.0-beta.1

**Category**: react
**URL**: https://v3.heroui.com/docs/react/releases/v3-0-0-beta-1
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-beta-1.mdx
> Major redesign with new design system, 8 new components, and improved developer experience.

<div className="flex items-center gap-3 mb-6">
  <span className="text-sm text-muted">November 6, 2025</span>
</div>

This release introduces a comprehensive redesign of HeroUI v3, merging v2's beauty and animations with v3's simplicity. All components redesigned, 8 new components, and improved design system with better color tokens, shadows, and architecture.

## Installation

Update to the latest version:

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    ```bash
    npm i @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm add @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>

<Tab value="yarn">
    ```bash
    yarn add @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>

<Tab value="bun">
    ```bash
    bun add @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>
</Tabs>

## What's New

### New Design System

We've spent weeks crafting a new design system that merges the soul of HeroUI v2 with the simplicity of v3. Every component has been redesigned with attention to detail, smooth animations, and improved developer experience. The new design system is available in our [Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3).

The redesign brings:

* New color system that brings v3's vision to life and stands out for its uniqueness
* Refined shadow system for better depth perception
* New variables and tokens for better customization
* Automatic `isOnSurface` support for form-based components
* Enhanced border and spacing tokens
* Better contrast and accessibility
* Consistent component patterns across web and native

### New Components

This release introduces **8 new** essential components:

* **[Alert](#alert)**: Display important messages and notifications with status indicators.
* **[Checkbox & CheckboxGroup](#checkbox-checkboxgroup)**: Select multiple items from a list.
* **[InputOTP](#inputotp)**: One-time password input for authentication flows.
* **[Listbox](#listbox)**: Display a list of options and allow single or multiple selection.
* **[Select](#select)**: Dropdown selection component built on top of Listbox.
* **[Slider](#slider)**: Select a value from a range with custom marks and labels.
* **[Surface](#surface)**: Base surface component for creating elevated containers.

### Alert

```tsx
import {Alert, Button, CloseButton, Spinner} from "@heroui/react";
import React from "react";

export function Basic() {
  return (
    <div className="grid w-full max-w-xl gap-4">
      {/* Default - General information */}
      <Alert>
        <Alert.Indicator />
        <Alert.Content>
          <Alert.Title>New features available</Alert.Title>
          <Alert.Description>
            Check out our latest updates including dark mode support and improved accessibility
            features.
          </Alert.Description>
        </Alert.Content>
      </Alert>

{/* Accent - Important information with action */}
      <Alert status="accent">
        <Alert.Indicator />
        <Alert.Content>
          <Alert.Title>Update available</Alert.Title>
          <Alert.Description>
            A new version of the application is available. Please refresh to get the latest features
            and bug fixes.
          </Alert.Description>
          <Button className="mt-2 sm:hidden" size="sm" variant="primary">
            Refresh
          </Button>
        </Alert.Content>
        <Button className="hidden sm:block" size="sm" variant="primary">
          Refresh
        </Button>
      </Alert>

{/* Danger - Error with detailed steps */}
      <Alert status="danger">
        <Alert.Indicator />
        <Alert.Content>
          <Alert.Title>Unable to connect to server</Alert.Title>
          <Alert.Description>
            We're experiencing connection issues. Please try the following:
            <ul className="mt-2 list-inside list-disc space-y-1 text-sm">
              <li>Check your internet connection</li>
              <li>Refresh the page</li>
              <li>Clear your browser cache</li>
            </ul>
          </Alert.Description>
          <Button className="mt-2 sm:hidden" size="sm" variant="danger">
            Retry
          </Button>
        </Alert.Content>
        <Button className="hidden sm:block" size="sm" variant="danger">
          Retry
        </Button>
      </Alert>

{/* Without description */}
      <Alert status="success">
        <Alert.Indicator />
        <Alert.Content>
          <Alert.Title>Profile updated successfully</Alert.Title>
        </Alert.Content>
        <CloseButton />
      </Alert>

{/* Custom indicator - Loading state */}
      <Alert status="accent">
        <Alert.Indicator>
          <Spinner size="sm" />
        </Alert.Indicator>
        <Alert.Content>
          <Alert.Title>Processing your request</Alert.Title>
          <Alert.Description>
            Please wait while we sync your data. This may take a few moments.
          </Alert.Description>
        </Alert.Content>
      </Alert>

{/* Without close button */}
      <Alert status="warning">
        <Alert.Indicator />
        <Alert.Content>
          <Alert.Title>Scheduled maintenance</Alert.Title>
          <Alert.Description>
            Our services will be unavailable on Sunday, March 15th from 2:00 AM to 6:00 AM UTC for
            scheduled maintenance.
          </Alert.Description>
        </Alert.Content>
      </Alert>
    </div>
  );
}

```

### Checkbox & CheckboxGroup

```tsx
import {Checkbox, Label} from "@heroui/react";

export function Basic() {
  return (
    <div className="flex items-center gap-3">
      <Checkbox id="basic-terms">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
      </Checkbox>
      <Label htmlFor="basic-terms">Accept terms and conditions</Label>
    </div>
  );
}

```

```tsx
import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";

export function Basic() {
  return (
    <CheckboxGroup name="interests">
      <Label>Select your interests</Label>
      <Description>Choose all that apply</Description>
      <Checkbox value="coding">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Coding</Label>
          <Description>Love building software</Description>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="design">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Design</Label>
          <Description>Enjoy creating beautiful interfaces</Description>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="writing">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Writing</Label>
          <Description>Passionate about content creation</Description>
        </Checkbox.Content>
      </Checkbox>
    </CheckboxGroup>
  );
}

```

### InputOTP

```tsx
import {InputOTP, Label, Link} from "@heroui/react";

export function Basic() {
  return (
    <div className="flex w-[280px] flex-col gap-2">
      <div className="flex flex-col gap-1">
        <Label>Verify account</Label>
        <p className="text-sm text-muted">We've sent a code to a****@gmail.com</p>
      </div>
      <InputOTP maxLength={6}>
        <InputOTP.Group>
          <InputOTP.Slot index={0} />
          <InputOTP.Slot index={1} />
          <InputOTP.Slot index={2} />
        </InputOTP.Group>
        <InputOTP.Separator />
        <InputOTP.Group>
          <InputOTP.Slot index={3} />
          <InputOTP.Slot index={4} />
          <InputOTP.Slot index={5} />
        </InputOTP.Group>
      </InputOTP>
      <div className="flex items-center gap-[5px] px-1 pt-1">
        <p className="text-sm text-muted">Didn't receive a code?</p>
        <Link className="text-foreground" underline="always">
          Resend
        </Link>
      </div>
    </div>
  );
}

```

### Listbox

```tsx
import {Avatar, Description, Label, ListBox} from "@heroui/react";

export function Default() {
  return (
    <ListBox aria-label="Users" className="w-[220px]" selectionMode="single">
      <ListBox.Item id="1" textValue="Bob">
        <Avatar size="sm">
          <Avatar.Image
            alt="Bob"
            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
          />
          <Avatar.Fallback>B</Avatar.Fallback>
        </Avatar>
        <div className="flex flex-col">
          <Label>Bob</Label>
          <Description>bob@heroui.com</Description>
        </div>
        <ListBox.ItemIndicator />
      </ListBox.Item>
      <ListBox.Item id="2" textValue="Fred">
        <Avatar size="sm">
          <Avatar.Image
            alt="Fred"
            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
          />
          <Avatar.Fallback>F</Avatar.Fallback>
        </Avatar>
        <div className="flex flex-col">
          <Label>Fred</Label>
          <Description>fred@heroui.com</Description>
        </div>
        <ListBox.ItemIndicator />
      </ListBox.Item>
      <ListBox.Item id="3" textValue="Martha">
        <Avatar size="sm">
          <Avatar.Image
            alt="Martha"
            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
          />
          <Avatar.Fallback>M</Avatar.Fallback>
        </Avatar>
        <div className="flex flex-col">
          <Label>Martha</Label>
          <Description>martha@heroui.com</Description>
        </div>
        <ListBox.ItemIndicator />
      </ListBox.Item>
    </ListBox>
  );
}

```

### Select

```tsx
import {Label, ListBox, Select} from "@heroui/react";

export function Default() {
  return (
    <Select className="w-[256px]" placeholder="Select one">
      <Label>State</Label>
      <Select.Trigger>
        <Select.Value />
        <Select.Indicator />
      </Select.Trigger>
      <Select.Popover>
        <ListBox>
          <ListBox.Item id="florida" textValue="Florida">
            Florida
            <ListBox.ItemIndicator />
          </ListBox.Item>
          <ListBox.Item id="delaware" textValue="Delaware">
            Delaware
            <ListBox.ItemIndicator />
          </ListBox.Item>
          <ListBox.Item id="california" textValue="California">
            California
            <ListBox.ItemIndicator />
          </ListBox.Item>
          <ListBox.Item id="texas" textValue="Texas">
            Texas
            <ListBox.ItemIndicator />
          </ListBox.Item>
          <ListBox.Item id="new-york" textValue="New York">
            New York
            <ListBox.ItemIndicator />
          </ListBox.Item>
          <ListBox.Item id="washington" textValue="Washington">
            Washington
            <ListBox.ItemIndicator />
          </ListBox.Item>
        </ListBox>
      </Select.Popover>
    </Select>
  );
}

```

### Slider

```tsx
import {Label, Slider} from "@heroui/react";

export function Default() {
  return (
    <Slider className="w-full max-w-xs" defaultValue={30}>
      <Label>Volume</Label>
      <Slider.Output />
      <Slider.Track>
        <Slider.Fill />
        <Slider.Thumb />
      </Slider.Track>
    </Slider>
  );
}

```

### Surface

```tsx
import {Surface} from "@heroui/react";

export function Variants() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex flex-col gap-2">
        <p className="text-sm font-medium text-muted">Default</p>
        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default">
          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
          <p className="text-sm text-muted">
            This is a default surface variant. It uses bg-surface styling.
          </p>
        </Surface>
      </div>

<div className="flex flex-col gap-2">
        <p className="text-sm font-medium text-muted">Secondary</p>
        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="secondary">
          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
          <p className="text-sm text-muted">
            This is a secondary surface variant. It uses bg-surface-secondary styling.
          </p>
        </Surface>
      </div>

<div className="flex flex-col gap-2">
        <p className="text-sm font-medium text-muted">Tertiary</p>
        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="tertiary">
          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
          <p className="text-sm text-muted">
            This is a tertiary surface variant. It uses bg-surface-tertiary styling.
          </p>
        </Surface>
      </div>

<div className="flex flex-col gap-2">
        <p className="text-sm font-medium text-muted">Quaternary</p>
        <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="quaternary">
          <h3 className="text-base font-semibold text-foreground">Surface Content</h3>
          <p className="text-sm text-muted">
            This is a quaternary surface variant. It uses bg-surface-quaternary styling.
          </p>
        </Surface>
      </div>
    </div>
  );
}

```

### Improved Component APIs

Several components have been refined with better APIs:

* **Link**: Added `underline` and `underlineOffset` props for better customization

```tsx
import {Link} from "@heroui/react";

export function LinkBasic() {
  return (
    <Link href="#">
      Call to action
      <Link.Icon />
    </Link>
  );
}

```

* **Card**: Improved variants and styling system

```tsx
import {CircleDollar} from "@gravity-ui/icons";
import {Avatar, Button, Card, CloseButton, Link} from "@heroui/react";

export function WithImages() {
  return (
    <div className="flex w-full items-center justify-center">
      <div className="grid w-full max-w-2xl grid-cols-12 gap-4 p-4">
        {/* Row 1: Large Product Card - Available Soon */}
        <Card className="col-span-12 flex h-auto min-h-[152px] flex-col sm:flex-row">
          <div className="relative h-[140px] w-full shrink-0 overflow-hidden rounded-2xl sm:h-[120px] sm:w-[120px]">
            <img
              alt="Cherries"
              className="pointer-events-none absolute inset-0 h-full w-full scale-125 object-cover select-none"
              loading="lazy"
              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cherries.jpeg"
            />
          </div>
          <div className="flex flex-1 flex-col gap-3">
            <Card.Header className="gap-1">
              <Card.Title className="pr-8">Become an ACME Creator!</Card.Title>
              <Card.Description>
                Lorem ipsum dolor sit amet consectetur. Sed arcu donec id aliquam dolor sed amet
                faucibus etiam.
              </Card.Description>
              <CloseButton aria-label="Close banner" className="absolute top-3 right-3" />
            </Card.Header>
            <Card.Footer className="mt-auto flex w-full flex-col items-start gap-3 sm:flex-row sm:items-center sm:justify-between">
              <div className="flex flex-col">
                <span className="text-sm font-medium text-foreground">Only 10 spots</span>
                <span className="text-xs text-muted">Submission ends Oct 10.</span>
              </div>
              <Button className="w-full sm:w-auto">Apply Now</Button>
            </Card.Footer>
          </div>
        </Card>

{/* Row 2 */}
        <div className="col-span-12 grid grid-cols-12 gap-4">
          {/* Left Column */}
          <div className="col-span-12 grid grid-cols-12 gap-4 lg:col-span-6">
            {/* Top Card */}
            <Card className="col-span-12">
              <div className="absolute top-3 right-3 z-10">
                <CloseButton aria-label="Close notification" />
              </div>
              <Card.Header className="gap-3">
                <CircleDollar
                  aria-label="Dollar sign icon"
                  className="text-primary size-8 shrink-0"
                  role="img"
                />
                <div className="flex flex-col gap-1">
                  <span className="text-xs font-medium text-muted uppercase">PAYMENT</span>
                  <Card.Title className="pr-8 text-sm sm:text-base">
                    You can now withdraw on crypto
                  </Card.Title>
                  <Card.Description className="text-xs sm:text-sm">
                    Add your wallet in settings to withdraw
                  </Card.Description>
                </div>
              </Card.Header>
              <Card.Footer>
                <Link aria-label="Go to settings" href="#" rel="noopener noreferrer">
                  Go to settings
                  <Link.Icon aria-hidden="true" />
                </Link>
              </Card.Footer>
            </Card>
            {/* Bottom cards */}
            <div className="col-span-12 grid grid-cols-12 gap-4">
              {/* Left Card */}
              <Card className="col-span-12 gap-2 sm:col-span-6">
                <Card.Header>
                  <Avatar className="size-[56px] rounded-xl">
                    <Avatar.Image
                      alt="Demo 1"
                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg"
                    />
                    <Avatar.Fallback>JK</Avatar.Fallback>
                  </Avatar>
                </Card.Header>
                <Card.Content className="mt-1">
                  <p className="text-sm leading-4 font-medium">Indie Hackers</p>
                  <p className="text-xs text-muted">148 members</p>
                </Card.Content>
                <Card.Footer className="flex items-center gap-2">
                  <Avatar className="size-4">
                    <Avatar.Image
                      alt="John"
                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg"
                    />
                    <Avatar.Fallback>JK</Avatar.Fallback>
                  </Avatar>
                  <p className="text-xs text-muted">By John</p>
                </Card.Footer>
              </Card>
              {/* Right Card */}
              <Card className="col-span-12 gap-2 sm:col-span-6">
                <Card.Header>
                  <Avatar className="size-[56px] rounded-xl">
                    <Avatar.Image
                      alt="Demo 2"
                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg"
                    />
                    <Avatar.Fallback>AB</Avatar.Fallback>
                  </Avatar>
                </Card.Header>
                <Card.Content className="mt-1">
                  <p className="text-sm leading-4 font-medium">AI Builders</p>
                  <p className="text-xs text-muted">362 members</p>
                </Card.Content>
                <Card.Footer className="flex items-center gap-2">
                  <Avatar className="size-4">
                    <Avatar.Image
                      alt="John"
                      src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
                    />
                    <Avatar.Fallback>M</Avatar.Fallback>
                  </Avatar>
                  <p className="text-xs text-muted">By Martha</p>
                </Card.Footer>
              </Card>
            </div>
          </div>
          {/* Right Column */}
          <Card className="col-span-12 min-h-[200px] overflow-hidden rounded-3xl lg:col-span-6">
            {/* Background image */}
            <img
              alt="NEO Home Robot"
              aria-hidden="true"
              className="absolute inset-0 h-full w-full object-cover"
              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo2.jpeg"
            />

{/* Header */}
            <Card.Header className="z-10 text-white">
              <Card.Title className="text-xs font-semibold tracking-wide text-black/70">
                NEO
              </Card.Title>
              <Card.Description className="text-sm leading-5 font-medium text-black/50">
                Home Robot
              </Card.Description>
            </Card.Header>

{/* Footer */}
            <Card.Footer className="z-10 mt-auto flex items-center justify-between">
              <div>
                <div className="text-sm font-medium text-black">Available soon</div>
                <div className="text-xs text-black/60">Get notified</div>
              </div>
              <Button className="bg-white text-black" size="sm" variant="tertiary">
                Notify me
              </Button>
            </Card.Footer>
          </Card>
        </div>

{/* Row 3 */}
        <div className="col-span-12 grid grid-cols-12 gap-4">
          {/* Left Column: Card */}
          <Card className="relative col-span-12 h-[250px] sm:h-[300px] md:col-span-8 md:h-[350px]">
            <img
              alt="NEO Home Robot"
              aria-hidden="true"
              className="absolute inset-0 h-full w-full object-cover"
              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo1.jpeg"
            />

<Card.Footer className="z-10 mt-auto flex items-end justify-between">
              <div>
                <div className="text-base font-medium text-black sm:text-lg">NEO</div>
                <div className="text-xs font-medium text-black/50 sm:text-sm">$499/m</div>
              </div>
              <Button className="bg-white text-black" size="sm" variant="tertiary">
                Get now
              </Button>
            </Card.Footer>
          </Card>

{/* Right Column: Cards Stack */}
          <div className="col-span-12 flex flex-col gap-2 md:col-span-4 md:justify-between md:gap-0 md:py-2">
            {/* 1 */}
            <Card className="flex flex-row gap-3 p-1" variant="transparent">
              <img
                alt="Futuristic Robot"
                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
                loading="lazy"
                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg"
              />
              <div className="flex flex-1 flex-col justify-center gap-1">
                <Card.Title className="text-sm">Bridging the Future</Card.Title>
                <Card.Description className="text-xs">Today, 6:30 PM</Card.Description>
              </div>
            </Card>
            {/* 2 */}
            <Card className="flex flex-row gap-3 p-1" variant="transparent">
              <img
                alt="Avocado"
                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
                loading="lazy"
                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg"
              />
              <div className="flex flex-1 flex-col justify-center gap-1">
                <Card.Title className="text-sm">Avocado Hackathon</Card.Title>
                <Card.Description className="text-xs">Wed, 4:30 PM</Card.Description>
              </div>
            </Card>
            {/* 3 */}
            <Card className="flex flex-row gap-3 p-1" variant="transparent">
              <img
                alt="Sound Electro event"
                className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
                loading="lazy"
                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg"
              />
              <div className="flex flex-1 flex-col justify-center gap-1">
                <Card.Title className="text-sm">Sound Electro | Beyond art</Card.Title>
                <Card.Description className="text-xs">Fri, 8:00 PM</Card.Description>
              </div>
            </Card>
          </div>
        </div>
      </div>
    </div>
  );
}

```

* **Chip**: Enhanced with size variants and improved color system

```tsx
import {Chip} from "@heroui/react";

export function ChipBasic() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Chip>Default</Chip>
      <Chip color="accent">Accent</Chip>
      <Chip color="success">Success</Chip>
      <Chip color="warning">Warning</Chip>
      <Chip color="danger">Danger</Chip>
    </div>
  );
}

```

* **Switch**: Redesigned from the ground up with improved visual design and animations

```tsx
import {Label, Switch} from "@heroui/react";

export function Basic() {
  return (
    <Switch>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      <Label className="text-sm">Enable notifications</Label>
    </Switch>
  );
}

```

* **RadioGroup**: Redesigned from the ground up with better API and styling

```tsx
import {Description, Label, Radio, RadioGroup} from "@heroui/react";

```

### Flexible Component Patterns

HeroUI now supports flexible component syntax. Use compound patterns with or without `.Root`, or named exports - all three patterns work identically.

**Available patterns:**

```tsx
import { Avatar } from "@heroui/react"

// 1. Compound pattern (no .Root needed) - recommended
<Avatar>
  <Avatar.Image src="/avatar.jpg" alt="User" />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

// 2. Compound pattern with .Root - still supported
<Avatar.Root>
  <Avatar.Image src="/avatar.jpg" alt="User" />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>

// 3. Named exports
import { AvatarRoot, AvatarImage, AvatarFallback } from "@heroui/react"

```

**Simple components** like Button work the same way:

```tsx
import { Button } from "@heroui/react"

// No .Root needed
<Button>Label</Button>

// Or with .Root
<Button.Root>Label</Button.Root>

// Or named export
import { ButtonRoot } from "@heroui/react"
<ButtonRoot>Label</ButtonRoot>

```

**You can mix compound and named exports** in the same component:

```tsx
import { Avatar, AvatarFallback } from "@heroui/react"

```

This provides:

* **Simpler API**: Main components no longer require `.Root` suffix
* **Flexibility**: Choose between compound pattern, compound with `.Root`, or named exports
* **Backward Compatibility**: The `.Root` pattern still works
* **Naming Consistency**: Standardized naming (e.g., "Container" instead of "Wrapper")

### Global Animation Control

HeroUI now supports easy global animation control through the `data-reduce-motion` attribute. Simply add `data-reduce-motion="true"` to your `<html>` or `<body>` tag to disable all animations across your application.

```html
<!DOCTYPE html>
<html data-reduce-motion="true">
  
</html>

```

HeroUI automatically respects user motion preferences using the `prefers-reduced-motion` media query and extends Tailwind's `motion-reduce:` variant to support both system preferences and manual control via the data attribute. This provides flexible control over animations while maintaining accessibility best practices.

Learn more about animations and motion preferences in the [Animation documentation](/docs/handbook/animation).

## ⚠️ Breaking Changes

### Design System Variables

#### Panel → Surface & Overlay

The `--panel` variable has been replaced with `--surface` and `--overlay` to better distinguish between non-overlay components (cards, accordions) and floating components (tooltips, popovers, modals).

**Before:**

```css
--panel: var(--white);
--panel-foreground: var(--foreground);
--shadow-panel: 0 0 1px 0 rgba(0, 0, 0, 0.3) inset, 0 2px 8px 0 rgba(0, 0, 0, 0.08);

```

**After:**

```css
--surface: var(--white);
--surface-foreground: var(--foreground);
--overlay: var(--white);
--overlay-foreground: var(--foreground);
--shadow-surface: 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);
--shadow-overlay: 0 4px 16px 0 rgba(24, 24, 27, 0.08), 0 8px 24px 0 rgba(24, 24, 27, 0.09);

```

**Migration:**

* Replace `bg-panel` with `bg-surface` for non-overlay components
* Replace `bg-panel` with `bg-overlay` for floating components
* Replace `shadow-panel` with `shadow-surface` or `shadow-overlay`
* Replace `--color-panel` with `--color-surface` or `--color-overlay`

#### Surface Levels Simplified

The `--surface-1`, `--surface-2`, and `--surface-3` variables have been removed. Surface levels are now automatically calculated from `--surface` using `color-mix`, so you only need to declare the base surface color.

**Before (manual declaration):**

```css
--surface-1: var(--background);
--surface-2: var(--color-neutral-100);
--surface-3: var(--color-neutral-200);

```

**After (auto-calculated):**

```css
/* You only declare the base surface */
--surface: var(--white);
--surface-foreground: var(--foreground);

/* HeroUI automatically calculates these using color-mix */
--color-surface-secondary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
--color-surface-tertiary: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
--color-surface-quaternary: color-mix(in oklab, var(--surface) 86%, var(--surface-foreground) 14%);

```

**Customization:**

You can override the default calculations using Tailwind's `@theme` directive:

```css
@theme inline {
  --color-surface-secondary: color-mix(in oklab, var(--surface) 96%, var(--surface-foreground) 4%);
  --color-surface-tertiary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
  --color-surface-quaternary: color-mix(in oklab, var(--surface) 90%, var(--surface-foreground) 10%);
}

```

**Migration:**

* Replace `bg-surface-1` with `bg-surface` (base surface)
* Replace `bg-surface-2` with `bg-surface-secondary` (auto-calculated)
* Replace `bg-surface-3` with `bg-surface-tertiary` (auto-calculated)

The same auto-calculation pattern applies to:

* **Background shades**: Calculated from `--background` → `background-secondary`, `background-tertiary`, `background-quaternary`
* **Soft colors**: Calculated from status colors → `accent-soft`, `danger-soft`, `warning-soft`, `success-soft`

#### Border Width Default Changed

The default border width has changed from `1px` to `0px`. Borders are now opt-in rather than default.

**Before:**

```css
--border-width: 1px;

```

**After:**

```css
--border-width: 0px; /* no border by default */

```

**Migration:**

* If you rely on default borders, explicitly set `border-width` in your custom styles
* Form fields now use `transparent` borders by default

#### Border Color Default Changed

The default border color opacity has changed from `15%` to `0%` (transparent).

**Before:**

```css
--border: oklch(0 0 0 / 15%);

```

**After:**

```css
--border: oklch(0 0 0 / 0%);

```

**Field Border Default:**

```css
--field-border: transparent; /* no border by default on form fields */

```

#### Shadow System Updates

The shadow system has been completely redesigned with separate shadows for surfaces and overlays.

**Before:**

```css
--panel-shadow: 0 0 1px 0 rgba(0, 0, 0, 0.3) inset, 0 2px 8px 0 rgba(0, 0, 0, 0.08);
--field-shadow: 0 0 0 0 rgba(255, 255, 255, 0.1) inset, 0 1px 2px 0 rgba(0, 0, 0, 0.05);

```

**After (Light):**

```css
--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);

```

**After (Dark):**

```css
--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 */

```

#### Accent Color Updates

The accent color has been updated for better contrast and visual appeal.

**Before:**

```css
--accent: var(--color-neutral-950);
--accent-foreground: var(--snow);

```

**After:**

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

```

#### Status Color Refinements

Success, warning, and danger colors have been refined for better consistency and contrast.

**Success:**

* **Before:** `oklch(0.5503 0.1244 153.56)`
* **After:** `oklch(0.7329 0.1935 150.81)`
* Foreground changed from `var(--snow)` to `var(--eclipse)` in light mode

**Warning:**

* **Before:** `oklch(0.7186 0.1521 64.85)`
* **After:** `oklch(0.7819 0.1585 72.33)` (light), `oklch(0.8203 0.1388 76.34)` (dark)

**Danger:**

* **Before:** `oklch(0.6259 0.1908 29.19)`
* **After:** `oklch(0.6532 0.2328 25.74)` (light), `oklch(0.594 0.1967 24.63)` (dark)

### Component API Changes

#### Chip Component

The Chip component's `type` prop has been renamed to `color`, and a new `size` prop has been added. A new `soft` variant has been introduced.

**Before:**

```tsx
import { Chip } from "@heroui/react";

<Chip type="danger" variant="secondary">Label</Chip>

```

**After:**

```tsx
import { Chip } from "@heroui/react";

<Chip color="danger" variant="soft" size="md">Label</Chip>

```

**Migration:**

* Replace `type` prop with `color` prop
* Use `size` prop (`sm`, `md`, `lg`) to control chip size
* The `soft` variant provides a subtle appearance for less prominent chips

#### Link Component

The Link component now supports `underline` and `underlineOffset` props, and includes `asChild` support.

**Before:**

```tsx
import { Link } from "@heroui/react";

```

**After:**

```tsx
import { Link } from "@heroui/react";

```

**New Props:**

* `underline`: `"none" | "hover" | "always"` - Controls underline visibility
* `underlineOffset`: `number` - Controls underline offset from text

#### Type Reference Syntax

Due to the dual pattern implementation, type references through the namespace syntax are no longer supported. Use object-style syntax or named type imports instead.

**Before (no longer works):**

```tsx
type AvatarProps = Avatar.RootProps

```

**After (Option 1 - Object-style syntax):**

```tsx
type AvatarProps = Avatar["RootProps"]

```

**After (Option 2 - Named type imports, recommended):**

```tsx
import type { AvatarRootProps } from "@heroui/react"

type AvatarProps = AvatarRootProps

```

This change affects all compound components when accessing prop types.

#### Tabs Component Renaming

The Tabs component's wrapper element has been renamed for consistency:

* **Compound property**: `Tabs.ListWrapper` → `Tabs.ListContainer`
* **Named export**: `TabListWrapper` → `TabListContainer`
* **CSS class**: `.tabs__list-wrapper` → `.tabs__list-container`
* **Data attribute**: `data-slot="tabs-list-wrapper"` → `data-slot="tabs-list-container"`

**Migration:**

Find and replace all instances of `TabListWrapper` with `TabListContainer`:

```bash
# Component usage
TabListWrapper → TabListContainer
Tabs.ListWrapper → Tabs.ListContainer

# CSS selectors (if using custom styles)
.tabs__list-wrapper → .tabs__list-container
[data-slot="tabs-list-wrapper"] → [data-slot="tabs-list-container"]

```

#### Removed Variables

The following variables have been removed:

* `--panel` → Use `--surface` or `--overlay`
* `--panel-foreground` → Use `--surface-foreground` or `--overlay-foreground`
* `--surface-1`, `--surface-2`, `--surface-3` → Use background shades or surface levels
* `--accent-soft` → Use `--color-accent-soft` (now calculated)
* `--radius-panel` and `--radius-panel-inner` → Use standard radius values

## Design System Updates

### New Color System

#### Surface vs Overlay Concept

The design system now distinguishes between two types of elevated components:

* **Surface**: Used for non-overlay components like cards, accordions, and disclosure groups that sit on the page
* **Overlay**: Used for floating components like tooltips, popovers, modals, and menus that appear above the page

This distinction provides:

* Better visual hierarchy
* Appropriate shadow depths
* Improved dark mode contrast
* Clearer component semantics

#### Auto-Calculated Color System

HeroUI now automatically calculates shade levels and soft color variants using CSS `color-mix`. You only need to declare the base colors, and HeroUI handles the rest.

**Background Shade Levels**

Background shades are automatically calculated from `--background`:

```css
/* You only declare the base */
--background: oklch(0.9702 0 0);
--foreground: var(--eclipse);

/* HeroUI automatically calculates these */
--color-background-secondary: color-mix(in oklab, var(--color-background) 96%, var(--color-foreground) 4%);
--color-background-tertiary: color-mix(in oklab, var(--color-background) 92%, var(--color-foreground) 8%);
--color-background-quaternary: color-mix(in oklab, var(--color-background) 86%, var(--color-foreground) 14%);

```

**Surface Levels**

Surface levels are automatically calculated from `--surface`:

```css
/* You only declare the base */
--surface: var(--white);
--surface-foreground: var(--foreground);

/* HeroUI automatically calculates these */
--color-surface-secondary: color-mix(in oklab, var(--surface) 94%, var(--surface-foreground) 6%);
--color-surface-tertiary: color-mix(in oklab, var(--surface) 92%, var(--surface-foreground) 8%);
--color-surface-quaternary: color-mix(in oklab, var(--surface) 86%, var(--surface-foreground) 14%);

```

**Soft Color Variants**

Soft color variants are automatically calculated from status colors:

```css
/* You declare the base status colors */
--accent: oklch(0.6204 0.195 253.83);
--danger: oklch(0.6532 0.2328 25.74);
--warning: oklch(0.7819 0.1585 72.33);
--success: oklch(0.7329 0.1935 150.81);

/* HeroUI automatically calculates these at 15% opacity */
--color-accent-soft: color-mix(in oklab, var(--color-accent) 15%, transparent);
--color-danger-soft: color-mix(in oklab, var(--color-danger) 15%, transparent);
--color-warning-soft: color-mix(in oklab, var(--color-warning) 15%, transparent);
--color-success-soft: color-mix(in oklab, var(--color-success) 15%, transparent);

```

Each soft variant includes hover states (20% opacity) and foreground colors for proper contrast.

**Customization:**

You can override any auto-calculated values using Tailwind's `@theme` directive:

```css
@theme inline {
  /* Adjust surface levels */
  --color-surface-secondary: color-mix(in oklab, var(--surface) 96%, var(--surface-foreground) 4%);

/* Adjust soft colors */
  --color-accent-soft: color-mix(in oklab, var(--color-accent) 20%, transparent);
}

```

This auto-calculation system reduces the number of variables you need to manage while providing full customization when needed.

### Shadow System

The shadow system has been redesigned to provide:

* Separate shadows for surfaces and overlays
* Better depth perception
* Dark mode support (transparent shadows)
* Consistent field shadows

Shadows automatically adapt to light and dark modes, providing appropriate depth cues for each theme.

### Focus System

The focus color now uses the accent color for consistency:

```css
--focus: var(--accent);

```

This ensures focus indicators align with your brand colors while maintaining accessibility.

### Typography Tokens

Several typography-related variables have been removed in favor of using Tailwind's typography utilities directly. The design system now focuses on color and spacing tokens, letting Tailwind handle typography.

## Migration Guide

### Step 1: Update Design System Variables

Replace old panel variables with surface/overlay:

```css
/* Before */
.my-card {
  background: var(--panel);
  box-shadow: var(--shadow-panel);
}

/* After */
.my-card {
  background: var(--surface);
  box-shadow: var(--shadow-surface);
}

.my-tooltip {
  background: var(--overlay);
  box-shadow: var(--shadow-overlay);
}

```

### Step 2: Update Surface Levels

Surface levels are now automatically calculated from `--surface`, so you don't need to manually declare them. Simply use the new utility classes:

```css
/* Before */
.bg-surface-1 → .bg-surface (base surface)
.bg-surface-2 → .bg-surface-secondary (auto-calculated)
.bg-surface-3 → .bg-surface-tertiary (auto-calculated)

/* You can also use background shades */
.bg-surface-2 → .bg-background-secondary (auto-calculated from --background)
.bg-surface-3 → .bg-background-tertiary (auto-calculated from --background)

```

**Note:** Surface levels (`surface-secondary`, `surface-tertiary`, etc.) are automatically calculated based on your `--surface` color. No manual CSS variables needed unless you want to customize the calculations.

### Step 3: Update Component Props

Update Chip and Link components:

```tsx
// Chip: type → color, add size if needed
<Chip type="danger" /> → <Chip color="danger" size="md" />

// Link: Add underline props if customizing underlines
<Link href="#">Text</Link> // Still works, underline props are optional

```

### Step 4: Simplify Component Patterns (Optional)

If you adopted the `.Root` suffix from v3.0.0-alpha.35, you can now simplify your code by removing it:

**Before (v3.0.0-alpha.35):**

```tsx
<Avatar.Root>
  <Avatar.Image src="..." alt="..." />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar.Root>

```

**After (simpler):**

```tsx
<Avatar>
  <Avatar.Image src="..." alt="..." />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

```

**Note:** The `.Root` syntax still works if you prefer it.

### Step 5: Update Type References

If you're using namespace syntax for types, switch to object-style syntax or named imports:

**Before:**

```tsx
type ButtonProps = Button.RootProps

```

**After (Option 1 - Object-style):**

```tsx
type ButtonProps = Button["RootProps"]

```

**After (Option 2 - Named imports, recommended):**

```tsx
import type { ButtonRootProps } from "@heroui/react"

type ButtonProps = ButtonRootProps

```

### Step 6: Update Tabs Component

Replace `TabListWrapper` with `TabListContainer`:

**Before:**

```tsx
import { Tabs } from "@heroui/react"

<Tabs.Root>
  <Tabs.ListWrapper>
    <Tabs.List>
      <Tabs.Tab id="home">Home<Tabs.Indicator /></Tabs.Tab>
    </Tabs.List>
  </Tabs.ListWrapper>
  <Tabs.Panel id="home">Content</Tabs.Panel>
</Tabs.Root>

```

**After:**

```tsx
import { Tabs } from "@heroui/react"

<Tabs>
  <Tabs.ListContainer>
    <Tabs.List>
      <Tabs.Tab id="home">Home<Tabs.Indicator /></Tabs.Tab>
    </Tabs.List>
  </Tabs.ListContainer>
  <Tabs.Panel id="home">Content</Tabs.Panel>
</Tabs>

```

### Step 7: Handle Border Changes

If your custom styles rely on default borders:

```css
/* Add explicit borders where needed */
.my-component {
  border-width: 1px;
  border-color: var(--color-border);
}

```

### Step 8: Update Status Colors

If you've customized status colors, review the new values and adjust your custom theme if needed:

```css
/* Check if your custom status colors need updates */
--success: oklch(0.7329 0.1935 150.81); /* New value */
--warning: oklch(0.7819 0.1585 72.33); /* New value */
--danger: oklch(0.6532 0.2328 25.74); /* New value */

```

### Automated Migration

For large codebases, you can use find-and-replace:

```bash
# Panel → Surface
--panel → --surface
bg-panel → bg-surface
shadow-panel → shadow-surface

# Panel → Overlay (for floating components)
--panel → --overlay (where appropriate)
bg-panel → bg-overlay (for tooltips, popovers, etc.)
shadow-panel → shadow-overlay (for floating components)

# Chip type prop
type=" → color="

# Surface levels
bg-surface-1 → bg-surface
bg-surface-2 → bg-surface-secondary
bg-surface-3 → bg-surface-tertiary

# Tabs component
TabListWrapper → TabListContainer
Tabs.ListWrapper → Tabs.ListContainer

# Type references
Component.RootProps → Component["RootProps"] or use named imports

```

## Component Updates

### Card Component

Card component has been refined with improved variants and better semantic structure. The component now uses the new surface system for consistent styling.

### Accordion Component

Accordion now uses the surface system for better visual consistency with other components.

### Form Components

Form components (Input, TextField, TextArea) have been updated to use the new field border system (transparent by default) for a cleaner look while maintaining accessibility.

### Component Pattern Updates

All components now support flexible patterns. Components that support the dual pattern include:

* **Simple components**: Button, Link, Spinner, Chip, Kbd
* **Compound components**: Accordion, Avatar, Card, Disclosure, Fieldset, Popover, RadioGroup, Switch, Tabs, Tooltip

You can use any of the three patterns (compound without `.Root`, compound with `.Root`, or named exports) with all these components.

## HeroUI Pro

HeroUI Pro is being reshaped from the ground up on top of the new design system. The new Pro version will feature:

* New components built on top of HeroUI v3
* Tailwind CSS v4 native support
* CSS native animations
* Enhanced customization options

We'll share more updates soon.

## Roadmap

We're working towards a stable release in **Q4** this year (2025). This beta release brings us significantly closer to that goal with:

* Comprehensive component set
* Refined design system
* Improved developer experience
* Better performance

## Community

The reception on the native side has been phenomenal. Thank you for supporting us as we build HeroUI v3! Your feedback helps us improve every day.

See what the community is saying: [HeroUI Native Reception](https://x.com/hero_ui/status/1985721976220966926)

## Links

* [Component Documentation](https://v3.heroui.com/docs/components)
* [Design System - Figma Kit V3](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [HeroUI Native](https://link.heroui.com/native)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #5872](https://github.com/heroui-inc/heroui/pull/5872)

## Contributors

Thanks to everyone who contributed to this release, helping us create a design system that's both beautiful and practical!

</page>

<page url="/docs/react/releases/v3-0-0-beta-2">
# v3.0.0-beta.2

**Category**: react
**URL**: https://v3.heroui.com/docs/react/releases/v3-0-0-beta-2
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-beta-2.mdx
> Six new components (AlertDialog, ComboBox, Dropdown, InputGroup, Modal, NumberField), Select API improvements, and component refinements.

<div className="flex items-center gap-3 mb-6">
  <span className="text-sm text-muted">November 20, 2025</span>
</div>

This release introduces six essential new components, improves the Select component API, and includes various refinements and bug fixes.

## Installation

Update to the latest version:

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    ```bash
    npm i @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm add @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>

<Tab value="yarn">
    ```bash
    yarn add @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>

<Tab value="bun">
    ```bash
    bun add @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>
</Tabs>

## What's New

### New Components

This release introduces **6 new** essential components:

* **[AlertDialog](#alert-dialog)**: Modal dialog for important decisions that require user confirmation. ([Documentation](/docs/components/alert-dialog))
* **[ComboBox](#combobox)**: Combines a text input with a listbox, allowing users to filter a list of options. ([Documentation](/docs/components/combobox))
* **[Dropdown](#dropdown)**: Displays a list of actions or options that a user can choose. ([Documentation](/docs/components/dropdown))
* **[InputGroup](#inputgroup)**: Group related input controls with prefix and suffix elements for enhanced form fields. ([Documentation](/docs/components/input-group))
* **[Modal](#modal)**: Dialog overlay for focused user interactions and important content. ([Documentation](/docs/components/modal))
* **[NumberField](#numberfield)**: Number input with increment/decrement buttons, validation, and internationalized formatting. ([Documentation](/docs/components/number-field))

### AlertDialog

```tsx
"use client";

import {AlertDialog, Button} from "@heroui/react";

export function Default() {
  return (
    <AlertDialog>
      <Button variant="danger">Delete Project</Button>
      <AlertDialog.Backdrop>
        <AlertDialog.Container>
          <AlertDialog.Dialog className="sm:max-w-[400px]">
            <AlertDialog.CloseTrigger />
            <AlertDialog.Header>
              <AlertDialog.Icon status="danger" />
              <AlertDialog.Heading>Delete project permanently?</AlertDialog.Heading>
            </AlertDialog.Header>
            <AlertDialog.Body>
              <p>
                This will permanently delete <strong>My Awesome Project</strong> and all of its
                data. This action cannot be undone.
              </p>
            </AlertDialog.Body>
            <AlertDialog.Footer>
              <Button slot="close" variant="tertiary">
                Cancel
              </Button>
              <Button slot="close" variant="danger">
                Delete Project
              </Button>
            </AlertDialog.Footer>
          </AlertDialog.Dialog>
        </AlertDialog.Container>
      </AlertDialog.Backdrop>
    </AlertDialog>
  );
}

```

### ComboBox

```tsx
"use client";

import {ComboBox, Input, Label, ListBox} from "@heroui/react";

export function Default() {
  return (
    <ComboBox className="w-[256px]">
      <Label>Favorite Animal</Label>
      <ComboBox.InputGroup>
        <Input placeholder="Search animals..." />
        <ComboBox.Trigger />
      </ComboBox.InputGroup>
      <ComboBox.Popover>
        <ListBox>
          <ListBox.Item id="aardvark" textValue="Aardvark">
            Aardvark
            <ListBox.ItemIndicator />
          </ListBox.Item>
          <ListBox.Item id="cat" textValue="Cat">
            Cat
            <ListBox.ItemIndicator />
          </ListBox.Item>
          <ListBox.Item id="dog" textValue="Dog">
            Dog
            <ListBox.ItemIndicator />
          </ListBox.Item>
          <ListBox.Item id="kangaroo" textValue="Kangaroo">
            Kangaroo
            <ListBox.ItemIndicator />
          </ListBox.Item>
          <ListBox.Item id="panda" textValue="Panda">
            Panda
            <ListBox.ItemIndicator />
          </ListBox.Item>
          <ListBox.Item id="snake" textValue="Snake">
            Snake
            <ListBox.ItemIndicator />
          </ListBox.Item>
        </ListBox>
      </ComboBox.Popover>
    </ComboBox>
  );
}

```

### Dropdown

```tsx
"use client";

import {Button, Dropdown, Label} from "@heroui/react";

export function Default() {
  return (
    <Dropdown>
      <Button aria-label="Menu" variant="secondary">
        Actions
      </Button>
      <Dropdown.Popover>
        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
          <Dropdown.Item id="new-file" textValue="New file">
            <Label>New file</Label>
          </Dropdown.Item>
          <Dropdown.Item id="copy-link" textValue="Copy link">
            <Label>Copy link</Label>
          </Dropdown.Item>
          <Dropdown.Item id="edit-file" textValue="Edit file">
            <Label>Edit file</Label>
          </Dropdown.Item>
          <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
            <Label>Delete file</Label>
          </Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### Modal

```tsx
"use client";

import {Rocket} from "@gravity-ui/icons";
import {Button, Modal} from "@heroui/react";

export function Default() {
  return (
    <Modal>
      <Button variant="secondary">Open Modal</Button>
      <Modal.Backdrop>
        <Modal.Container>
          <Modal.Dialog className="sm:max-w-[360px]">
            <Modal.CloseTrigger />
            <Modal.Header>
              <Modal.Icon className="bg-default text-foreground">
                <Rocket className="size-5" />
              </Modal.Icon>
              <Modal.Heading>Welcome to HeroUI</Modal.Heading>
            </Modal.Header>
            <Modal.Body>
              <p>
                A beautiful, fast, and modern React UI library for building accessible and
                customizable web applications with ease.
              </p>
            </Modal.Body>
            <Modal.Footer>
              <Button className="w-full" slot="close">
                Continue
              </Button>
            </Modal.Footer>
          </Modal.Dialog>
        </Modal.Container>
      </Modal.Backdrop>
    </Modal>
  );
}

```

### InputGroup

```tsx
"use client";

import {Globe} from "@gravity-ui/icons";
import {InputGroup, Label, TextField} from "@heroui/react";

export function WithIconPrefixAndTextSuffix() {
  return (
    <TextField className="w-full max-w-[280px]" defaultValue="heroui" name="website">
      <Label>Website</Label>
      <InputGroup>
        <InputGroup.Prefix>
          <Globe className="size-4 text-muted" />
        </InputGroup.Prefix>
        <InputGroup.Input className="w-full max-w-[280px]" />
        <InputGroup.Suffix>.com</InputGroup.Suffix>
      </InputGroup>
    </TextField>
  );
}

```

### NumberField

```tsx
import {Label, NumberField} from "@heroui/react";

export function Basic() {
  return (
    <NumberField className="w-full max-w-64" defaultValue={1024} minValue={0} name="width">
      <Label>Width</Label>
      <NumberField.Group>
        <NumberField.DecrementButton />
        <NumberField.Input className="w-[120px]" />
        <NumberField.IncrementButton />
      </NumberField.Group>
    </NumberField>
  );
}

```

### Style Improvements

#### Custom Variants and Theme Compatibility

Enhanced CSS variants and theme system for better customization:

**Motion Preferences**:

* New `motion-safe` variant with `data-reduce-motion="true"` attribute matching
* Enhanced `motion-reduce` now supports ancestor elements and pseudo-elements

**Dark Mode**:

* Class and `data-theme="dark"` attribute selectors now take precedence over `prefers-color-scheme`
* Full support for pseudo-elements in dark mode

**Theme Variables**:

* Expanded light theme scope to support nested themes (`:root`, `.light`, `.default`, `[data-theme="light"]`, `[data-theme="default"]`)

### Component Improvements

#### Select Component API Update

The Select component's API has been improved for better consistency with other components. The `Content` subcomponent has been renamed to `Popover`.

**Before:**

```tsx
<Select>
  <Select.Trigger>
    <Select.Value />
    <Select.Indicator />
  </Select.Trigger>
  <Select.Content>
    <ListBox>
      {/* items */}
    </ListBox>
  </Select.Content>
</Select>

```

**After:**

```tsx
<Select>
  <Select.Trigger>
    <Select.Value />
    <Select.Indicator />
  </Select.Trigger>
  <Select.Popover>
    <ListBox>
      {/* items */}
    </ListBox>
  </Select.Popover>
</Select>

```

#### Chip Component Refinements

Chip component sizes have been updated for better consistency:

* **Small (`sm`)**: `px-1 py-0 text-xs`
* **Medium (`md`)**: `text-xs` (now explicitly set)
* **Large (`lg`)**: `px-3 py-1 text-sm font-medium`

#### Separator Component Enhancement

The Separator component now automatically detects when it's placed inside a surface component (one that uses `bg-surface`) and applies the appropriate divider color for better visibility. A new `isOnSurface` prop is also available for manual control.

**New Calculated Variable:**

* `--color-separator-on-surface`: A calculated variable (automatically generated using `color-mix`) that ensures the separator is visible when placed on a surface background. Like other calculated variables, it can be overridden in your theme.

**Usage:**

```tsx
<div className="bg-surface">
  <Separator isOnSurface />
</div>

```

The `isOnSurface` prop is automatically applied when the Separator detects a `SurfaceContext` provider (used by components like Card, Alert, Popover, Modal, etc.).

You can also use the calculated variable directly with Tailwind classes:

```tsx
<div className="bg-surface">
  <div className="h-px w-full bg-separator-on-surface" />
</div>

```

#### Animation Improvements

* Loading state spinner color updated for better visibility
* Select and Slider component styles adjusted for improved animations
* Checkbox animation improved (faster transition)
* Better support for `prefers-reduced-motion` with pseudo elements

## ⚠️ Breaking Changes

### Select Component

The `Select.Content` subcomponent has been renamed to `Select.Popover` for consistency with other components like ComboBox and Dropdown.

**Migration:**

Replace all instances of `Select.Content` with `Select.Popover`:

```tsx
// Before
<Select.Content>
  <ListBox>...</ListBox>
</Select.Content>

// After
<Select.Popover>
  <ListBox>...</ListBox>
</Select.Popover>

```

**Type imports:**

```tsx
// Before
import type { SelectContentProps } from "@heroui/react"

// After
import type { SelectPopoverProps } from "@heroui/react"

```

**Named exports:**

```tsx
// Before
import { SelectContent } from "@heroui/react"

// After
import { SelectPopover } from "@heroui/react"

```

### CSS Variables and Utilities: Divider → Separator

All CSS variables and utility classes related to `divider` have been renamed to `separator` for consistency with the Separator component name.

**CSS Variables:**

```css
/* Before */
border-bottom: 1px solid var(--divider);

/* After */
border-bottom: 1px solid var(--separator);

```

**Tailwind Utility Classes:**

```tsx
// Before
<div className="bg-divider" />
<div className="border-divider" />

// After
<div className="bg-separator" />
<div className="border-separator" />

```

**Theme Overrides:**

If you have custom themes that override the divider variable, update them:

```css
/* Before */
:root {
  --divider: oklch(92% 0.004 286.32);
}

.dark {
  --divider: oklch(22% 0.006 286.033);
}

/* After */
:root {
  --separator: oklch(92% 0.004 286.32);
}

.dark {
  --separator: oklch(22% 0.006 286.033);
}

```

## Bug Fixes

* Fixed loading state spinner color for better visibility
* Fixed bordered focus styles taking precedence over hover states
* Fixed animation stuttering in documentation
* Improved modal form styling
* Enhanced motion reduce support for pseudo elements
* Fixed mobile hover states sticking after touch interactions by wrapping hover styles in `@media (hover: hover)` media queries. Also simplified data attribute selectors by removing unnecessary `="true"` value checks.

## Links

* [Component Documentation](https://v3.heroui.com/docs/components)
* [Design System - Figma Kit V3 (updated)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #5885](https://github.com/heroui-inc/heroui/pull/5885)

## Contributors

Thanks to everyone who contributed to this release!

</page>

<page url="/docs/react/releases/v3-0-0-beta-3">
# v3.0.0-beta.3

**Category**: react
**URL**: https://v3.heroui.com/docs/react/releases/v3-0-0-beta-3
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/releases/v3-0-0-beta-3.mdx
> Seven new components, fullWidth and hideSeparator support, style fixes, and breaking changes for AlertDialog/Modal backdrop variants and asChild prop removal.

<div className="flex items-center gap-3 mb-6">
  <span className="text-sm text-muted">December 19, 2025</span>
</div>

This release introduces seven new components ([ButtonGroup](/docs/components/button-group), [DateField](/docs/components/date-field), [ErrorMessage](/docs/components/error-message), [ScrollShadow](/docs/components/scroll-shadow), [SearchField](/docs/components/search-field), [TagGroup](/docs/components/tag-group), [TimeField](/docs/components/time-field)), adds `fullWidth` support for form components and `hideSeparator` to [Tabs](/docs/components/tabs), [ButtonGroup](/docs/components/button-group), and [Accordion](/docs/components/accordion), includes style fixes, and ⚠️ **breaking changes** removing the `asChild` prop and updating [AlertDialog](/docs/components/alert-dialog) & [Modal](/docs/components/modal) backdrop variants.

## Installation

Update to the latest version:

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    ```bash
    npm i @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm add @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>

<Tab value="yarn">
    ```bash
    yarn add @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>

<Tab value="bun">
    ```bash
    bun add @heroui/styles@beta @heroui/react@beta
    ```
  </Tab>
</Tabs>

## What's New

### New Components

This release introduces **7 new** essential components:

* **[ButtonGroup](#button-group)**: Groups related buttons with consistent styling and spacing. ([Documentation](/docs/components/button-group))
* **[DateField](#date-field)**: Date input field with labels, descriptions, and validation built on React Aria DateField. ([Documentation](/docs/components/date-field))
* **[ErrorMessage](#error-message)**: Low-level error message component for displaying errors in non-form components. ([Documentation](/docs/components/error-message))
* **[ScrollShadow](#scroll-shadow)**: Apply visual shadows to indicate scrollable content overflow with automatic detection of scroll position. ([Documentation](/docs/components/scroll-shadow))
* **[SearchField](#search-field)**: Search input field with built-in search icon and clear button. ([Documentation](/docs/components/search-field))
* **[TagGroup](#tag-group)**: Focusable list of tags with support for keyboard navigation, selection, and removal. ([Documentation](/docs/components/tag-group))
* **[TimeField](#time-field)**: Time input field with labels, descriptions, and validation built on React Aria TimeField. ([Documentation](/docs/components/time-field))

### ButtonGroup

```tsx
import {
  ChevronDown,
  ChevronLeft,
  ChevronRight,
  CodeFork,
  Ellipsis,
  Picture,
  Pin,
  QrCode,
  Star,
  TextAlignCenter,
  TextAlignJustify,
  TextAlignLeft,
  TextAlignRight,
  ThumbsDown,
  ThumbsUp,
  Video,
} from "@gravity-ui/icons";
import {Button, ButtonGroup, Chip, Description, Dropdown, Label} from "@heroui/react";

export function Basic() {
  return (
    <div className="flex flex-col items-start gap-6">
      {/* Single button with dropdown */}
      <div className="flex flex-col gap-2">
        <ButtonGroup>
          <Button>Merge pull request</Button>
          <Dropdown>
            <Button isIconOnly aria-label="More options">
              <ChevronDown />
            </Button>
            <Dropdown.Popover className="max-w-[290px]" placement="bottom end">
              <Dropdown.Menu>
                <Dropdown.Item
                  className="flex flex-col items-start gap-1"
                  id="merge"
                  textValue="Create a merge commit"
                >
                  <Label>Create a merge commit</Label>
                  <Description>
                    All commits from this branch will be added to the base branch
                  </Description>
                </Dropdown.Item>
                <Dropdown.Item
                  className="flex flex-col items-start gap-1"
                  id="squash-and-merge"
                  textValue="Squash and merge"
                >
                  <Label>Squash and merge</Label>
                  <Description>
                    The 14 commits from this branch will be combined into one commit in the base
                    branch
                  </Description>
                </Dropdown.Item>
                <Dropdown.Item
                  className="flex flex-col items-start gap-1"
                  id="rebase-and-merge"
                  textValue="Rebase and merge"
                >
                  <Label>Rebase and merge</Label>
                  <Description>
                    The 14 commits from this branch will be rebased and added to the base branch
                  </Description>
                </Dropdown.Item>
              </Dropdown.Menu>
            </Dropdown.Popover>
          </Dropdown>
        </ButtonGroup>
      </div>

{/* Individual buttons */}
      <div className="flex flex-col gap-2">
        <div className="flex flex-wrap gap-x-2 gap-y-4">
          <ButtonGroup variant="tertiary">
            <Button>
              <CodeFork className="size-3.5" />
              Fork
              <Chip color="accent" size="sm" variant="soft">
                24
              </Chip>
            </Button>
            <Button isIconOnly>
              <ChevronDown />
            </Button>
          </ButtonGroup>
          <ButtonGroup variant="tertiary">
            <Button isIconOnly>
              <QrCode />
            </Button>
            <Button>Scan to pay</Button>
          </ButtonGroup>
          <ButtonGroup variant="tertiary">
            <Button>
              <ThumbsUp />
              <span className="text-xs font-semibold">2.4K</span>
            </Button>
            <Button isIconOnly>
              <ThumbsDown />
            </Button>
          </ButtonGroup>
          <ButtonGroup variant="tertiary">
            <Button>
              <Star className="size-3.5" />
              Star
            </Button>
            <Button className="px-2">
              <Chip color="accent" size="sm" variant="soft">
                104
              </Chip>
            </Button>
          </ButtonGroup>
          <ButtonGroup variant="tertiary">
            <Button>
              <Pin />
              Pinned
            </Button>
            <Button isIconOnly>
              <ChevronDown />
            </Button>
          </ButtonGroup>
        </div>
      </div>

{/* Previous/Next Button Group */}
      <div className="flex flex-col gap-2">
        <ButtonGroup variant="tertiary">
          <Button>
            <ChevronLeft />
            Previous
          </Button>
          <Button>
            Next
            <ChevronRight />
          </Button>
        </ButtonGroup>
      </div>

{/* Content Selection Button Group */}
      <div className="flex flex-col gap-2">
        <ButtonGroup variant="tertiary">
          <Button>
            <Picture />
            Photos
          </Button>
          <Button>
            <Video />
            Videos
          </Button>
          <Button isIconOnly aria-label="More options">
            <Ellipsis />
          </Button>
        </ButtonGroup>
      </div>

{/* Text Alignment Button Group */}
      <div className="flex flex-col gap-2">
        <ButtonGroup variant="tertiary">
          <Button>Left</Button>
          <Button>Center</Button>
          <Button>Right</Button>
        </ButtonGroup>
      </div>

{/* Icon-Only Alignment Button Group */}
      <div className="flex flex-col gap-2">
        <ButtonGroup variant="tertiary">
          <Button isIconOnly>
            <TextAlignLeft />
          </Button>
          <Button isIconOnly>
            <TextAlignCenter />
          </Button>
          <Button isIconOnly>
            <TextAlignRight />
          </Button>
          <Button isIconOnly>
            <TextAlignJustify />
          </Button>
        </ButtonGroup>
      </div>
    </div>
  );
}

```

### DateField

```tsx
"use client";

import {DateField, DateInputGroup, Label} from "@heroui/react";

export function Basic() {
  return (
    <DateField className="w-[256px]" name="date">
      <Label>Date</Label>
      <DateInputGroup>
        <DateInputGroup.Input>
          {(segment) => <DateInputGroup.Segment segment={segment} />}
        </DateInputGroup.Input>
      </DateInputGroup>
    </DateField>
  );
}

```

### ErrorMessage

```tsx
"use client";

import type {Key} from "@heroui/react";

import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react";
import {useMemo, useState} from "react";

export function ErrorMessageBasic() {
  const [selected, setSelected] = useState<Iterable<Key>>(new Set());
  const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]);

return (
    <TagGroup
      selectedKeys={selected}
      selectionMode="multiple"
      onSelectionChange={(keys) => setSelected(keys)}
    >
      <Label>Required Categories</Label>
      <TagGroup.List>
        <Tag id="news">News</Tag>
        <Tag id="travel">Travel</Tag>
        <Tag id="gaming">Gaming</Tag>
        <Tag id="shopping">Shopping</Tag>
      </TagGroup.List>
      <Description>Select at least one category</Description>
      <ErrorMessage>{!!isInvalid && <>Please select at least one category</>}</ErrorMessage>
    </TagGroup>
  );
}

```

### SearchField

```tsx
import {Label, SearchField} from "@heroui/react";

export function Basic() {
  return (
    <SearchField name="search">
      <Label>Search</Label>
      <SearchField.Group>
        <SearchField.SearchIcon />
        <SearchField.Input className="w-[280px]" placeholder="Search..." />
        <SearchField.ClearButton />
      </SearchField.Group>
    </SearchField>
  );
}

```

### ScrollShadow

```tsx
import {Card, ScrollShadow} from "@heroui/react";

const images = [
  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg",
  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg",
  "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg",
];

export default function Orientation() {
  const getRandomImage = (idx: number) => {
    return images[idx % images.length];
  };

return (
    <div className="w-full sm:max-w-sm">
      <div className="mb-8 w-full">
        <h4 className="mb-2 text-sm font-semibold">Vertical</h4>
        <Card className="w-full p-0">
          <ScrollShadow className="max-h-[240px] p-4" orientation="vertical">
            <div className="space-y-4">
              {Array.from({length: 10}).map((_, idx) => (
                <p key={`scroll-shadow-lorem-content-${idx}`}>
                  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non
                  risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor
                  quam. Morbi accumsan cursus enim, sed ultricies sapien.
                </p>
              ))}
            </div>
          </ScrollShadow>
        </Card>
      </div>

<div className="w-full">
        <h4 className="mb-2 text-sm font-semibold">Horizontal</h4>
        <Card className="w-full p-0">
          <ScrollShadow className="p-4" orientation="horizontal">
            <div className="flex flex-row gap-4">
              {Array.from({length: 10}).map((_, idx) => (
                <Card
                  key={`scroll-shadow-lorem-cards-${idx}`}
                  className="flex min-w-[200px] flex-row gap-3 p-1"
                  variant="transparent"
                >
                  <img
                    alt="Lorem Card"
                    className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20"
                    loading="lazy"
                    src={getRandomImage(idx)}
                  />
                  <div className="flex flex-1 flex-col justify-center gap-1">
                    <Card.Title className="text-sm">Bridging the Future</Card.Title>
                    <Card.Description className="text-xs">Today, 6:30 PM</Card.Description>
                  </div>
                </Card>
              ))}
            </div>
          </ScrollShadow>
        </Card>
      </div>
    </div>
  );
}

```

### TagGroup

```tsx
"use client";

import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
import {Tag, TagGroup} from "@heroui/react";

export function TagGroupBasic() {
  return (
    <TagGroup aria-label="Tags" selectionMode="single">
      <TagGroup.List>
        <Tag id="default-news">
          <SquareArticle />
          News
        </Tag>
        <Tag id="default-travel">
          <PlanetEarth />
          Travel
        </Tag>
        <Tag id="default-gaming">
          <Rocket />
          Gaming
        </Tag>
        <Tag id="default-shopping">
          <ShoppingBag />
          Shopping
        </Tag>
      </TagGroup.List>
    </TagGroup>
  );
}

```

### TimeField

```tsx
"use client";

import {DateInputGroup, Label, TimeField} from "@heroui/react";

export function Basic() {
  return (
    <TimeField className="w-[256px]" name="time">
      <Label>Time</Label>
      <DateInputGroup>
        <DateInputGroup.Input>
          {(segment) => <DateInputGroup.Segment segment={segment} />}
        </DateInputGroup.Input>
      </DateInputGroup>
    </TimeField>
  );
}

```

### Full-Width Support

Added `fullWidth` support to form and input components, allowing them to span the full width of their container. This is particularly useful for creating consistent form layouts and responsive designs.

**Supported components:**

* [ButtonGroup](/docs/components/button-group)
* [Button](/docs/components/button)
* [ComboBox](/docs/components/combobox)
* [DateField](/docs/components/date-field)
* [DateInputGroup](/docs/components/date-input-group)
* [InputGroup](/docs/components/input-group)
* [Input](/docs/components/input)
* [NumberField](/docs/components/number-field)
* [SearchField](/docs/components/search-field)
* [Select](/docs/components/select)
* [TextField](/docs/components/text-field)
* [TextArea](/docs/components/textarea)
* [TimeField](/docs/components/time-field)

## Component Improvements

### Separator Control Enhancement

Added `hideSeparator` prop to [Tabs](/docs/components/tabs), [ButtonGroup](/docs/components/button-group), and [Accordion](/docs/components/accordion) components, allowing you to hide separator lines between items for a cleaner, more minimal appearance.

**Tabs:**

```tsx
<Tabs hideSeparator>
  <Tabs.ListContainer>
    <Tabs.List aria-label="Options">
      <Tabs.Tab id="overview">Overview<Tabs.Indicator /></Tabs.Tab>
      <Tabs.Tab id="analytics">Analytics<Tabs.Indicator /></Tabs.Tab>
    </Tabs.List>
  </Tabs.ListContainer>
</Tabs>

```

**ButtonGroup:**

```tsx
<ButtonGroup hideSeparator>
  <Button>First</Button>
  <Button>Second</Button>
  <Button>Third</Button>
</ButtonGroup>

```

**Accordion:**

```tsx
<Accordion hideSeparator>
  <Accordion.Item>
    <Accordion.Heading>
      <Accordion.Trigger>Item 1</Accordion.Trigger>
    </Accordion.Heading>
    <Accordion.Panel>
      <Accordion.Body>Content</Accordion.Body>
    </Accordion.Panel>
  </Accordion.Item>
</Accordion>

```

### Documentation Icons Integration

Integrated [@gravity-ui/icons](https://github.com/gravity-ui/icons) into documentation components for consistent icon rendering with improved SSR support and better performance.

## Dependencies

### React Aria Components v1.14.0

Upgraded [react-aria-components](https://react-aria.adobe.com/releases/v1-14-0) to v1.14.0. This release includes:

**Enhancements:**

* SearchField: Added `isReadOnly` and `isRequired` to render props
* Tooltip: Added `shouldCloseOnPress` prop
* Tabs: Support for animated transitions between tab panels
* Miscellaneous: Support for `setState` callback in `useControlledState`

**Fixes:**

* ComboBox: Fixed VoiceOver announcement not respecting `aria-label` of ListBoxItem
* Date and Time: Enhanced error handling for absolute date and date time strings
* NumberField: Prevented incrementing/decrementing when scrolling on mobile
* Overlays: Fixed overlay positioning and flipping when boundary container is set
* Table: Fixed crash in drag and drop when keyboard navigating
* Various other bug fixes and improvements

For the complete list of changes, see the [React Aria Components v1.14.0 release notes](https://react-aria.adobe.com/releases/v1-14-0).

### Other Dependency Upgrades

* `@internationalized/date`: 3.10.0 → 3.10.1
* `@radix-ui/react-avatar`: 1.1.10 → 1.1.11
* `tailwind-merge`: 3.3.1 → 3.4.0
* `tailwind-variants`: 3.1.1 → 3.2.2

## Style Fixes

### Form Component Disabled State

Fixed disabled state styling for [Input](/docs/components/input) and [TextArea](/docs/components/textarea) components.

### Style Optimizations

* **Improved selector precision**: Enhanced CSS selector specificity for better style isolation and performance
* **Enhanced animations**: Improved animation performance and smoothness across components
* **Added no-highlight utility**: Added `no-highlight` utility class to prevent text selection on interactive elements for improved user experience
* **Optimized will-change properties**: Updated `will-change` CSS properties across components for better animation performance
* **Removed global scrollbar styling**: Removed global scrollbar styles to prevent conflicts with custom scrollbar implementations and fix modal/overlay interaction issues

## ⚠️ Breaking Changes

### AlertDialog & Modal Backdrop Variant

Renamed `backdropVariant`/`variant` prop value from `"solid"` to `"opaque"` for better semantic clarity. The term "opaque" more accurately describes the backdrop's visual appearance.

**Migration:**

Update all instances of `backdropVariant="solid"` to `backdropVariant="opaque"` for AlertDialog, and `variant="solid"` to `variant="opaque"` for Modal:

```tsx
// Before
<AlertDialog.Backdrop backdropVariant="solid">
  <AlertDialog.Container>
    {/* content */}
  </AlertDialog.Container>
</AlertDialog.Backdrop>

<Modal.Backdrop variant="solid">
  <Modal.Container>
    {/* content */}
  </Modal.Container>
</Modal.Backdrop>

// After
<AlertDialog.Backdrop backdropVariant="opaque">
  <AlertDialog.Container>
    {/* content */}
  </AlertDialog.Container>
</AlertDialog.Backdrop>

<Modal.Backdrop variant="opaque">
  <Modal.Container>
    {/* content */}
  </Modal.Container>
</Modal.Backdrop>

```

**Available backdrop variants:**

* `"opaque"` - Dark backdrop that completely obscures the background (formerly `"solid"`)
* `"blur"` - Blurred backdrop that softly obscures the background
* `"transparent"` - Transparent backdrop that keeps the background visible

### Removed `asChild` Prop

Removed the `asChild` prop pattern from components for cleaner APIs, improved type safety, and simplified usage.

For more details about component composition patterns, see the [Composition guide](/docs/handbook/composition).

## Bug Fixes

* Fixed `isInvalid` styles when components are used on surface backgrounds
* Fixed AlertDialog and Modal re-rendering issues after close
* Fixed overlay close issue that prevented proper cleanup when closing overlays
* Fixed Storybook links and navigation issues

## Links

* [Component Documentation](https://v3.heroui.com/docs/components)
* [Design System - Figma Kit V3 (updated)](https://www.figma.com/community/file/1546526812159103429/heroui-figma-kit-v3)
* [GitHub Repository](https://github.com/heroui-inc/heroui)
* [GitHub PR #5923](https://github.com/heroui-inc/heroui/pull/5923)

## Contributors

Thanks to everyone who contributed to this release!

</page>

<page url="/docs/native/getting-started/animation">
# Animation

**Category**: native
**URL**: https://v3.heroui.com/docs/native/getting-started/animation
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/(handbook)/animation.mdx
> Add smooth animations and transitions to HeroUI Native components

All animations in HeroUI Native are built with [react-native-reanimated](https://docs.swmansion.com/react-native-reanimated/) and gesture control is handled by [react-native-gesture-handler](https://docs.swmansion.com/react-native-gesture-handler/). It's worth familiarizing yourself with these libraries if you want more control over animations.

## The `animation` Prop

Every animated component in HeroUI Native exposes a single `animation` prop that controls all animations for that component. This prop allows you to modify animation values, timing configurations, layout animations, or completely disable animations.

**Approach**: If you're working with animations, first look for the `animation` prop on the component you're using.

## Modifying Animations

You can customize animations by passing an object to the `animation` prop. Each component exposes different animation properties that you can modify. The approach is simple: if you want to slightly change the animation behavior of already written animations in components, we provide all necessary values for modification. If you want to write your own animations without relying on our written ones, you must create your own custom components with animations.

### Example 1: Simple Value Modification

Modify animation values like scale, opacity, or colors:

```tsx
import {Switch} from 'heroui-native';

<Switch
  animation={{
    scale: {
      value: [1, 0.9], // [unpressed, pressed]
    },
    backgroundColor: {
      value: ['#172554', '#eab308'], // [unselected, selected]
    },
  }}>
  <Switch.Thumb />
</Switch>;

```

### Example 2: Timing Configuration

Customize animation timing and easing:

```tsx
import {Accordion} from 'heroui-native';

<Accordion>
  <Accordion.Item value="1">
    <Accordion.Trigger>
      <Accordion.Indicator
        animation={{
          rotation: {
            value: [0, -180],
            springConfig: {
              damping: 60,
              stiffness: 900,
              mass: 3,
            },
          },
        }}
      />
    </Accordion.Trigger>
  </Accordion.Item>
</Accordion>;

```

### Example 3: Layout Animations (Entering/Exiting)

Customize entering and exiting animations using Reanimated's layout animations:

```tsx
import {Accordion} from 'heroui-native';
import {FadeInRight, FadeInLeft, ZoomIn} from 'react-native-reanimated';
import {Easing} from 'react-native-reanimated';

<Accordion>
  <Accordion.Item value="1">
    <Accordion.Content
      animation={{
        entering: {
          value: FadeInRight.delay(50).easing(Easing.inOut(Easing.ease)),
        },
      }}>
      Content here
    </Accordion.Content>
  </Accordion.Item>
</Accordion>;

```

## Disabling Animations

You can disable animations at different levels using the `animation` prop.

### Disable Options

* `animation={false}` or `animation="disabled"`: Disable animations for the specific component only
* `animation="disable-all"`: Disable all animations including children (only available at root level)
* `animation={true}` or `animation={undefined}`: Use default animations

### Component-Level Disabling

Disable animations for a specific component:

```tsx
<Switch>
  <Switch.Thumb animation={false} />
</Switch>

```

### Root-Level Disabling (`disable-all`)

The `"disable-all"` option is only available at the root level of compound components. When used, it disables all animations including children, even if those children are not part of the compound component structure:

```tsx
// Disables all animations including Button components inside Card
<Card animation="disable-all">
  <Card.Body>
    <Card.Title>$450</Card.Title>
    <Card.Description>Living room Sofa</Card.Description>
  </Card.Body>
  <Card.Footer className="gap-3">
    <Button variant="primary">Buy now</Button>
    <Button variant="ghost">Add to cart</Button>
  </Card.Footer>
</Card>

```

**Important**: `"disable-all"` cascades down to all child components, including standalone components like `Button`, `Spinner`, etc., not just compound component parts.

## Global Animation Configuration

You can disable all HeroUI Native animations globally using the `HeroUINativeProvider`:

```tsx
import {HeroUINativeProvider} from 'heroui-native';

<HeroUINativeProvider
  config={{
    animation: 'disable-all',
  }}>
  <App />
</HeroUINativeProvider>;

```

This will disable all animations across your entire application, regardless of individual component `animation` prop settings.

## Accessibility

Reduce motion is handled automatically under the hood. When a user enables "Reduce Motion" in their device accessibility settings, all animations are automatically disabled globally. This is handled by the `GlobalAnimationSettingsProvider` which checks `useReducedMotion()` from react-native-reanimated.

You don't need to do anything - the library respects the user's accessibility preferences automatically.

## Animation State Management

We keep disabled state of animations under control internally to ensure they look nice without unpredictable lags or jumps. When animations are disabled, components immediately jump to their final state rather than animating, preventing visual glitches or intermediate states.

## Children Render Function

Many components support a render function pattern for children, which is particularly handy when working with state like `isSelected`:

```tsx
import {Switch} from 'heroui-native';

<Switch
  isSelected={isSelected}
  onSelectedChange={setIsSelected}>
  {({isSelected, isDisabled}) => (
    <Switch.Thumb>{isSelected ? <CheckIcon /> : <XIcon />}</Switch.Thumb>
  )}
</Switch>;

```

This pattern allows you to conditionally render content based on component state, making it easy to create dynamic UIs that respond to selection, disabled states, and other component properties.

## Next Steps

* Learn about [Styling](/docs/native/getting-started/styling) approaches
* View [Theming](/docs/native/getting-started/theming) documentation
* Explore [Colors](/docs/native/getting-started/colors) documentation

</page>

<page url="/docs/native/getting-started/colors">
# Colors

**Category**: native
**URL**: https://v3.heroui.com/docs/native/getting-started/colors
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/(handbook)/colors.mdx
> Color palette and theming system for HeroUI Native

import {ColorSwatch, ColorPalette} from "@/components/color-swatch";

HeroUI Native 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 Native's color system is built on top of [Tailwind CSS v4](https://tailwindcss.com/docs/theme)'s theme via [Uniwind](https://uniwind.dev/). When you import `heroui-native/styles`, it uses Tailwind's built-in color palettes and maps them to semantic variables.

**Naming pattern:**

* Colors without a suffix are backgrounds (e.g., `--accent`)
* Colors with `-foreground` are for text on that background (e.g., `--accent-foreground`)

**Usage:**

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

// This gives you the right background and text colors
<View className="bg-background flex-1">
  <View className="bg-accent p-4 rounded-lg">
    <Text className="text-accent-foreground">Hello</Text>
  </View>
</View>

```

### Base Colors

These four colors stay the same in all themes:

### Background & Surface

### Primary Colors

**Accent** — Your main brand color (used for primary actions)
**Accent Soft** — A lighter version for secondary actions

### Status Colors

For alerts, validation, and status messages:

### Form Field Colors

For consistent form field styling across input components:

### Other Colors

## How to Use Colors

**In your components:**

```tsx
import { View, Text } from 'react-native';
import { Button } from 'heroui-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:**

```css title="global.css"
/* 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](https://github.com/heroui-inc/heroui-native/blob/beta/src/styles/variables.css)). This theme automatically switches between light and dark modes through [Uniwind's theming system](https://docs.uniwind.dev/theming/basics), which supports system preferences and programmatic theme switching.

```css
  @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);
    --eclipse: oklch(0.2103 0.0059 285.89);

/* Base radius */
    --radius: 0.5rem;

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

@layer theme {
    :root {
      @variant light {
        /* 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 (dialogs, popovers, modals, menus) */
        --overlay: var(--white);
        --overlay-foreground: var(--foreground);

--muted: oklch(55.2% 0.016 285.938);

--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(72% 0.004 286.32);
        --link: var(--foreground);
      }

@variant dark {
        /* Base Colors */
        --background: var(--black);
        --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 (dialogs, popovers, modals, menus) - lighter for contrast */
        --overlay: oklch(
          0.2563 0.0058 271.19
        ); /* Lighter than surface for visibility in dark mode */
        --overlay-foreground: var(--foreground);

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

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

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

/* Form Field Defaults - Colors (only the ones that are different from light theme) */
        --field-background: var(--default);
        --field-foreground: var(--foreground);
        --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.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(38% 0.006 286.033);
        --link: var(--foreground);
      }
    }
  }

```

## Customizing Colors

**Override existing colors:**

```css
@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](https://oklch.com)

**Add your own colors:**

```css
@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:

```tsx
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](https://tailwindcss.com/docs/theme).

## 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

## Related

* [Theming](/docs/native/getting-started/theming) - Learn about the theming system
* [Styling](/docs/native/getting-started/styling) - Styling components with CSS
* [Design Principles](/docs/native/getting-started/design-principles) - Understanding HeroUI's design philosophy

</page>

<page url="/docs/native/getting-started/composition">
# Composition

**Category**: native
**URL**: https://v3.heroui.com/docs/native/getting-started/composition
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/(handbook)/composition.mdx
> Build flexible UI with component composition patterns

HeroUI Native uses composition patterns to create flexible, customizable components. Change the rendered element, compose components together, and maintain full control over markup.

## Compound Components

HeroUI Native components use a compound component pattern with dot notation—components export sub-components as properties (e.g., `Button.Label`, `Dialog.Trigger`, `Accordion.Item`) that work together to form complete UI elements.

```tsx
import { Button, Dialog } from 'heroui-native';

function DialogExample() {
  return (
    <Dialog>
      <Dialog.Trigger>
        Open Dialog
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content>
          <Dialog.Close />
          <Dialog.Title>Dialog Title</Dialog.Title>
          <Dialog.Description>Dialog description</Dialog.Description>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog>
  );
}

```

## The asChild Prop

The `asChild` prop lets you change what element a component renders. When `asChild` is true, HeroUI Native clones the child element and merges props instead of rendering its default element.

```tsx
import { Button, Dialog } from 'heroui-native';

function DialogExample() {
  return (
    <Dialog>
      {/* With asChild: Button becomes the trigger directly, no wrapper element */}
      <Dialog.Trigger asChild>
        <Button variant="primary">Open Dialog</Button>
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content>
          {/* Dialog.Close can also use asChild */}
          <Dialog.Close asChild>
            <Button variant="ghost" size="sm">Cancel</Button>
          </Dialog.Close>
          <Dialog.Title>Dialog Title</Dialog.Title>
          <Dialog.Description>Dialog description</Dialog.Description>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog>
  );
}

```

## Custom Components

Create your own components by composing HeroUI Native primitives:

```tsx
import { Button, Card, Popover } from 'heroui-native';
import { View } from 'react-native';

// Product card component
function ProductCard({ title, description, price, onBuy, ...props }) {
  return (
    <Card {...props}>
      <Card.Body>
        <Card.Title>{price}</Card.Title>
        <Card.Title>{title}</Card.Title>
        <Card.Description>{description}</Card.Description>
      </Card.Body>
      <Card.Footer>
        <Button variant="primary" onPress={onBuy}>
          <Button.Label>Buy now</Button.Label>
        </Button>
      </Card.Footer>
    </Card>
  );
}

// Popover button component
function PopoverButton({ children, popoverContent, ...props }) {
  return (
    <Popover>
      <Popover.Trigger asChild>
        <Button {...props}>
          <Button.Label>{children}</Button.Label>
        </Button>
      </Popover.Trigger>
      <Popover.Portal>
        <Popover.Overlay />
        <Popover.Content>
          <Popover.Close />
          {popoverContent}
        </Popover.Content>
      </Popover.Portal>
    </Popover>
  );
}

// Usage
<ProductCard
  title="Living room Sofa"
  description="Perfect for modern spaces"
  price="$450"
  onBuy={() => console.log('Buy')}
/>

<PopoverButton variant="tertiary" popoverContent={
  <View>
    <Popover.Title>Information</Popover.Title>
    <Popover.Description>Additional details here</Popover.Description>
  </View>
}>
  Show Info
</PopoverButton>

```

## Custom Variants

Create custom variants using `tailwind-variants` to extend component styling:

```tsx
import { Button } from 'heroui-native';
import type { ButtonRootProps } from 'heroui-native';
import { tv, type VariantProps } from 'tailwind-variants';

const customButtonVariants = tv({
  base: 'font-semibold rounded-lg',
  variants: {
    intent: {
      primary: 'bg-blue-500 text-white',
      secondary: 'bg-gray-200',
      danger: 'bg-red-500 text-white',
    },
  },
  defaultVariants: {
    intent: 'primary',
  },
});

type CustomButtonVariants = VariantProps<typeof customButtonVariants>;

interface CustomButtonProps
  extends Omit<ButtonRootProps, 'className' | 'variant'>,
    CustomButtonVariants {
  className?: string;
}

export function CustomButton({
  intent,
  className,
  children,
  ...props
}: CustomButtonProps) {
  return (
    <Button
      className={customButtonVariants({ intent, className })}
      {...props}
    >
      <Button.Label>{children}</Button.Label>
    </Button>
  );
}

```

## Next Steps

* Learn about [Styling](/docs/native/getting-started/styling) system
* Explore [Theming](/docs/native/getting-started/theming) documentation
* Explore [Animation](/docs/native/getting-started/animation) options

</page>

<page url="/docs/native/getting-started/provider">
# Provider

**Category**: native
**URL**: https://v3.heroui.com/docs/native/getting-started/provider
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/(handbook)/provider.mdx
> Configure HeroUI Native provider with text, animation, and toast settings

The `HeroUINativeProvider` is the root provider component that configures and initializes HeroUI Native in your React Native application. It provides global configuration and portal management for your application.

## Overview

The provider serves as the main entry point for HeroUI Native, wrapping your application with essential contexts and configurations:

* **Text Configuration**: Global text component settings for consistency across all HeroUI components
* **Animation Configuration**: Global animation control to disable all animations across the application
* **Toast Configuration**: Global toast system configuration including insets, default props, and wrapper components
* **Portal Management**: Handles overlays, modals, and other components that render on top of the app hierarchy

## Basic Setup

Wrap your application root with the provider:

```tsx
import { HeroUINativeProvider } from 'heroui-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <HeroUINativeProvider>{/* Your app content */}</HeroUINativeProvider>
    </GestureHandlerRootView>
  );
}

```

## Configuration Options

The provider accepts a `config` prop with the following options:

### Text Component Configuration

Global settings for all Text components within HeroUI Native. These props are carefully selected to include only those that make sense to configure globally across all Text components in the application:

```tsx
import { HeroUINativeProvider } from 'heroui-native';
import type { HeroUINativeConfig } from 'heroui-native';

const config: HeroUINativeConfig = {
  textProps: {
    // Disable font scaling for accessibility
    allowFontScaling: false,

// Auto-adjust font size to fit container
    adjustsFontSizeToFit: false,

// Maximum font size multiplier when scaling
    maxFontSizeMultiplier: 1.5,

// Minimum font scale (iOS only, 0.01-1.0)
    minimumFontScale: 0.5,
  },
};

export default function App() {
  return (
    <HeroUINativeProvider config={config}>
      {/* Your app content */}
    </HeroUINativeProvider>
  );
}

```

### Animation Configuration

Global animation configuration for the entire application:

```tsx
const config: HeroUINativeConfig = {
  // Disable all animations across the application (cascades to all children)
  animation: 'disable-all',
};

```

<Callout type="warning">
  **Note**: When set to `'disable-all'`, all animations across the application will be disabled. This is useful for accessibility or performance optimization.
</Callout>

### Toast Configuration

Configure the global toast system including insets, default props, and wrapper components:

```tsx
import { KeyboardAvoidingView } from 'react-native';

const config: HeroUINativeConfig = {
  toast: {
    // Global toast configuration (used as defaults for all toasts)
    defaultProps: {
      variant: 'default',
      placement: 'top',
      isSwipeable: true,
      animation: true,
    },
    // Insets for spacing from screen edges (added to safe area insets)
    insets: {
      top: 0,      // Default: iOS = 0, Android = 12
      bottom: 6,   // Default: iOS = 6, Android = 12
      left: 12,    // Default: 12
      right: 12,   // Default: 12
    },
    // Maximum number of visible toasts before opacity starts fading
    maxVisibleToasts: 3,
    // Custom wrapper function to wrap the toast content
    contentWrapper: (children) => (
      <KeyboardAvoidingView
        behavior="padding"
        keyboardVerticalOffset={24}
        className="flex-1"
      >
        {children}
      </KeyboardAvoidingView>
    ),
  },
};

```

## Complete Example

Here's a comprehensive example showing all configuration options:

```tsx
import { HeroUINativeProvider } from 'heroui-native';
import type { HeroUINativeConfig } from 'heroui-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

const config: HeroUINativeConfig = {
  // Global text configuration
  textProps: {
    minimumFontScale: 0.5,
    maxFontSizeMultiplier: 1.5,
    allowFontScaling: true,
    adjustsFontSizeToFit: false,
  },
  // Global animation configuration
  animation: 'disable-all', // Optional: disable all animations
  // Global toast configuration
  toast: {
    defaultProps: {
      variant: 'default',
      placement: 'top',
    },
    insets: {
      top: 0,
      bottom: 6,
      left: 12,
      right: 12,
    },
    maxVisibleToasts: 3,
  },
};

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <HeroUINativeProvider config={config}>
        <YourApp />
      </HeroUINativeProvider>
    </GestureHandlerRootView>
  );
}

```

## Integration with Expo Router

When using Expo Router, wrap your root layout:

```tsx
// app/_layout.tsx
import { HeroUINativeProvider } from 'heroui-native';
import type { HeroUINativeConfig } from 'heroui-native';
import { Stack } from 'expo-router';

const config: HeroUINativeConfig = {
  textProps: {
    minimumFontScale: 0.5,
    maxFontSizeMultiplier: 1.5,
  },
};

export default function RootLayout() {
  return (
    <HeroUINativeProvider config={config}>
      <Stack />
    </HeroUINativeProvider>
  );
}

```

## Architecture

### Provider Hierarchy

The `HeroUINativeProvider` internally composes multiple providers:

```

HeroUINativeProvider
├── GlobalAnimationSettingsProvider (animation configuration)
│   └── TextComponentProvider (text configuration)
│       └── ToastProvider (toast configuration)
│           └── Your App
│           └── PortalHost (for overlays)

```

## Best Practices

### 1. Single Provider Instance

Always use a single `HeroUINativeProvider` at the root of your app. Don't nest multiple providers:

```tsx
// ❌ Bad
<HeroUINativeProvider>
  <SomeComponent>
    <HeroUINativeProvider> {/* Don't do this */}
      <AnotherComponent />
    </HeroUINativeProvider>
  </SomeComponent>
</HeroUINativeProvider>

// ✅ Good
<HeroUINativeProvider>
  <SomeComponent>
    <AnotherComponent />
  </SomeComponent>
</HeroUINativeProvider>

```

### 2. Configuration Object

Define your configuration outside the component to prevent recreating on each render:

```tsx
// ❌ Bad
function App() {
  return (
    <HeroUINativeProvider
      config={{
        textProps: {
          /* inline config */
        },
      }}
    >
      {/* ... */}
    </HeroUINativeProvider>
  );
}

// ✅ Good
const config: HeroUINativeConfig = {
  textProps: {
    maxFontSizeMultiplier: 1.5,
  },
};

function App() {
  return (
    <HeroUINativeProvider config={config}>{/* ... */}</HeroUINativeProvider>
  );
}

```

### 3. Text Configuration

Consider accessibility when configuring text props:

```tsx
const config: HeroUINativeConfig = {
  textProps: {
    // Allow font scaling for accessibility
    allowFontScaling: true,
    // But limit maximum scale
    maxFontSizeMultiplier: 1.5,
  },
};

```

## TypeScript Support

The provider is fully typed. Import types for better IDE support:

```tsx
import { HeroUINativeProvider, type HeroUINativeConfig } from 'heroui-native';

const config: HeroUINativeConfig = {
  // Full type safety and autocomplete
  textProps: {
    allowFontScaling: true,
    maxFontSizeMultiplier: 1.5,
  },
  animation: 'disable-all', // Optional: disable all animations
  toast: {
    defaultProps: {
      variant: 'default',
      placement: 'top',
    },
    insets: {
      top: 0,
      bottom: 6,
      left: 12,
      right: 12,
    },
  },
};

```

## Related

* [Quick Start](/docs/native/getting-started/quick-start) - Basic setup guide
* [Theming](/docs/native/getting-started/theming) - Customize colors and themes
* [Styling](/docs/native/getting-started/styling) - Style components with Tailwind

</page>

<page url="/docs/native/getting-started/styling">
# Styling

**Category**: native
**URL**: https://v3.heroui.com/docs/native/getting-started/styling
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/(handbook)/styling.mdx
> Style HeroUI Native components with Tailwind or StyleSheet API

HeroUI Native components provide flexible styling options: Tailwind CSS utilities, StyleSheet API, and render props for dynamic styling.

## Styling Principles

HeroUI Native is built with `className` as the go-to styling solution. You can use Tailwind CSS classes via the `className` prop on all components.

**StyleSheet precedence:** The `style` prop (StyleSheet API) can be used and has precedence over `className` when both are provided. This allows you to override Tailwind classes when needed.

**Animated styles:** Some style properties are animated using `react-native-reanimated` and, like StyleSheet styles, they have precedence over `className`. To identify which styles are animated and cannot be used via `className`:

* **Hover over `className` in your IDE** - The TypeScript definitions will show which properties are available
* **Check component documentation** - Each component page includes a link to the component's style source at the top, which contains notes about animated properties

**Customizing animated styles:** If styles are occupied by animation, you can modify them via the `animation` prop on components that support it.

## Basic Styling

**Using className:** All HeroUI Native components accept `className` props:

```tsx
import { Button } from 'heroui-native';

<Button className="bg-accent px-6 py-3 rounded-lg">
  <Button.Label>Custom Button</Button.Label>
</Button>

```

**Using style:** Components also accept inline styles via the `style` prop:

```tsx
import { Button } from 'heroui-native';

<Button style={{ backgroundColor: '#8B5CF6', paddingHorizontal: 24 }}>
  <Button.Label>Styled Button</Button.Label>
</Button>

```

## Render Props

Use a render function to access component state and customize content dynamically:

```tsx
import { RadioGroup, cn } from 'heroui-native';

<RadioGroup value={value} onValueChange={setValue}>
  <RadioGroup.Item value="option1">
    {({ isSelected, isInvalid, isDisabled }) => (
      <>
        <RadioGroup.Label
          className={cn(
            "text-foreground",
            isSelected && "text-accent font-semibold"
          )}
        >
          Option 1
        </RadioGroup.Label>
        <RadioGroup.Indicator
          className={cn(
            "border-2 rounded-full",
            isSelected && "border-accent bg-accent"
          )}
        >
          {isSelected && <CustomIcon />}
        </RadioGroup.Indicator>
      </>
    )}
  </RadioGroup.Item>
</RadioGroup>

```

## Creating Wrapper Components

Create reusable custom components using [tailwind-variants](https://tailwind-variants.org/)—a Tailwind CSS first-class variant API:

```tsx
import { Button } from 'heroui-native';
import type { ButtonRootProps } from 'heroui-native';
import { tv, type VariantProps } from 'tailwind-variants';

type CustomButtonVariants = VariantProps<typeof customButtonVariants>;

interface CustomButtonProps
  extends Omit<ButtonRootProps, 'className' | 'variant'>,
    CustomButtonVariants {
  className?: string;
}

```

## Responsive Design

HeroUI Native supports Tailwind's responsive breakpoint system via [Uniwind](https://docs.uniwind.dev/breakpoints). Use breakpoint prefixes like `sm:`, `md:`, `lg:`, and `xl:` to apply styles conditionally based on screen width.

**Mobile-first approach:** Start with mobile styles (no prefix), then use breakpoints to enhance for larger screens.

### Responsive Typography and Spacing

```tsx
import { Button } from 'heroui-native';
import { View, Text } from 'react-native';

<View className="px-4 sm:px-6 lg:px-8 py-6 sm:py-8">
  <Text className="text-2xl sm:text-3xl lg:text-4xl font-bold mb-4 sm:mb-6">
    Responsive Heading
  </Text>
  <Button className="px-3 sm:px-4 lg:px-6">
    <Button.Label className="text-sm sm:text-base lg:text-lg">
      Responsive Button
    </Button.Label>
  </Button>
</View>

```

### Responsive Layouts

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

<View className="flex-row flex-wrap">
  {/* Mobile: 1 column, Tablet: 2 columns, Desktop: 3 columns */}
  <View className="w-full sm:w-1/2 lg:w-1/3 p-2">
    <View className="bg-accent p-4 rounded-lg">
      <Text className="text-accent-foreground">Item 1</Text>
    </View>
  </View>
</View>

```

**Default breakpoints:**

* `sm`: 640px
* `md`: 768px
* `lg`: 1024px
* `xl`: 1280px
* `2xl`: 1536px

For custom breakpoints and more details, see the [Uniwind breakpoints documentation](https://docs.uniwind.dev/breakpoints).

## Utilities

HeroUI Native provides utility functions to assist with styling components.

### cn Utility

The `cn` utility function merges Tailwind CSS classes with proper conflict resolution. It's particularly useful when combining conditional classes or merging classes from props:

```tsx
import { cn } from 'heroui-native';
import { View } from 'react-native';

function MyComponent({ className, isActive }) {
  return (
    <View
      className={cn(
        'bg-background p-4 rounded-lg',
        'border border-divider',
        isActive && 'bg-accent',
        className
      )}
    />
  );
}

```

The `cn` utility is powered by `tailwind-variants` and includes:

* Automatic Tailwind class merging (`twMerge: true`)
* Custom opacity class group support
* Proper conflict resolution (later classes override earlier ones)

**Example with conflicts:**

```tsx
// 'bg-accent' overrides 'bg-background'
cn('bg-background p-4', 'bg-accent');
// Result: 'p-4 bg-accent'

```

### useThemeColor Hook

Quick access to theme colors in hex format for use with the `style` prop:

```tsx
import { useThemeColor } from 'heroui-native';
import { View, Text } from 'react-native';

function MyComponent() {
  const accentColor = useThemeColor('accent');
  const dangerColor = useThemeColor('danger');

return (
    <View style={{ borderColor: accentColor }}>
      <Text style={{ color: dangerColor }}>Error message</Text>
    </View>
  );
}

```

**Type signature:**

```tsx
useThemeColor(themeColor: ThemeColor): string

```

Available theme colors include: `background`, `foreground`, `surface`, `accent`, `default`, `success`, `warning`, `danger`, and all their variants (hover, soft, etc.).

## Next Steps

* Learn about [Animation](/docs/native/getting-started/animation) techniques
* Explore [Theming](/docs/native/getting-started/theming) system
* Explore [Colors](/docs/native/getting-started/colors) documentation

</page>

<page url="/docs/native/getting-started/theming">
# Theming

**Category**: native
**URL**: https://v3.heroui.com/docs/native/getting-started/theming
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/(handbook)/theming.mdx
> Customize HeroUI Native's design system with CSS variables and global styles

HeroUI Native uses CSS variables for theming. Customize everything from colors to component styles using standard CSS.

## How It Works

HeroUI Native's theming system is built on top of [Tailwind CSS v4](https://tailwindcss.com/docs/theme)'s theme via [Uniwind](https://uniwind.dev/). When you import `heroui-native/styles`, it uses Tailwind's built-in color palettes, maps them to semantic variables, automatically switches between light and dark themes, and uses CSS layers and the `@theme` directive for organization.

**Naming pattern:**

* Colors without a suffix are backgrounds (e.g., `--accent`)
* Colors with `-foreground` are for text on that background (e.g., `--accent-foreground`)

## Quick Start

**Apply colors in your components:**

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

<View className="bg-background flex-1">
  <Text className="text-foreground">Your app content</Text>
</View>

```

**Switch themes:**

HeroUI Native automatically supports dark mode through [Uniwind](https://docs.uniwind.dev/theming/basics). The theme switches between light and dark variants based on system preferences or manual selection:

```tsx
import { Uniwind, useUniwind } from 'uniwind';
import { Button } from 'heroui-native';

function ThemeToggle() {
  const { theme } = useUniwind();

return (
    <Button
      onPress={() => Uniwind.setTheme(theme === 'light' ? 'dark' : 'light')}
    >
      <Button.Label>Toggle {theme === 'light' ? 'Dark' : 'Light'} Mode</Button.Label>
    </Button>
  );
}

```

**Override colors:**

```css
/* global.css */
@layer theme {
  @variant light {
    /* Override any color variable */
    --accent: oklch(0.65 0.25 270); /* Custom indigo accent */
    --success: oklch(0.65 0.15 155);
  }

@variant dark {
    --accent: oklch(0.65 0.25 270);
    --success: oklch(0.75 0.12 155);
  }
}

```

> **Note**: See [Colors](/docs/native/getting-started/colors) for the complete color palette and visual reference.

**Create your own theme:**

Create multiple themes using Uniwind's variant system. For complete custom theme documentation, see the [Uniwind Custom Themes Guide](https://docs.uniwind.dev/theming/custom-themes).

<Callout type="warning">
  **Important:** All themes must define the same variables. See the [Default Theme](/docs/native/getting-started/colors#default-theme) section for a complete list of all required variables.
</Callout>

```css
/* global.css */
@layer theme {
  :root {
    @variant ocean-light {
      /* Base Colors */
      --background: oklch(0.95 0.02 230);
      --foreground: oklch(0.25 0.04 230);

/* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
      --surface: oklch(0.98 0.01 230);
      --surface-foreground: oklch(0.3 0.045 230);

/* Overlay: Used for floating/overlay components (dialogs, popovers, modals, menus) */
      --overlay: oklch(0.998 0.003 230);
      --overlay-foreground: oklch(0.3 0.045 230);

--muted: oklch(0.55 0.035 230);

--default: oklch(0.94 0.018 230);
      --default-foreground: oklch(0.4 0.05 230);

/* Accent */
      --accent: oklch(0.6 0.2 230);
      --accent-foreground: oklch(0.98 0.005 230);

/* Form Field Defaults - Colors */
      --field-background: oklch(0.98 0.01 230);
      --field-foreground: oklch(0.25 0.04 230);
      --field-placeholder: var(--muted);
      --field-border: transparent;

/* Status Colors */
      --success: oklch(0.72 0.14 165);
      --success-foreground: oklch(0.25 0.08 165);

--warning: oklch(0.78 0.12 85);
      --warning-foreground: oklch(0.3 0.08 85);

--danger: oklch(0.68 0.18 15);
      --danger-foreground: oklch(0.98 0.005 15);

/* Component Colors */
      --segment: oklch(0.98 0.01 230);
      --segment-foreground: oklch(0.25 0.04 230);

/* Misc Colors */
      --border: oklch(0 0 0 / 0%);
      --divider: oklch(0.91 0.015 230);
      --link: oklch(0.62 0.17 230);
    }

@variant ocean-dark {
      /* Base Colors */
      --background: oklch(0.15 0.04 230);
      --foreground: oklch(0.94 0.01 230);

/* Surface: Used for non-overlay components (cards, accordions, disclosure groups) */
      --surface: oklch(0.2 0.048 230);
      --surface-foreground: oklch(0.9 0.015 230);

/* Overlay: Used for floating/overlay components (dialogs, popovers, modals, menus) */
      --overlay: oklch(0.23 0.045 230);
      --overlay-foreground: oklch(0.9 0.015 230);

--muted: oklch(0.5 0.04 230);

--default: oklch(0.25 0.05 230);
      --default-foreground: oklch(0.88 0.018 230);

/* Accent */
      --accent: oklch(0.72 0.21 230);
      --accent-foreground: oklch(0.15 0.04 230);

/* Form Field Defaults - Colors */
      --field-background: var(--default);
      --field-foreground: var(--foreground);
      --field-placeholder: var(--muted);
      --field-border: transparent;

/* Status Colors */
      --success: oklch(0.68 0.16 165);
      --success-foreground: oklch(0.95 0.008 165);

--warning: oklch(0.75 0.14 90);
      --warning-foreground: oklch(0.2 0.04 90);

--danger: oklch(0.65 0.2 20);
      --danger-foreground: oklch(0.95 0.008 20);

/* Component Colors */
      --segment: oklch(0.22 0.046 230);
      --segment-foreground: oklch(0.9 0.015 230);

/* Misc Colors */
      --border: oklch(0 0 0 / 0%);
      --divider: oklch(0.28 0.045 230);
      --link: oklch(0.75 0.18 230);
    }
  }
}

```

**Important:** When adding custom themes, you must register them in your Metro config:

```js
// metro.config.js
const { withUniwindConfig } = require('uniwind/metro');
const { wrapWithReanimatedMetroConfig } = require('react-native-reanimated/metro-config');

const config = {
  // ... your existing config
};

module.exports = withUniwindConfig(wrapWithReanimatedMetroConfig(config), {
  cssEntryFile: './global.css',
  dtsFile: './src/uniwind.d.ts',
  extraThemes: [
    'ocean-light',
    'ocean-dark',
  ],
});

```

Apply themes in your app:

```tsx
import { Uniwind } from 'uniwind';
import { Button } from 'heroui-native';

function App() {
  return (
    <Button onPress={() => Uniwind.setTheme('ocean-light')}>
      <Button.Label>Ocean Theme</Button.Label>
    </Button>
  );
}

```

## Adding Custom Colors

Add your own semantic colors to the theme:

```css
@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);
  }
}

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

```

Now use it in your components:

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

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

```

## Custom Fonts

To use a custom font family in your app, you need to load the fonts and then override the font CSS variables.

### 1. Load Fonts in Your App

First, load your custom fonts (using Expo's `useFonts` hook for example):

```tsx
import { useFonts } from 'expo-font';
import { HeroUINativeProvider } from 'heroui-native';
import { YourFont_400Regular, YourFont_500Medium, YourFont_600SemiBold } from '@expo-google-fonts/your-font';

export default function App() {
  const [fontsLoaded] = useFonts({
    YourFont_400Regular,
    YourFont_500Medium,
    YourFont_600SemiBold,
  });

if (!fontsLoaded) {
    return null; // Or return a loading screen
  }

return (
    <HeroUINativeProvider>
      {/* Your app content */}
    </HeroUINativeProvider>
  );
}

```

### 2. Configure Font CSS Variables

After loading the fonts, override the font CSS variables in your `global.css` file:

```css
@theme {
  --font-normal: 'YourFont-Regular';
  --font-medium: 'YourFont-Medium';
  --font-semibold: 'YourFont-SemiBold';
}

```

**Note:** The font names in CSS variables should match the PostScript names of your loaded fonts. Check your font package documentation or use the font names exactly as they appear in your `useFonts` hook.

All HeroUI Native components automatically use these font variables, ensuring consistent typography throughout your app.

## Variables Reference

HeroUI defines three types of variables:

1. **Base Variables** — Non-changing values like `--white`, `--black`
2. **Theme Variables** — Colors that change between light/dark themes
3. **Calculated Variables** — Automatically generated hover (pressed) states and size variants

For a complete reference, see: [Colors Documentation](/docs/native/getting-started/colors), [Default Theme Variables](https://github.com/heroui-inc/heroui-native/blob/beta/src/styles/variables.css), [Shared Theme Utilities](https://github.com/heroui-inc/heroui-native/blob/beta/src/styles/theme.css)

**Calculated variables (Tailwind):**

We use Tailwind's `@theme` directive to automatically create calculated variables for hover (pressed) states and radius variants. These are defined in [theme.css](https://github.com/heroui-inc/heroui-native/blob/beta/src/styles/theme.css):

```css
  @theme inline static {
    --color-background: var(--background);
    --color-foreground: var(--foreground);

--color-surface: var(--surface);
    --color-surface-foreground: var(--surface-foreground);

--color-overlay: var(--overlay);
    --color-overlay-foreground: var(--overlay-foreground);

--color-muted: var(--muted);

--color-accent: var(--accent);
    --color-accent-foreground: var(--accent-foreground);

--color-segment: var(--segment);
    --color-segment-foreground: var(--segment-foreground);

--color-border: var(--border);
    --color-divider: var(--divider);
    --color-focus: var(--focus);
    --color-link: var(--link);

--color-default: var(--default);
    --color-default-foreground: var(--default-foreground);

--color-success: var(--success);
    --color-success-foreground: var(--success-foreground);

--color-warning: var(--warning);
    --color-warning-foreground: var(--warning-foreground);

--color-danger: var(--danger);
    --color-danger-foreground: var(--danger-foreground);

/* Form Field Tokens */
    --color-field: var(--field-background, var(--color-default));
    --color-field-hover: color-mix(
      in oklab,
      var(--field-background, var(--color-default)) 90%,
      var(--field-foreground, var(--color-default-foreground)) 10%
    );
    --color-field-foreground: var(--field-foreground, var(--color-foreground));
    --color-field-placeholder: var(--field-placeholder, var(--color-muted));
    --color-field-border: var(--field-border, var(--color-border));
    --radius-field: var(--field-radius, var(--radius-xl));
    --border-width-field: var(--field-border-width, var(--border-width));

/* Calculated Variables */

/* Colors */

/* --- background shades --- */
    --color-background-secondary: color-mix(
      in oklab,
      var(--color-background) 96%,
      var(--color-foreground) 4%
    );
    --color-background-tertiary: color-mix(
      in oklab,
      var(--color-background) 92%,
      var(--color-foreground) 8%
    );
    --color-background-quaternary: color-mix(
      in oklab,
      var(--color-background) 86%,
      var(--color-foreground) 14%
    );
    --color-background-inverse: var(--color-foreground);

/* ------------------------- */
    --color-default-hover: color-mix(
      in oklab,
      var(--color-default) 90%,
      var(--color-default-foreground) 2%
    );
    --color-accent-hover: color-mix(
      in oklab,
      var(--color-accent) 90%,
      var(--color-accent-foreground) 10%
    );
    --color-success-hover: color-mix(
      in oklab,
      var(--color-success) 90%,
      var(--color-success-foreground) 10%
    );
    --color-warning-hover: color-mix(
      in oklab,
      var(--color-warning) 90%,
      var(--color-warning-foreground) 10%
    );
    --color-danger-hover: color-mix(
      in oklab,
      var(--color-danger) 90%,
      var(--color-danger-foreground) 10%
    );

/* Form Field Colors */
    --color-field-hover: color-mix(
      in oklab,
      var(--color-field) 90%,
      var(--color-field-foreground) 2%
    );
    --color-field-focus: var(--color-field);
    --color-field-border-hover: color-mix(
      in oklab,
      var(--color-field-border) 88%,
      var(--color-field-foreground) 10%
    );
    --color-field-border-focus: color-mix(
      in oklab,
      var(--color-field-border) 74%,
      var(--color-field-foreground) 22%
    );

/* Soft Colors */
    --color-accent-soft: color-mix(
      in oklab,
      var(--color-accent) 15%,
      transparent
    );
    --color-accent-soft-foreground: var(--color-accent);
    --color-accent-soft-hover: color-mix(
      in oklab,
      var(--color-accent) 20%,
      transparent
    );

--color-danger-soft: color-mix(
      in oklab,
      var(--color-danger) 15%,
      transparent
    );
    --color-danger-soft-foreground: var(--color-danger);
    --color-danger-soft-hover: color-mix(
      in oklab,
      var(--color-danger) 20%,
      transparent
    );

--color-warning-soft: color-mix(
      in oklab,
      var(--color-warning) 15%,
      transparent
    );
    --color-warning-soft-foreground: var(--color-warning);
    --color-warning-soft-hover: color-mix(
      in oklab,
      var(--color-warning) 20%,
      transparent
    );

--color-success-soft: color-mix(
      in oklab,
      var(--color-success) 15%,
      transparent
    );
    --color-success-soft-foreground: var(--color-success);
    --color-success-soft-hover: color-mix(
      in oklab,
      var(--color-success) 20%,
      transparent
    );

/* Surface Levels - progressively darker/lighter shades for layering */
    --color-surface-secondary: color-mix(
      in oklab,
      var(--surface) 94%,
      var(--surface-foreground) 6%
    );
    --color-surface-tertiary: color-mix(
      in oklab,
      var(--surface) 92%,
      var(--surface-foreground) 8%
    );
    --color-surface-quaternary: color-mix(
      in oklab,
      var(--surface) 86%,
      var(--default-foreground) 14%
    );

/* On Surface Colors */
    --color-on-surface: color-mix(
      in oklab,
      var(--color-surface) 93%,
      var(--color-surface-foreground) 7%
    );
    --color-on-surface-foreground: var(--color-surface-foreground);
    --color-on-surface-hover: color-mix(
      in oklab,
      var(--color-surface) 91%,
      var(--color-surface-foreground) 9%
    );
    --color-on-surface-focus: var(--color-on-surface);

/* Radius and default sizes - defaults can change by just changing the --radius */
    --radius-xs: calc(var(--radius) * 0.25); /* 0.125rem (2px) */
    --radius-sm: calc(var(--radius) * 0.5); /* 0.25rem (4px) */
    --radius-md: calc(var(--radius) * 0.75); /* 0.375rem (6px) */
    --radius-lg: calc(var(--radius) * 1); /* 0.5rem (8px) */
    --radius-xl: calc(var(--radius) * 1.5); /* 0.75rem (12px) */
    --radius-2xl: calc(var(--radius) * 2); /* 1rem (16px) */
    --radius-3xl: calc(var(--radius) * 3); /* 1.5rem (24px) */
    --radius-4xl: calc(var(--radius) * 4); /* 2rem (32px) */
  }

```

Form controls now rely on the `--field-*` variables and their calculated hover/focus variants. Update them in your theme to restyle inputs, checkboxes, radios, and OTP slots without impacting surfaces like buttons or cards.

## Resources

* [Colors Documentation](/docs/native/getting-started/colors)
* [Styling Guide](/docs/native/getting-started/styling)
* [Tailwind CSS v4 Theming](https://tailwindcss.com/docs/theme)
* [OKLCH Color Tool](https://oklch.com)

</page>

<page url="/docs/native/getting-started/design-principles">
# Design Principles

**Category**: native
**URL**: https://v3.heroui.com/docs/native/getting-started/design-principles
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/(overview)/design-principles.mdx
> Core principles that guide HeroUI v3's design and development

HeroUI Native follows 9 core principles that prioritize clarity, accessibility, customization, and developer experience.

## Core Principles

### 1. Semantic Intent Over Visual Style

Use semantic naming (primary, secondary, tertiary) instead of visual descriptions (solid, flat, bordered). Inspired by [Uber's Base design system](https://base.uber.com/6d2425e9f/p/756216-button), variants follow a clear hierarchy:

```tsx
// ✅ Semantic variants communicate hierarchy
<Button variant="primary">Save</Button>
<Button variant="secondary">Edit</Button>
<Button variant="tertiary">Cancel</Button>

```

| Variant       | Purpose                           | Usage            |
| ------------- | --------------------------------- | ---------------- |
| **Primary**   | Main action to move forward       | 1 per context    |
| **Secondary** | Alternative actions               | Multiple allowed |
| **Tertiary**  | Dismissive actions (cancel, skip) | Sparingly        |
| **Danger**    | Destructive actions               | When needed      |

### 2. Accessibility as Foundation

Accessibility follows mobile development best practices with proper touch accessibility, focus management, and screen reader support built into every component. All components include proper accessibility labels and semantic structure for VoiceOver (iOS) and TalkBack (Android).

```tsx
import { Tabs } from 'heroui-native';

<Tabs value="profile" onValueChange={setActiveTab}>
  <Tabs.List>
    <Tabs.Indicator />
    <Tabs.Trigger value="profile">
      <Tabs.Label>Profile</Tabs.Label>
    </Tabs.Trigger>
    <Tabs.Trigger value="security">
      <Tabs.Label>Security</Tabs.Label>
    </Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="profile">Content</Tabs.Content>
  <Tabs.Content value="security">Content</Tabs.Content>
</Tabs>

```

### 3. Composition Over Configuration

Compound components let you rearrange, customize, or omit parts as needed. Use dot notation to compose components exactly as you need them.

```tsx
// Compose parts to build exactly what you need
import { Accordion } from 'heroui-native';

<Accordion>
  <Accordion.Item value="1">
    <Accordion.Trigger>
      Question Text
      <Accordion.Indicator />
    </Accordion.Trigger>
    <Accordion.Content>Answer content</Accordion.Content>
  </Accordion.Item>
</Accordion>

```

### 4. Progressive Disclosure

Start simple, add complexity only when needed. Components work with minimal props and scale up as requirements grow.

```tsx
import { Button, Icon, Spinner } from 'heroui-native';

// Level 1: Minimal
<Button>Click me</Button>

// Level 2: Enhanced
<Button variant="primary" size="lg">
  <Icon name="check" size={20} />
  <Button.Label>Submit</Button.Label>
</Button>

// Level 3: Advanced
<Button variant="primary" isDisabled={isLoading}>
  {isLoading ? (
    <>
      <Spinner size="sm" />
      <Button.Label>Loading...</Button.Label>
    </>
  ) : (
    <Button.Label>Submit</Button.Label>
  )}
</Button>

```

### 5. Predictable Behavior

Consistent patterns across all components: sizes (`sm`, `md`, `lg`), variants, and className support. Same API, same behavior.

```tsx
import { Button, Chip, Avatar } from 'heroui-native';

// All components follow the same patterns
<Button size="lg" variant="primary" className="custom">
  <Button.Label>Click me</Button.Label>
</Button>
<Chip size="lg" color="success" className="custom">
  <Chip.Label>Success</Chip.Label>
</Chip>
<Avatar size="lg" className="custom">
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

```

### 6. Type Safety First

Full TypeScript support with IntelliSense, auto-completion, and compile-time error detection. Extend types for custom components.

```tsx
import type { ButtonRootProps } from 'heroui-native';

// Type-safe props and event handlers
<Button
  variant="primary"  // Autocomplete: primary | secondary | tertiary | ghost | danger | danger-soft
  size="md"          // Type checked: sm | md | lg
  onPress={() => {   // Properly typed press handler
    console.log('Button pressed');
  }}
>
  <Button.Label>Click me</Button.Label>
</Button>

// Extend types for custom components
interface CustomButtonProps extends Omit<ButtonRootProps, 'variant'> {
  intent: 'save' | 'cancel' | 'delete';
}

```

### 7. Developer Experience Excellence

Clear APIs, descriptive errors, IntelliSense and AI-friendly markdown docs.

### 8. Complete Customization

Beautiful defaults out-of-the-box. Transform the entire look with CSS variables through [Uniwind's theming system](https://docs.uniwind.dev/theming/basics). Every slot is customizable.

```css
/* Custom colors using Uniwind's theme layer */
@layer theme {
  @variant light {
    --accent: oklch(0.65 0.25 270); /* Custom indigo accent */
    --background: oklch(0.98 0 0);  /* Custom background */
  }

@variant dark {
    --accent: oklch(0.65 0.25 270);
    --background: oklch(0.15 0 0);
  }
}

/* Radius customization */
@theme {
  --radius: 0.75rem; /* Increase for rounder components */
}

```

### 9. Open and Extensible

Wrap, extend, and customize components to match your needs. Create custom wrappers or apply custom styles using className.

```tsx
import { Button } from 'heroui-native';
import type { ButtonRootProps } from 'heroui-native';

// Custom wrapper component
interface CTAButtonProps extends Omit<ButtonRootProps, 'variant'> {
  intent?: 'primary-cta' | 'secondary-cta' | 'minimal';
}

const CTAButton = ({
  intent = 'primary-cta',
  children,
  ...props
}: CTAButtonProps) => {
  const variantMap = {
    'primary-cta': 'primary',
    'secondary-cta': 'secondary',
    'minimal': 'ghost'
  } as const;

return (
    <Button variant={variantMap[intent]} {...props}>
      <Button.Label>{children}</Button.Label>
    </Button>
  );
};

// Usage
<CTAButton intent="primary-cta">Get Started</CTAButton>
<CTAButton intent="secondary-cta">Learn More</CTAButton>

```

**Extend with Tailwind Variants:**

```tsx
import { Button } from 'heroui-native';
import { tv } from 'tailwind-variants';

// Extend button styles with custom variants
const myButtonVariants = tv({
  base: 'px-4 py-2 rounded-lg',
  variants: {
    variant: {
      'primary-cta': 'bg-accent text-accent-foreground px-8 py-4 shadow-lg',
      'secondary-cta': 'border-2 border-accent text-accent px-6 py-3',
    }
  },
  defaultVariants: {
    variant: 'primary-cta',
  }
});

// Use the custom variants
function CustomButton({ variant, className, ...props }) {
  return (
    <Button className={myButtonVariants({ variant, className })} {...props}>
      <Button.Label>Get Started</Button.Label>
    </Button>
  );
}

// Usage
<CustomButton variant="primary-cta">Get Started</CustomButton>
<CustomButton variant="secondary-cta">Learn More</CustomButton>

```

</page>

<page url="/docs/native/getting-started/quick-start">
# Quick Start

**Category**: native
**URL**: https://v3.heroui.com/docs/native/getting-started/quick-start
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/(overview)/quick-start.mdx
> Get started with HeroUI Native in minutes

## Getting Started

### 1. Install HeroUI Native

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    ```bash
    npm install heroui-native
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm add heroui-native
    ```
  </Tab>

<Tab value="yarn">
    ```bash
    yarn add heroui-native
    ```
  </Tab>

<Tab value="bun">
    ```bash
    bun add heroui-native
    ```
  </Tab>
</Tabs>

### 2. Install Mandatory Peer Dependencies

<Tabs items={["npm", "pnpm", "yarn", "bun"]}>
  <Tab value="npm">
    ```bash
    npm install react-native-screens@~4.16.0 react-native-reanimated@~4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@0.5.1 react-native-safe-area-context@~5.6.0 react-native-svg@15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0 @gorhom/bottom-sheet@^5
    ```
  </Tab>

<Tab value="pnpm">
    ```bash
    pnpm add react-native-screens@~4.16.0 react-native-reanimated@~4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@0.5.1 react-native-safe-area-context@~5.6.0 react-native-svg@15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0 @gorhom/bottom-sheet@^5
    ```
  </Tab>

<Tab value="yarn">
    ```bash
    yarn add react-native-screens@~4.16.0 react-native-reanimated@~4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@0.5.1 react-native-safe-area-context@~5.6.0 react-native-svg@15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0 @gorhom/bottom-sheet@^5
    ```
  </Tab>

<Tab value="bun">
    ```bash
    bun add react-native-screens@~4.16.0 react-native-reanimated@~4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@0.5.1 react-native-safe-area-context@~5.6.0 react-native-svg@15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0 @gorhom/bottom-sheet@^5
    ```
  </Tab>
</Tabs>

<Callout type="warning">
  It's recommended to use the exact versions specified above to avoid compatibility issues. Version mismatches may cause unexpected bugs.
</Callout>

### 3. Set Up Uniwind

Follow the [Uniwind installation guide](https://docs.uniwind.dev/quickstart) to set up Tailwind CSS for React Native.

If you're migrating from NativeWind, see the [migration guide](https://docs.uniwind.dev/migration-from-nativewind).

### 4. Configure global.css

Inside your `global.css` file add the following imports:

```css
@import 'tailwindcss';
@import 'uniwind';

@import 'heroui-native/styles';

/* Path to the heroui-native lib inside node_modules from the root of your project */
@source './node_modules/heroui-native/lib';

```

### 5. Wrap Your App with Provider

Wrap your application with `HeroUINativeProvider`. You must wrap it with `GestureHandlerRootView`:

```tsx
import { HeroUINativeProvider } from 'heroui-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

```

> **Note**: For advanced configuration options including text props, animation settings, and toast configuration, see the [Provider documentation](/docs/native/getting-started/provider).

### 6. Use Your First Component

```tsx
import { Button } from 'heroui-native';
import { View } from 'react-native';

export default function MyComponent() {
  return (
    <View className="flex-1 justify-center items-center bg-background">
      <Button onPress={() => console.log('Pressed!')}>Get Started</Button>
    </View>
  );
}

```

## What's Next?

* [HeroUI Native Provider](/docs/native/getting-started/provider)
* [Styling Guide](/docs/native/getting-started/styling)
* [Theming Documentation](/docs/native/getting-started/theming)

## Running on Web (Expo)

<Callout type="warning">
  HeroUI Native is currently not recommended for web use. We are focusing on mobile platforms (iOS and Android) at this time.
</Callout>

</page>

<page url="/docs/native/getting-started/llms-txt">
# LLMs.txt

**Category**: native
**URL**: https://v3.heroui.com/docs/native/getting-started/llms-txt
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/(ui-for-agents)/llms-txt.mdx
> Enable AI assistants like Claude, Cursor, and Windsurf to understand HeroUI Native

We provide [LLMs.txt](https://llmstxt.org/) files to make HeroUI Native documentation accessible to AI coding assistants.

## Available Files

**Core documentation:**

* [/native/llms.txt](/native/llms.txt) — Quick reference index for Native documentation
* [/native/llms-full.txt](/native/llms-full.txt) — Complete HeroUI Native documentation

**For limited context windows:**

* [/native/llms-components.txt](/native/llms-components.txt) — Component documentation only
* [/native/llms-patterns.txt](/native/llms-patterns.txt) — Common patterns and recipes

**All platforms:**

* [/llms.txt](/llms.txt) — Quick reference index (React + Native)
* [/llms-full.txt](/llms-full.txt) — Complete documentation (React + Native)
* [/llms-components.txt](/llms-components.txt) — All component documentation
* [/llms-patterns.txt](/llms-patterns.txt) — All patterns and recipes

## Integration

**Claude Code:** Tell Claude to reference the documentation:

```
Use HeroUI Native documentation from https://v3.heroui.com/native/llms.txt

```

Or add to your project's `.claude` file for automatic loading.

**Cursor:** Use the `@Docs` feature:

```
@Docs https://v3.heroui.com/native/llms-full.txt

```

[Learn more](https://docs.cursor.com/context/@-symbols/@-docs)

**Windsurf:** Add to your `.windsurfrules` file:

```
#docs https://v3.heroui.com/native/llms-full.txt

```

[Learn more](https://docs.codeium.com/windsurf/memories#memories-and-rules)

**Other AI tools:** Most AI assistants can reference documentation by URL. Simply provide:

```
https://v3.heroui.com/native/llms.txt

```

**For component-specific documentation:**

```

https://v3.heroui.com/native/llms-components.txt

```

**For patterns and best practices:**

```

https://v3.heroui.com/native/llms-patterns.txt

```

## Contributing

Found an issue with AI-generated code? Help us improve our LLMs.txt files on [GitHub](https://github.com/heroui-inc/heroui).

</page>

<page url="/docs/native/getting-started/mcp-server">
# MCP Server

**Category**: native
**URL**: https://v3.heroui.com/docs/native/getting-started/mcp-server
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/getting-started/(ui-for-agents)/mcp-server.mdx
> Access HeroUI Native documentation directly in your AI assistant

The HeroUI MCP Server gives AI assistants direct access to HeroUI Native component documentation, making it easier to build with HeroUI in AI-powered development environments.

The MCP server currently supports **heroui-native** and [stdio transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio). Published at `@heroui/native-mcp` on npm. View the source code on [GitHub](https://github.com/heroui-inc/heroui-mcp).

<Callout>
  As we add more components to HeroUI Native, they'll be available in the MCP server too.
</Callout>

## Quick Setup

**Cursor:**

<span>Install in Cursor</span>
  </a>
</div>

Or manually add to **Cursor Settings** → **Tools** → **MCP Servers**:

```json title=".cursor/mcp.json"
{
  "mcpServers": {
    "heroui-native": {
      "command": "npx",
      "args": ["-y", "@heroui/native-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-native -- npx -y @heroui/native-mcp@latest

```

Or manually add to your project's `.mcp.json` file:

```json title=".mcp.json"
{
  "mcpServers": {
    "heroui-native": {
      "command": "npx",
      "args": ["-y", "@heroui/native-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-native": {
      "command": "npx",
      "args": ["-y", "@heroui/native-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.

**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"
{
  "mcpServers": {
    "heroui-native": {
      "command": "npx",
      "args": ["-y", "@heroui/native-mcp@latest"]
    }
  }
}

```

After adding the configuration, open `.vscode/mcp.json` and click **Start** next to the heroui-native server.

See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more details.

## Usage

Once configured, ask your AI assistant questions like:

* "Help me install HeroUI Native in my Expo app"
* "Show me all HeroUI Native 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 default styles for Card"
* "What are the theme variables for dark mode?"

### Automatic Updates

The MCP server can help you upgrade to the latest HeroUI Native version:

```bash
"Hey Cursor, update HeroUI Native 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 alpha, beta, or stable release.

## Available Tools

The MCP server provides these tools to AI assistants:

| Tool                     | Description                                                                                                        |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `installation`           | Get complete installation instructions for your specific framework (Expo or Bare React Native) and package manager |
| `list_components`        | List all available HeroUI Native components                                                                        |
| `get_component_info`     | Get detailed documentation, anatomy, props, and examples for specific components                                   |
| `get_component_props`    | Get detailed props information for HeroUI Native components                                                        |
| `get_component_examples` | Get usage examples for HeroUI Native components                                                                    |
| `get_theme_info`         | Access theme variables for colors, typography, spacing with light/dark mode support                                |
| `get_docs`               | Browse the full HeroUI Native documentation including guides and principles                                        |

## Troubleshooting

**Requirements:** Node.js 18 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/native-mcp)
* [GitHub Repository](https://github.com/heroui-inc/heroui-mcp)
* [Contributing Guide](https://github.com/heroui-inc/heroui-mcp/blob/main/CONTRIBUTING.md)

</page>

<page url="/docs/native/components/button">
# Button

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/button
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(buttons)/button.mdx
> Interactive component that triggers an action when pressed.

## Import

```tsx
import { Button } from 'heroui-native';

```

## Anatomy

```tsx
<Button>
  <Button.Label>...</Button.Label>
</Button>

```

* **Button**: Main container that handles press interactions, animations, and variants. Renders string children as label or accepts compound components for custom layouts.
* **Button.Label**: Text content of the button. Inherits size and variant styling from parent Button context.

## Usage

### Basic Usage

The Button component accepts string children that automatically render as label.

```tsx
<Button>Basic Button</Button>

```

### With Compound Parts

Use Button.Label for explicit control over the label component.

```tsx
<Button>
  <Button.Label>Click me</Button.Label>
</Button>

```

### With Icons

Combine icons with labels for enhanced visual communication.

```tsx
<Button>
  <Icon name="add" size={20} />
  <Button.Label>Add Item</Button.Label>
</Button>

<Button>
  <Button.Label>Download</Button.Label>
  <Icon name="download" size={18} />
</Button>

```

### Icon Only

Create square icon-only buttons using the isIconOnly prop.

```tsx
<Button isIconOnly>
  <Icon name="heart" size={18} />
</Button>

```

### Sizes

Control button dimensions with three size options.

```tsx
<Button size="sm">Small</Button>
<Button size="md">Medium</Button>
<Button size="lg">Large</Button>

```

### Variants

Choose from six visual variants for different emphasis levels.

```tsx
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="tertiary">Tertiary</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="danger">Danger</Button>
<Button variant="danger-soft">Danger Soft</Button>

```

### Feedback Variants

Choose between highlight and ripple feedback effects for press interactions.

```tsx
{
  /* Highlight feedback (default) */
}
<Button feedbackVariant="highlight">Highlight Effect</Button>;

{
  /* Ripple feedback */
}
<Button feedbackVariant="ripple">Ripple Effect</Button>;

{
  /* Customize ripple animation */
}
<Button
  feedbackVariant="ripple"
  animation={{
    ripple: {
      backgroundColor: { value: '#3b82f6' },
      opacity: { value: [0, 0.3, 0] },
    },
  }}
>
  Custom Ripple
</Button>;

```

### Loading State with Spinner

Transform button to loading state with spinner animation.

```tsx
const themeColorAccentForeground = useThemeColor('accent-foreground');

<Button
  layout={LinearTransition.springify()}
  variant="primary"
  onPress={() => {
    setIsDownloading(true);
    setTimeout(() => {
      setIsDownloading(false);
    }, 3000);
  }}
  isIconOnly={isDownloading}
  className="self-center"
>
  {isDownloading ? (
    <Spinner entering={FadeIn.delay(50)} color={themeColorAccentForeground} />
  ) : (
    'Download now'
  )}
</Button>;

```

### Custom Background with LinearGradient

Add gradient backgrounds using absolute positioned elements.

```tsx
<Button>
  <LinearGradient
    colors={['#9333ea', '#ec4899']}
    start={{ x: 0, y: 0 }}
    end={{ x: 1, y: 0 }}
    style={StyleSheet.absoluteFill}
  />
  <Button.Label className="text-white font-bold">Gradient</Button.Label>
</Button>

```

## Example

```tsx
import { Button, useThemeColor } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import { View } from 'react-native';

export default function ButtonExample() {
  const themeColorAccentForeground = useThemeColor('accent-foreground');
  const themeColorAccentSoftForeground = useThemeColor(
    'accent-soft-foreground'
  );
  const themeColorDangerForeground = useThemeColor('danger-foreground');
  const themeColorDefaultForeground = useThemeColor('default-foreground');

return (
    <View className="gap-4 p-4">
      <Button variant="primary">
        <Ionicons name="add" size={20} color={themeColorAccentForeground} />
        <Button.Label>Add Item</Button.Label>
      </Button>

<Button variant="tertiary">
        <Button.Label>Learn More</Button.Label>
        <Ionicons
          name="chevron-forward"
          size={18}
          color={themeColorDefaultForeground}
        />
      </Button>
    </View>
  );
}

```

## API Reference

### Button

Button extends all props from [PressableFeedback](./pressable-feedback) component with additional button-specific props.

| prop         | type                                                                             | default     | description                                                    |
| ------------ | -------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------- |
| `variant`    | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger' \| 'danger-soft'` | `'primary'` | Visual variant of the button                                   |
| `size`       | `'sm' \| 'md' \| 'lg'`                                                           | `'md'`      | Size of the button                                             |
| `isIconOnly` | `boolean`                                                                        | `false`     | Whether the button displays an icon only (square aspect ratio) |

For inherited props including `feedbackVariant`, `feedbackPosition`, `animation`, `isDisabled`, `className`, `children`, and all Pressable props, see [PressableFeedback API Reference](./pressable-feedback#api-reference).

### Button.Label

| prop           | type              | default | description                           |
| -------------- | ----------------- | ------- | ------------------------------------- |
| `children`     | `React.ReactNode` | -       | Content to be rendered as label       |
| `className`    | `string`          | -       | Additional CSS classes                |
| `...TextProps` | `TextProps`       | -       | All standard Text props are supported |

## Hooks

### useButton

Hook to access the Button context values. Returns the button's size, variant, and disabled state.

```tsx
import { useButton } from 'heroui-native';

const { size, variant, isDisabled } = useButton();

```

#### Return Value

| property     | type                                                                             | description                    |
| ------------ | -------------------------------------------------------------------------------- | ------------------------------ |
| `size`       | `'sm' \| 'md' \| 'lg'`                                                           | Size of the button             |
| `variant`    | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger' \| 'danger-soft'` | Visual variant of the button   |
| `isDisabled` | `boolean`                                                                        | Whether the button is disabled |

**Note:** This hook must be used within a `Button` component. It will throw an error if called outside of the button context.

</page>

<page url="/docs/native/components/chip">
# Chip

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/chip
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(data-display)/chip.mdx
> Displays a compact element in a capsule shape.

## Import

```tsx
import { Chip } from 'heroui-native';

```

## Anatomy

```tsx
<Chip>
  <Chip.Label>...</Chip.Label>
</Chip>

```

* **Chip**: Main container that displays a compact element
* **Chip.Label**: Text content of the chip

## Usage

### Basic Usage

The Chip component displays text or custom content in a capsule shape.

```tsx
<Chip>Basic Chip</Chip>

```

### Sizes

Control the chip size with the `size` prop.

```tsx
<Chip size="sm">Small</Chip>
<Chip size="md">Medium</Chip>
<Chip size="lg">Large</Chip>

```

### Variants

Choose between different visual styles with the `variant` prop.

```tsx
<Chip variant="primary">Primary</Chip>
<Chip variant="secondary">Secondary</Chip>
<Chip variant="tertiary">Tertiary</Chip>
<Chip variant="soft">Soft</Chip>

```

### Colors

Apply different color themes with the `color` prop.

```tsx
<Chip color="accent">Accent</Chip>
<Chip color="default">Default</Chip>
<Chip color="success">Success</Chip>
<Chip color="warning">Warning</Chip>
<Chip color="danger">Danger</Chip>

```

### With Icons

Add icons or custom content alongside text using compound components.

```tsx
<Chip>
  <Icon name="star" size={12} />
  <Chip.Label>Featured</Chip.Label>
</Chip>

<Chip>
  <Chip.Label>Close</Chip.Label>
  <Icon name="close" size={12} />
</Chip>

```

### Custom Styling

Apply custom styles using className or style props.

```tsx
<Chip className="bg-purple-600 px-6">
  <Chip.Label className="text-white">Custom</Chip.Label>
</Chip>

```

### Disable All Animations

Disable all animations including children by using the `"disable-all"` value for the `animation` prop.

```tsx
{
  /* Disable all animations including children */
}
<Chip animation="disable-all">No Animations</Chip>;

```

## Example

```tsx
import { Chip } from 'heroui-native';
import { View, Text } from 'react-native';
import { Ionicons } from '@expo/vector-icons';

export default function ChipExample() {
  return (
    <View className="gap-4 p-4">
      <View className="flex-row flex-wrap gap-2">
        <Chip size="sm">Small</Chip>
        <Chip size="md">Medium</Chip>
        <Chip size="lg">Large</Chip>
      </View>

<View className="flex-row flex-wrap gap-2">
        <Chip variant="primary" color="accent">
          Primary
        </Chip>
        <Chip variant="secondary" color="success">
          <View className="size-1.5 rounded-full bg-success" />
          <Chip.Label>Success</Chip.Label>
        </Chip>
        <Chip variant="tertiary" color="warning">
          <Ionicons name="star" size={12} color="#F59E0B" />
          <Chip.Label>Premium</Chip.Label>
        </Chip>
      </View>

<View className="flex-row gap-2">
        <Chip variant="secondary">
          <Chip.Label>Remove</Chip.Label>
          <Ionicons name="close" size={14} color="#6B7280" />
        </Chip>
        <Chip className="bg-purple-600">
          <Chip.Label className="text-white font-semibold">Custom</Chip.Label>
        </Chip>
      </View>
    </View>
  );
}

```

## API Reference

### Chip

| prop                | type                                                          | default     | description                                                                               |
| ------------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children`          | `React.ReactNode`                                             | -           | Content to render inside the chip                                                         |
| `size`              | `'sm' \| 'md' \| 'lg'`                                        | `'md'`      | Size of the chip                                                                          |
| `variant`           | `'primary' \| 'secondary' \| 'tertiary' \| 'soft'`            | `'primary'` | Visual variant of the chip                                                                |
| `color`             | `'accent' \| 'default' \| 'success' \| 'warning' \| 'danger'` | `'accent'`  | Color theme of the chip                                                                   |
| `className`         | `string`                                                      | -           | Additional CSS classes to apply                                                           |
| `animation`         | `"disable-all" \| undefined`                                  | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
| `...PressableProps` | `PressableProps`                                              | -           | All Pressable props are supported                                                         |

### Chip.Label

| prop           | type              | default | description                            |
| -------------- | ----------------- | ------- | -------------------------------------- |
| `children`     | `React.ReactNode` | -       | Text or content to render as the label |
| `className`    | `string`          | -       | Additional CSS classes to apply        |
| `...TextProps` | `TextProps`       | -       | All standard Text props are supported  |

## Hooks

### useChip

Hook to access the Chip context values. Returns the chip's size, variant, and color.

```tsx
import { useChip } from 'heroui-native';

const { size, variant, color } = useChip();

```

#### Return Value

| property  | type                                                          | description                |
| --------- | ------------------------------------------------------------- | -------------------------- |
| `size`    | `'sm' \| 'md' \| 'lg'`                                        | Size of the chip           |
| `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'soft'`            | Visual variant of the chip |
| `color`   | `'accent' \| 'default' \| 'success' \| 'warning' \| 'danger'` | Color theme of the chip    |

**Note:** This hook must be used within a `Chip` component. It will throw an error if called outside of the chip context.

</page>

<page url="/docs/native/components/error-view">
# ErrorView

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/error-view
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(feedback)/error-view.mdx
> Displays validation error message content with smooth animations.

## Import

```tsx
import { ErrorView } from 'heroui-native';

```

## Anatomy

```tsx
<ErrorView>
  Error message content
</ErrorView>

```

* **ErrorView**: Main container that displays error messages with smooth animations. Accepts string children which are automatically wrapped with Text component, or custom React components for more complex layouts. Controls visibility through the `isInvalid` prop and supports custom entering/exiting animations.

## Usage

### Basic Usage

The ErrorView component displays error messages when validation fails.

```tsx
<ErrorView isInvalid={true}>This field is required</ErrorView>

```

### Controlled Visibility

Control when the error appears using the `isInvalid` prop.

```tsx
const [isInvalid, setIsInvalid] = useState(false);

<ErrorView isInvalid={isInvalid}>Please enter a valid email address</ErrorView>;

```

### Custom Content

Pass custom React components as children instead of strings.

```tsx
<ErrorView isInvalid={true}>
  <View className="flex-row items-center">
    <Icon name="alert-circle" />
    <Text className="ml-2 text-danger">Invalid input</Text>
  </View>
</ErrorView>

```

### Custom Animations

Override default entering and exiting animations using the `animation` prop.

```tsx
import { SlideInDown, SlideOutUp } from 'react-native-reanimated';

<ErrorView
  isInvalid={true}
  animation={{
    entering: { value: SlideInDown.duration(200) },
    exiting: { value: SlideOutUp.duration(150) },
  }}
>
  Field validation failed
</ErrorView>;

```

Disable animations entirely:

```tsx
<ErrorView isInvalid={true} animation={false}>
  Field validation failed
</ErrorView>

```

### Custom Styling

Apply custom styles to the container and text elements.

```tsx
<ErrorView
  isInvalid={true}
  className="mt-2"
  classNames={{
    container: 'bg-danger/10 p-2 rounded',
    text: 'text-xs font-medium',
  }}
>
  Password must be at least 8 characters
</ErrorView>

```

### Custom Text Props

Pass additional props to the Text component when children is a string.

```tsx
<ErrorView
  isInvalid={true}
  textProps={{
    numberOfLines: 1,
    ellipsizeMode: 'tail',
    style: { letterSpacing: 0.5 },
  }}
>
  This is a very long error message that might need to be truncated
</ErrorView>

```

## Example

```tsx
import { ErrorView, TextField } from 'heroui-native';
import { useState } from 'react';
import { View } from 'react-native';

export default function ErrorViewExample() {
  const [email, setEmail] = useState('');
  const [showError, setShowError] = useState(false);

const isValidEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);

const handleBlur = () => {
    setShowError(email !== '' && !isValidEmail);
  };

return (
    <View className="p-4">
      <TextField>
        <TextField.Label>Email Address</TextField.Label>
        <TextField.Input
          placeholder="Enter your email"
          value={email}
          onChangeText={setEmail}
          onBlur={handleBlur}
          keyboardType="email-address"
          autoCapitalize="none"
        />
        <TextField.Description>
          We'll use this to contact you
        </TextField.Description>
      </TextField>

<ErrorView isInvalid={showError} className="ml-1">
        Please enter a valid email address
      </ErrorView>
    </View>
  );
}

```

## API Reference

### ErrorView

| prop                   | type                           | default     | description                                                              |
| ---------------------- | ------------------------------ | ----------- | ------------------------------------------------------------------------ |
| `children`             | `React.ReactNode`              | `undefined` | The content of the error field. String children are wrapped with Text    |
| `isInvalid`            | `boolean`                      | `false`     | Controls the visibility of the error field                               |
| `animation`            | `ErrorViewRootAnimation`       | -           | Animation configuration                                                  |
| `className`            | `string`                       | `undefined` | Additional CSS classes for the container                                 |
| `classNames`           | `ElementSlots<ErrorViewSlots>` | `undefined` | Additional CSS classes for different parts of the component              |
| `textProps`            | `TextProps`                    | `undefined` | Additional props to pass to the Text component when children is a string |
| `...AnimatedViewProps` | `AnimatedProps<ViewProps>`     | -           | All Reanimated Animated.View props are supported                         |

**classNames prop:** `ElementSlots<ErrorViewSlots>` provides type-safe CSS classes for different parts of the error view component. Available slots: `container`, `text`.

#### ErrorViewRootAnimation

Animation configuration for error view root component. Can be:

* `false` or `"disabled"`: Disable only root animations
* `"disable-all"`: Disable all animations including children
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop             | type                    | default                                                                 | description                              |
| ---------------- | ----------------------- | ----------------------------------------------------------------------- | ---------------------------------------- |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br />`.duration(150)`<br />`.easing(Easing.out(Easing.ease))`  | Custom entering animation for error view |
| `exiting.value`  | `EntryOrExitLayoutType` | `FadeOut`<br />`.duration(100)`<br />`.easing(Easing.out(Easing.ease))` | Custom exiting animation for error view  |

</page>

<page url="/docs/native/components/skeleton-group">
# SkeletonGroup

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/skeleton-group
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(feedback)/skeleton-group.mdx
> Coordinates multiple skeleton loading placeholders with centralized animation control.

## Import

```tsx
import { SkeletonGroup } from 'heroui-native';

```

## Anatomy

```tsx
<SkeletonGroup>
  <SkeletonGroup.Item />
</SkeletonGroup>

```

* **SkeletonGroup**: Root container that provides centralized control for all skeleton items
* **SkeletonGroup.Item**: Individual skeleton item that inherits props from the parent group

## Usage

### Basic Usage

The SkeletonGroup component manages multiple skeleton items with shared loading state and animation.

```tsx
<SkeletonGroup isLoading={isLoading}>
  <SkeletonGroup.Item className="h-4 w-full rounded-md" />
  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
  <SkeletonGroup.Item className="h-4 w-1/2 rounded-md" />
</SkeletonGroup>

```

### With Container Layout

Use className on the group to control layout of skeleton items.

```tsx
<SkeletonGroup isLoading={isLoading} className="flex-row items-center gap-3">
  <SkeletonGroup.Item className="h-12 w-12 rounded-lg" />
  <View className="flex-1 gap-1.5">
    <SkeletonGroup.Item className="h-4 w-full rounded-md" />
    <SkeletonGroup.Item className="h-3 w-2/3 rounded-md" />
  </View>
</SkeletonGroup>

```

### With isSkeletonOnly for Pure Skeleton Layouts

Use `isSkeletonOnly` when the group contains only skeleton placeholders with layout wrappers (like View) that have no content to render in the loaded state. This prop hides the entire group when `isLoading` is false, preventing empty containers from affecting your layout.

```tsx
<SkeletonGroup
  isLoading={isLoading}
  isSkeletonOnly // Hides entire group when isLoading is false
  className="flex-row items-center gap-3"
>
  <SkeletonGroup.Item className="h-12 w-12 rounded-lg" />
  {/* This View is only for layout, no content */}
  <View className="flex-1 gap-1.5">
    <SkeletonGroup.Item className="h-4 w-full rounded-md" />
    <SkeletonGroup.Item className="h-3 w-2/3 rounded-md" />
  </View>
</SkeletonGroup>

```

### With Animation Variants

Control animation style for all items in the group.

```tsx
<SkeletonGroup isLoading={isLoading} variant="pulse">
  <SkeletonGroup.Item className="h-10 w-10 rounded-full" />
  <SkeletonGroup.Item className="h-4 w-32 rounded-md" />
  <SkeletonGroup.Item className="h-3 w-24 rounded-md" />
</SkeletonGroup>

```

### With Custom Animation Configuration

Configure shimmer or pulse animations for the entire group.

```tsx
<SkeletonGroup
  isLoading={isLoading}
  variant="shimmer"
  animation={{
    shimmer: {
      duration: 2000,
      highlightColor: 'rgba(59, 130, 246, 0.3)',
    },
  }}
>
  <SkeletonGroup.Item className="h-16 w-full rounded-lg" />
  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
</SkeletonGroup>

```

### With Enter/Exit Animations

Apply Reanimated transitions when the group appears or disappears.

```tsx
<SkeletonGroup
  entering={FadeInLeft}
  exiting={FadeOutRight}
  isLoading={isLoading}
  className="w-full gap-2"
>
  <SkeletonGroup.Item className="h-4 w-full rounded-md" />
  <SkeletonGroup.Item className="h-4 w-3/4 rounded-md" />
</SkeletonGroup>

```

## Example

```tsx
import { Card, SkeletonGroup, Avatar } from 'heroui-native';
import { useState } from 'react';
import { Text, View, Image } from 'react-native';

export default function SkeletonGroupExample() {
  const [isLoading, setIsLoading] = useState(true);

return (
    <SkeletonGroup isLoading={isLoading}>
      <Card className="p-4">
        <Card.Header>
          <View className="flex-row items-center gap-3 mb-4">
            <SkeletonGroup.Item className="h-10 w-10 rounded-full">
              <Avatar size="sm" alt="Avatar">
                <Avatar.Image
                  source={{ uri: 'https://i.pravatar.cc/150?img=4' }}
                />
                <Avatar.Fallback />
              </Avatar>
            </SkeletonGroup.Item>

<View className="flex-1 gap-1">
              <SkeletonGroup.Item className="h-3 w-32 rounded-md">
                <Text className="font-semibold text-foreground">John Doe</Text>
              </SkeletonGroup.Item>
              <SkeletonGroup.Item className="h-3 w-24 rounded-md">
                <Text className="text-sm text-muted">@johndoe</Text>
              </SkeletonGroup.Item>
            </View>
          </View>

<View className="mb-4 gap-1.5">
            <SkeletonGroup.Item className="h-4 w-full rounded-md">
              <Text className="text-base text-foreground">
                This is the first line of the post content.
              </Text>
            </SkeletonGroup.Item>
            <SkeletonGroup.Item className="h-4 w-full rounded-md">
              <Text className="text-base text-foreground">
                Second line with more interesting content to read.
              </Text>
            </SkeletonGroup.Item>
            <SkeletonGroup.Item className="h-4 w-2/3 rounded-md">
              <Text className="text-base text-foreground">
                Last line is shorter.
              </Text>
            </SkeletonGroup.Item>
          </View>
        </Card.Header>

<SkeletonGroup.Item className="h-48 w-full rounded-lg">
          <View className="h-48 bg-surface-tertiary rounded-lg overflow-hidden">
            <Image
              source={{
                uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/backgrounds/cards/car1.jpg',
              }}
              className="h-full w-full"
            />
          </View>
        </SkeletonGroup.Item>
      </Card>
    </SkeletonGroup>
  );
}

```

## API Reference

### SkeletonGroup

| prop                    | type                             | default     | description                                                            |
| ----------------------- | -------------------------------- | ----------- | ---------------------------------------------------------------------- |
| `children`              | `React.ReactNode`                | -           | SkeletonGroup.Item components and layout elements                      |
| `isLoading`             | `boolean`                        | `true`      | Whether the skeleton items are currently loading                       |
| `isSkeletonOnly`        | `boolean`                        | `false`     | Hides entire group when isLoading is false (for skeleton-only layouts) |
| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | Animation variant for all items in the group                           |
| `animation`             | `SkeletonRootAnimation`          | -           | Animation configuration                                                |
| `className`             | `string`                         | -           | Additional CSS classes for the group container                         |
| `style`                 | `StyleProp<ViewStyle>`           | -           | Custom styles for the group container                                  |
| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -           | All Reanimated Animated.View props are supported                       |

#### SkeletonRootAnimation

Animation configuration for SkeletonGroup component. Can be:

| prop                     | type                    | default                     | description                            |
| ------------------------ | ----------------------- | --------------------------- | -------------------------------------- |
| `entering.value`         | `EntryOrExitLayoutType` | `FadeIn`                    | Custom entering animation              |
| `exiting.value`          | `EntryOrExitLayoutType` | `FadeOut`                   | Custom exiting animation               |
| `shimmer.duration`       | `number`                | `1500`                      | Animation duration in milliseconds     |
| `shimmer.speed`          | `number`                | `1`                         | Speed multiplier for the animation     |
| `shimmer.highlightColor` | `string`                | -                           | Highlight color for the shimmer effect |
| `shimmer.easing`         | `EasingFunction`        | `Easing.linear`             | Easing function for the animation      |
| `pulse.duration`         | `number`                | `1000`                      | Animation duration in milliseconds     |
| `pulse.minOpacity`       | `number`                | `0.5`                       | Minimum opacity value                  |
| `pulse.maxOpacity`       | `number`                | `1`                         | Maximum opacity value                  |
| `pulse.easing`           | `EasingFunction`        | `Easing.inOut(Easing.ease)` | Easing function for the animation      |

### SkeletonGroup.Item

| prop                    | type                             | default   | description                                                         |
| ----------------------- | -------------------------------- | --------- | ------------------------------------------------------------------- |
| `children`              | `React.ReactNode`                | -         | Content to show when not loading                                    |
| `isLoading`             | `boolean`                        | inherited | Whether the skeleton is currently loading (overrides group setting) |
| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | inherited | Animation variant (overrides group setting)                         |
| `animation`             | `SkeletonRootAnimation`          | inherited | Animation configuration (overrides group setting)                   |
| `className`             | `string`                         | -         | Additional CSS classes for styling the item                         |
| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -         | All Reanimated Animated.View props are supported                    |

## Special Notes

### Props Inheritance

SkeletonGroup.Item components inherit all animation-related props from their parent SkeletonGroup:

* `isLoading`
* `variant`
* `animation`

Individual items can override any inherited prop by providing their own value.

</page>

<page url="/docs/native/components/skeleton">
# Skeleton

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/skeleton
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(feedback)/skeleton.mdx
> Displays a loading placeholder with shimmer or pulse animation effects.

## Import

```tsx
import { Skeleton } from 'heroui-native';

```

## Anatomy

The Skeleton component is a simple wrapper that renders a placeholder for content that is loading. It does not have any child components.

```tsx
<Skeleton />

```

## Usage

### Basic Usage

The Skeleton component creates an animated placeholder while content is loading.

```tsx
<Skeleton className="h-20 w-full rounded-lg" />

```

### With Content

Show skeleton while loading, then display content when ready.

```tsx
<Skeleton isLoading={isLoading} className="h-20 rounded-lg">
  <View className="h-20 bg-primary rounded-lg">
    <Text>Loaded Content</Text>
  </View>
</Skeleton>

```

### Animation Variants

Control the animation style with the `variant` prop.

```tsx
<Skeleton variant="shimmer" className="h-20 w-full rounded-lg" />
<Skeleton variant="pulse" className="h-20 w-full rounded-lg" />
<Skeleton variant="none" className="h-20 w-full rounded-lg" />

```

### Custom Shimmer Configuration

Customize the shimmer effect with duration, speed, and highlight color.

```tsx
<Skeleton
  className="h-16 w-full rounded-lg"
  variant="shimmer"
  animation={{
    shimmer: {
      duration: 2000,
      speed: 2,
      highlightColor: 'rgba(59, 130, 246, 0.3)',
    },
  }}
>
  ...
</Skeleton>

```

### Custom Pulse Configuration

Configure pulse animation with duration and opacity range.

```tsx
<Skeleton
  className="h-16 w-full rounded-lg"
  variant="pulse"
  animation={{
    pulse: {
      duration: 500,
      minOpacity: 0.1,
      maxOpacity: 0.8,
    },
  }}
>
  ...
</Skeleton>

```

### Shape Variations

Create different skeleton shapes using className for styling.

```tsx
<Skeleton className="h-4 w-full rounded-md" />
<Skeleton className="h-4 w-3/4 rounded-md" />
<Skeleton className="h-4 w-1/2 rounded-md" />
<Skeleton className="size-12 rounded-full" />

```

### Custom Enter/Exit Animations

Apply custom Reanimated transitions when skeleton appears or disappears.

```tsx
<Skeleton
  entering={FadeIn.duration(300)}
  exiting={FadeOut.duration(300)}
  isLoading={isLoading}
  className="h-20 w-full rounded-lg"
>
  ...
</Skeleton>

```

## Example

```tsx
import { Avatar, Card, Skeleton } from 'heroui-native';
import { useState } from 'react';
import { Image, Text, View } from 'react-native';

export default function SkeletonExample() {
  const [isLoading, setIsLoading] = useState(true);

return (
    <Card className="p-4">
      <View className="flex-row items-center gap-3 mb-4">
        <Skeleton isLoading={isLoading} className="h-10 w-10 rounded-full">
          <Avatar size="sm" alt="Avatar">
            <Avatar.Image source={{ uri: 'https://i.pravatar.cc/150?img=4' }} />
            <Avatar.Fallback />
          </Avatar>
        </Skeleton>

<View className="flex-1 gap-1">
          <Skeleton isLoading={isLoading} className="h-3 w-32 rounded-md">
            <Text className="font-semibold text-foreground">John Doe</Text>
          </Skeleton>
          <Skeleton isLoading={isLoading} className="h-3 w-24 rounded-md">
            <Text className="text-sm text-muted">@johndoe</Text>
          </Skeleton>
        </View>
      </View>

<Skeleton
        isLoading={isLoading}
        className="h-48 w-full rounded-lg"
        animation={{
          shimmer: {
            duration: 1500,
            speed: 1,
          },
        }}
      >
        <View className="h-48 bg-surface-tertiary rounded-lg overflow-hidden">
          <Image
            source={{
              uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/backgrounds/cards/car1.jpg',
            }}
            className="h-full w-full"
          />
        </View>
      </Skeleton>
    </Card>
  );
}

```

## API Reference

### Skeleton

| prop                    | type                             | default     | description                                      |
| ----------------------- | -------------------------------- | ----------- | ------------------------------------------------ |
| `children`              | `React.ReactNode`                | -           | Content to show when not loading                 |
| `isLoading`             | `boolean`                        | `true`      | Whether the skeleton is currently loading        |
| `variant`               | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | Animation variant                                |
| `animation`             | `SkeletonRootAnimation`          | -           | Animation configuration                          |
| `className`             | `string`                         | -           | Additional CSS classes for styling               |
| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`       | -           | All Reanimated Animated.View props are supported |

#### SkeletonRootAnimation

Animation configuration for Skeleton component. Can be:

</page>

<page url="/docs/native/components/spinner">
# Spinner

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/spinner
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(feedback)/spinner.mdx
> Displays an animated loading indicator.

## Import

```tsx
import { Spinner } from 'heroui-native';

```

## Anatomy

```tsx
<Spinner>
  <Spinner.Indicator>...</Spinner.Indicator>
</Spinner>

```

* **Spinner**: Main container that controls loading state, size, and color. Renders a default animated indicator if no children provided.
* **Spinner.Indicator**: Optional sub-component for customizing animation configuration and icon appearance. Accepts custom children to replace the default icon.

## Usage

### Basic Usage

The Spinner component displays a rotating loading indicator.

```tsx
<Spinner />

```

### Sizes

Control the spinner size with the `size` prop.

```tsx
<Spinner size="sm" />
<Spinner size="md" />
<Spinner size="lg" />

```

### Colors

Use predefined color variants or custom colors.

```tsx
<Spinner color="default" />
<Spinner color="success" />
<Spinner color="warning" />
<Spinner color="danger" />
<Spinner color="#8B5CF6" />

```

### Loading State

Control the visibility of the spinner with the `isLoading` prop.

```tsx
<Spinner isLoading={true} />
<Spinner isLoading={false} />

```

### Animation Speed

Customize the rotation speed using the `animation` prop on the Indicator component.

```tsx
<Spinner>
  <Spinner.Indicator animation={{ rotation: { speed: 0.5 } }} />
</Spinner>

```

### Custom Icon

Replace the default spinner icon with custom content.

```tsx
const themeColorForeground = useThemeColor('foreground')

```

## Example

```tsx
import { Spinner } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import React from 'react';
import { Text, TouchableOpacity, View } from 'react-native';

export default function SpinnerExample() {
  const [isLoading, setIsLoading] = React.useState(true);

return (
    <View className="gap-4 p-4 bg-background">
      <View className="flex-row items-center gap-2 p-4 rounded-lg bg-stone-200">
        <Spinner size="sm" color="default" />
        <Text className="text-stone-500">Loading content...</Text>
      </View>

<View className="items-center p-8 rounded-2xl bg-stone-200">
        <Spinner size="lg" color="success" isLoading={isLoading} />
        <Text className="text-stone-500 mt-4">Processing...</Text>
        <TouchableOpacity onPress={() => setIsLoading(!isLoading)}>
          <Text className="text-primary mt-2 text-sm">
            {isLoading ? 'Tap to stop' : 'Tap to start'}
          </Text>
        </TouchableOpacity>
      </View>

<View className="flex-row gap-4 items-center justify-center">
        <Spinner size="md" color="#EC4899">
          <Spinner.Indicator animation={{ rotation: { speed: 0.7 } }}>
            <Ionicons name="refresh" size={24} color="#EC4899" />
          </Spinner.Indicator>
        </Spinner>
      </View>
    </View>
  );
}

```

## API Reference

### Spinner

| prop           | type                                                        | default     | description                                        |
| -------------- | ----------------------------------------------------------- | ----------- | -------------------------------------------------- |
| `children`     | `React.ReactNode`                                           | `undefined` | Content to render inside the spinner               |
| `size`         | `'sm' \| 'md' \| 'lg'`                                      | `'md'`      | Size of the spinner                                |
| `color`        | `'default' \| 'success' \| 'warning' \| 'danger' \| string` | `'default'` | Color theme of the spinner                         |
| `isLoading`    | `boolean`                                                   | `true`      | Whether the spinner is loading                     |
| `className`    | `string`                                                    | `undefined` | Custom class name for the spinner                  |
| `animation`    | `SpinnerRootAnimation`                                      | -           | Animation configuration                            |
| `...ViewProps` | `ViewProps`                                                 | -           | All standard React Native View props are supported |

#### SpinnerRootAnimation

Animation configuration for Spinner component. Can be:

| prop             | type                    | default                                                                | description               |
| ---------------- | ----------------------- | ---------------------------------------------------------------------- | ------------------------- |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br />`.duration(200)`<br />`.easing(Easing.out(Easing.ease))` | Custom entering animation |
| `exiting.value`  | `EntryOrExitLayoutType` | `FadeOut`<br />`.duration(100)`                                        | Custom exiting animation  |

### Spinner.Indicator

| prop                    | type                        | default     | description                                      |
| ----------------------- | --------------------------- | ----------- | ------------------------------------------------ |
| `children`              | `React.ReactNode`           | `undefined` | Content to render inside the indicator           |
| `iconProps`             | `SpinnerIconProps`          | `undefined` | Props for the default icon                       |
| `className`             | `string`                    | `undefined` | Custom class name for the indicator element      |
| `animation`             | `SpinnerIndicatorAnimation` | -           | Animation configuration                          |
| `...Animated.ViewProps` | `Animated.ViewProps`        | -           | All Reanimated Animated.View props are supported |

#### SpinnerIndicatorAnimation

Animation configuration for Spinner.Indicator component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop              | type                         | default         | description                    |
| ----------------- | ---------------------------- | --------------- | ------------------------------ |
| `rotation.speed`  | `number`                     | `1.1`           | Rotation speed multiplier      |
| `rotation.easing` | `WithTimingConfig['easing']` | `Easing.linear` | Animation easing configuration |

### SpinnerIconProps

| prop     | type               | default          | description        |
| -------- | ------------------ | ---------------- | ------------------ |
| `width`  | `number \| string` | `24`             | Width of the icon  |
| `height` | `number \| string` | `24`             | Height of the icon |
| `color`  | `string`           | `'currentColor'` | Color of the icon  |

</page>

<page url="/docs/native/components/checkbox">
# Checkbox

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/checkbox
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/checkbox.mdx
> A selectable control that allows users to toggle between checked and unchecked states.

## Import

```tsx
import { Checkbox } from 'heroui-native';

```

## Anatomy

```tsx
<Checkbox>
  <Checkbox.Indicator>...</Checkbox.Indicator>
</Checkbox>

```

* **Checkbox**: Main container that handles selection state and user interaction. Renders default indicator with animated checkmark if no children provided. Automatically detects surface context for proper styling. Features press scale animation that can be customized or disabled. Supports render function children to access state (`isSelected`, `isInvalid`, `isDisabled`).
* **Checkbox.Indicator**: Optional checkmark container with default slide, scale, opacity, and border radius animations when selected. Renders animated check icon with SVG path drawing animation if no children provided. All animations can be individually customized or disabled. Supports render function children to access state.

## Usage

### Basic Usage

The Checkbox component renders with a default animated indicator if no children are provided. It automatically detects whether it's on a surface background for proper styling.

```tsx
<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected} />

```

### With Custom Indicator

Use a render function in the Indicator to show/hide custom icons based on state.

```tsx
<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
  <Checkbox.Indicator>
    {({ isSelected }) => (isSelected ? <CheckIcon /> : null)}
  </Checkbox.Indicator>
</Checkbox>

```

### Invalid State

Show validation errors with the `isInvalid` prop, which applies danger color styling.

```tsx
<Checkbox
  isSelected={isSelected}
  onSelectedChange={setIsSelected}
  isInvalid={hasError}
/>

```

### Custom Animations

Customize or disable animations for both the root checkbox and indicator.

```tsx
{
  /* Disable all animations (root and indicator) */
}
<Checkbox
  animation="disable-all"
  isSelected={isSelected}
  onSelectedChange={setIsSelected}
>
  <Checkbox.Indicator />
</Checkbox>;

{
  /* Disable only root animation */
}
<Checkbox
  animation="disabled"
  isSelected={isSelected}
  onSelectedChange={setIsSelected}
>
  <Checkbox.Indicator />
</Checkbox>;

{
  /* Disable only indicator animation */
}
<Checkbox isSelected={isSelected} onSelectedChange={setIsSelected}>
  <Checkbox.Indicator animation="disabled" />
</Checkbox>;

{
  /* Custom animation configuration */
}
<Checkbox
  animation={{ scale: { value: [1, 0.9], timingConfig: { duration: 200 } } }}
  isSelected={isSelected}
  onSelectedChange={setIsSelected}
>
  <Checkbox.Indicator
    animation={{
      scale: { value: [0.5, 1] },
      opacity: { value: [0, 1] },
      translateX: { value: [-8, 0] },
      borderRadius: { value: [12, 0] },
    }}
  />
</Checkbox>;

```

## Example

```tsx
import { Checkbox, Divider, FormField, Surface } from 'heroui-native';
import React from 'react';
import { View, Text } from 'react-native';

interface CheckboxFieldProps {
  isSelected: boolean;
  onSelectedChange: (value: boolean) => void;
  title: string;
  description: string;
}

const CheckboxField: React.FC<CheckboxFieldProps> = ({
  isSelected,
  onSelectedChange,
  title,
  description,
}) => {
  return (
    <FormField isSelected={isSelected} onSelectedChange={onSelectedChange}>
      <FormField.Indicator>
        <Checkbox className="mt-0.5" />
      </FormField.Indicator>
      <View className="flex-1">
        <FormField.Label className="text-lg">{title}</FormField.Label>
        <FormField.Description className="text-base">
          {description}
        </FormField.Description>
      </View>
    </FormField>
  );
};

export default function BasicUsage() {
  const [fields, setFields] = React.useState({
    newsletter: true,
    marketing: false,
    terms: false,
  });

const fieldConfigs: Record<
    keyof typeof fields,
    { title: string; description: string }
  > = {
    newsletter: {
      title: 'Subscribe to newsletter',
      description: 'Get weekly updates about new features and tips',
    },
    marketing: {
      title: 'Marketing communications',
      description: 'Receive promotional emails and special offers',
    },
    terms: {
      title: 'Accept terms and conditions',
      description: 'Agree to our Terms of Service and Privacy Policy',
    },
  };

const handleFieldChange = (key: keyof typeof fields) => (value: boolean) => {
    setFields((prev) => ({ ...prev, [key]: value }));
  };

const fieldKeys = Object.keys(fields) as Array<keyof typeof fields>;

return (
    <View className="flex-1 items-center justify-center px-5">
      <Surface className="py-5 w-full">
        {fieldKeys.map((key, index) => (
          <React.Fragment key={key}>
            {index > 0 && <Divider className="my-4" />}
            <CheckboxField
              isSelected={fields[key]}
              onSelectedChange={handleFieldChange(key)}
              title={fieldConfigs[key].title}
              description={fieldConfigs[key].description}
            />
          </React.Fragment>
        ))}
      </Surface>
    </View>
  );
}

```

## API Reference

### Checkbox

| prop                | type                                                                   | default     | description                                                               |
| ------------------- | ---------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
| `children`          | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | Child elements or render function to customize the checkbox               |
| `isSelected`        | `boolean`                                                              | `undefined` | Whether the checkbox is currently selected                                |
| `onSelectedChange`  | `(isSelected: boolean) => void`                                        | `undefined` | Callback fired when the checkbox selection state changes                  |
| `isDisabled`        | `boolean`                                                              | `false`     | Whether the checkbox is disabled and cannot be interacted with            |
| `isInvalid`         | `boolean`                                                              | `false`     | Whether the checkbox is invalid (shows danger color)                      |
| `isOnSurface`       | `boolean`                                                              | `undefined` | Whether checkbox is on a surface background (auto-detected if not set)    |
| `hitSlop`           | `number`                                                               | `6`         | Hit slop for the pressable area                                           |
| `animation`         | `CheckboxRootAnimation`                                                | -           | Animation configuration                                                   |
| `className`         | `string`                                                               | `undefined` | Additional CSS classes to apply                                           |
| `...PressableProps` | `PressableProps`                                                       | -           | All standard React Native Pressable props are supported (except disabled) |

#### CheckboxRenderProps

| prop         | type      | description                      |
| ------------ | --------- | -------------------------------- |
| `isSelected` | `boolean` | Whether the checkbox is selected |
| `isInvalid`  | `boolean` | Whether the checkbox is invalid  |
| `isDisabled` | `boolean` | Whether the checkbox is disabled |

#### CheckboxRootAnimation

Animation configuration for checkbox root component. Can be:

| prop                 | type               | default             | description                        |
| -------------------- | ------------------ | ------------------- | ---------------------------------- |
| `scale.value`        | `[number, number]` | `[1, 0.96]`         | Scale values \[unpressed, pressed] |
| `scale.timingConfig` | `WithTimingConfig` | `{ duration: 150 }` | Animation timing configuration     |

### Checkbox.Indicator

| prop                   | type                                                                   | default     | description                                                 |
| ---------------------- | ---------------------------------------------------------------------- | ----------- | ----------------------------------------------------------- |
| `children`             | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | Content or render function for the checkbox indicator       |
| `className`            | `string`                                                               | `undefined` | Additional CSS classes for the indicator                    |
| `iconProps`            | `CheckboxIndicatorIconProps`                                           | `undefined` | Custom props for the default animated check icon            |
| `animation`            | `CheckboxIndicatorAnimation`                                           | -           | Animation configuration                                     |
| `...AnimatedViewProps` | `AnimatedProps<ViewProps>`                                             | -           | All standard React Native Animated View props are supported |

#### CheckboxIndicatorIconProps

Props for customizing the default animated check icon.

| prop            | type     | description                                      |
| --------------- | -------- | ------------------------------------------------ |
| `size`          | `number` | Icon size                                        |
| `strokeWidth`   | `number` | Icon stroke width                                |
| `color`         | `string` | Icon color (defaults to theme accent-foreground) |
| `enterDuration` | `number` | Duration of enter animation (check appearing)    |
| `exitDuration`  | `number` | Duration of exit animation (check disappearing)  |

#### CheckboxIndicatorAnimation

Animation configuration for checkbox indicator component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop                        | type               | default             | description                                  |
| --------------------------- | ------------------ | ------------------- | -------------------------------------------- |
| `opacity.value`             | `[number, number]` | `[0, 1]`            | Opacity values \[unselected, selected]       |
| `opacity.timingConfig`      | `WithTimingConfig` | `{ duration: 100 }` | Animation timing configuration               |
| `borderRadius.value`        | `[number, number]` | `[8, 0]`            | Border radius values \[unselected, selected] |
| `borderRadius.timingConfig` | `WithTimingConfig` | `{ duration: 50 }`  | Animation timing configuration               |
| `translateX.value`          | `[number, number]` | `[-4, 0]`           | TranslateX values \[unselected, selected]    |
| `translateX.timingConfig`   | `WithTimingConfig` | `{ duration: 100 }` | Animation timing configuration               |
| `scale.value`               | `[number, number]` | `[0.8, 1]`          | Scale values \[unselected, selected]         |
| `scale.timingConfig`        | `WithTimingConfig` | `{ duration: 100 }` | Animation timing configuration               |

## Hooks

### useCheckbox

Hook to access checkbox context values within custom components or compound components.

```tsx
import { useCheckbox } from 'heroui-native';

const CustomIndicator = () => {
  const { isSelected, isInvalid, isDisabled } = useCheckbox();
  // ... your implementation
};

```

**Returns:** `UseCheckboxReturn`

| property           | type                                           | description                                                    |
| ------------------ | ---------------------------------------------- | -------------------------------------------------------------- |
| `isSelected`       | `boolean \| undefined`                         | Whether the checkbox is currently selected                     |
| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | Callback function to change the checkbox selection state       |
| `isDisabled`       | `boolean`                                      | Whether the checkbox is disabled and cannot be interacted with |
| `isInvalid`        | `boolean`                                      | Whether the checkbox is invalid (shows danger color)           |
| `isOnSurface`      | `boolean \| undefined`                         | Whether checkbox is on a surface background                    |
| `nativeID`         | `string \| undefined`                          | Native ID for the checkbox element                             |

**Note:** This hook must be used within a `Checkbox` component. It will throw an error if called outside of the checkbox context.

</page>

<page url="/docs/native/components/form-field">
# FormField

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/form-field
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/form-field.mdx
> Provides consistent layout and interaction for form controls with label, description, and error handling. Perfect for Switch and Checkbox components when you want the entire field to be pressable.

## Import

```tsx
import { FormField } from 'heroui-native';

```

## Anatomy

```tsx
<FormField>
  <FormField.Label>...</FormField.Label>
  <FormField.Description>...</FormField.Description>
  <FormField.Indicator>...</FormField.Indicator>
  <FormField.ErrorMessage>...</FormField.ErrorMessage>
</FormField>

```

* **FormField**: Root container that manages layout and state propagation
* **FormField.Label**: Primary text label for the control
* **FormField.Description**: Secondary descriptive helper text
* **FormField.Indicator**: Container for the form control component (Switch, Checkbox)
* **FormField.ErrorMessage**: Validation error message display

## Usage

### Basic Usage

FormField wraps form controls to provide consistent layout and state management.

```tsx
<FormField isSelected={value} onSelectedChange={setValue}>
  <View className="flex-1">
    <FormField.Label>Label text</FormField.Label>
  </View>
  <FormField.Indicator />
</FormField>

```

### With Description

Add helper text below the label using the Description component.

```tsx
<FormField isSelected={value} onSelectedChange={setValue}>
  <View className="flex-1">
    <FormField.Label>Enable notifications</FormField.Label>
    <FormField.Description>
      Receive push notifications about your account activity
    </FormField.Description>
  </View>
  <FormField.Indicator />
</FormField>

```

### With Error Message

Display validation errors using the ErrorMessage component.

```tsx
<FormField
  isSelected={value}
  onSelectedChange={setValue}
  isInvalid={!value}
  className="flex-col items-start gap-1"
>
  <View className="flex-row items-center gap-2">
    <View className="flex-1">
      <FormField.Label>I agree to the terms</FormField.Label>
      <FormField.Description>
        By checking this box, you agree to our Terms of Service
      </FormField.Description>
    </View>
    <FormField.Indicator variant="checkbox" />
  </View>
  <FormField.ErrorMessage>This field is required</FormField.ErrorMessage>
</FormField>

```

### Disabled State

Control interactivity with the disabled prop.

```tsx
<FormField isSelected={value} onSelectedChange={setValue} isDisabled>
  <View className="flex-1">
    <FormField.Label>Disabled field</FormField.Label>
    <FormField.Description>This field is disabled</FormField.Description>
  </View>
  <FormField.Indicator />
</FormField>

```

### Disabling All Animations

Disable all animations including children by using `"disable-all"`. This cascades down to all child components.

```tsx
<FormField
  isSelected={value}
  onSelectedChange={setValue}
  animation="disable-all"
>
  <View className="flex-1">
    <FormField.Label>Label text</FormField.Label>
    <FormField.Description>Description text</FormField.Description>
  </View>
  <FormField.Indicator />
</FormField>

```

## Example

```tsx
import { Checkbox, FormField, Switch } from 'heroui-native';
import React from 'react';
import { ScrollView, View } from 'react-native';

export default function FormFieldExample() {
  const [notifications, setNotifications] = React.useState(false);
  const [terms, setTerms] = React.useState(false);
  const [newsletter, setNewsletter] = React.useState(true);

return (
    <ScrollView className="bg-background p-4">
      <View className="gap-4">
        <FormField
          isSelected={notifications}
          onSelectedChange={setNotifications}
        >
          <View className="flex-1">
            <FormField.Label>Enable notifications</FormField.Label>
            <FormField.Description>
              Receive push notifications about your account activity
            </FormField.Description>
          </View>
          <FormField.Indicator />
        </FormField>

<FormField
          isSelected={terms}
          onSelectedChange={setTerms}
          isInvalid={!terms}
          className="flex-col items-start gap-1"
        >
          <View className="flex-row items-center gap-2">
            <View className="flex-1">
              <FormField.Label>
                I agree to the terms and conditions
              </FormField.Label>
              <FormField.Description>
                By checking this box, you agree to our Terms of Service
              </FormField.Description>
            </View>
            <FormField.Indicator className="mt-0.5">
              <Checkbox />
            </FormField.Indicator>
          </View>
          <FormField.ErrorMessage>
            This field is required
          </FormField.ErrorMessage>
        </FormField>

<FormField isSelected={newsletter} onSelectedChange={setNewsletter}>
          <View className="flex-1">
            <FormField.Label>Subscribe to newsletter</FormField.Label>
          </View>
          <FormField.Indicator>
            <Checkbox color="warning" />
          </FormField.Indicator>
        </FormField>
      </View>
    </ScrollView>
  );
}

```

## API Reference

### FormField

| prop              | type                                                                    | default     | description                                                                               |
| ----------------- | ----------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| children          | `React.ReactNode \| ((props: FormFieldRenderProps) => React.ReactNode)` | -           | Content to render inside the form control, or a render function                           |
| isSelected        | `boolean`                                                               | `undefined` | Whether the control is selected/checked                                                   |
| isDisabled        | `boolean`                                                               | `false`     | Whether the form control is disabled                                                      |
| isInvalid         | `boolean`                                                               | `false`     | Whether the form control is invalid                                                       |
| className         | `string`                                                                | -           | Custom class name for the root element                                                    |
| onSelectedChange  | `(isSelected: boolean) => void`                                         | -           | Callback when selection state changes                                                     |
| animation         | `"disable-all" \| undefined`                                            | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
| ...PressableProps | `PressableProps`                                                        | -           | All React Native Pressable props are supported                                            |

### FormField.Label

| prop         | type              | default | description                               |
| ------------ | ----------------- | ------- | ----------------------------------------- |
| children     | `React.ReactNode` | -       | Label text content                        |
| className    | `string`          | -       | Custom class name for the label element   |
| ...TextProps | `TextProps`       | -       | All React Native Text props are supported |

### FormField.Description

| prop         | type              | default | description                                   |
| ------------ | ----------------- | ------- | --------------------------------------------- |
| children     | `React.ReactNode` | -       | Description text content                      |
| className    | `string`          | -       | Custom class name for the description element |
| ...TextProps | `TextProps`       | -       | All React Native Text props are supported     |

### FormField.Indicator

| prop         | type                     | default    | description                                                |
| ------------ | ------------------------ | ---------- | ---------------------------------------------------------- |
| children     | `React.ReactNode`        | -          | Control component to render (Switch, Checkbox)             |
| variant      | `'checkbox' \| 'switch'` | `'switch'` | Variant of the control to render when no children provided |
| className    | `string`                 | -          | Custom class name for the indicator element                |
| ...ViewProps | `ViewProps`              | -          | All React Native View props are supported                  |

**Note**: When children are provided, the component automatically passes down `isSelected`, `onSelectedChange`, `isDisabled`, and `isInvalid` props from the FormField context if they are not already present on the child component.

### FormField.ErrorMessage

FormField.ErrorMessage extends all props from [ErrorView](./error-view) component.

**Note**: The `isInvalid` prop is automatically passed from the FormField context. The error message visibility is controlled by the `isInvalid` state of the parent FormField.

## Hooks

### useFormField

**Returns:**

| property           | type                                           | description                                    |
| ------------------ | ---------------------------------------------- | ---------------------------------------------- |
| `isSelected`       | `boolean \| undefined`                         | Whether the control is selected/checked        |
| `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | Callback when selection state changes          |
| `isDisabled`       | `boolean`                                      | Whether the form control is disabled           |
| `isInvalid`        | `boolean`                                      | Whether the form control is invalid            |
| `isPressed`        | `SharedValue<boolean>`                         | Reanimated shared value indicating press state |

</page>

<page url="/docs/native/components/radio-group">
# RadioGroup

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/radio-group
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/radio-group.mdx
> A set of radio buttons where only one option can be selected at a time.

## Import

```tsx
import { RadioGroup } from 'heroui-native';

```

## Anatomy

```tsx
<RadioGroup>
  <RadioGroup.Item>
    <RadioGroup.Label>...</RadioGroup.Label>
    <RadioGroup.Description>...</RadioGroup.Description>
    <RadioGroup.Indicator>
      <RadioGroup.IndicatorThumb />
    </RadioGroup.Indicator>
  </RadioGroup.Item>
  <RadioGroup.ErrorMessage>...</RadioGroup.ErrorMessage>
</RadioGroup>

```

* **RadioGroup**: Container that manages the selection state of radio items. Supports both horizontal and vertical orientations.
* **RadioGroup.Item**: Individual radio option within a RadioGroup. Must be used inside RadioGroup. Handles selection state and renders default indicator if no children provided. Supports render function children to access state (`isSelected`, `isInvalid`, `isDisabled`).
* **RadioGroup.Label**: Optional clickable text label for the radio option. Linked to the radio for accessibility.
* **RadioGroup.Description**: Optional secondary text below the label. Provides additional context about the radio option.
* **RadioGroup.Indicator**: Optional container for the radio circle. Renders default thumb if no children provided. Manages the visual selection state.
* **RadioGroup.IndicatorThumb**: Optional inner circle that appears when selected. Animates scale based on selection. Can be replaced with custom content.
* **RadioGroup.ErrorMessage**: Error message displayed when radio group is invalid. Shown with animation below the radio group content.

## Usage

### Basic Usage

RadioGroup with simple string children automatically renders title and indicator.

```tsx
<RadioGroup value={value} onValueChange={setValue}>
  <RadioGroup.Item value="option1">Option 1</RadioGroup.Item>
  <RadioGroup.Item value="option2">Option 2</RadioGroup.Item>
  <RadioGroup.Item value="option3">Option 3</RadioGroup.Item>
</RadioGroup>

```

### With Descriptions

Add descriptive text below each radio option for additional context.

```tsx
<RadioGroup value={value} onValueChange={setValue}>
  <RadioGroup.Item value="standard">
    <View>
      <RadioGroup.Label>Standard Shipping</RadioGroup.Label>
      <RadioGroup.Description>
        Delivered in 5-7 business days
      </RadioGroup.Description>
    </View>
    <RadioGroup.Indicator />
  </RadioGroup.Item>
  <RadioGroup.Item value="express">
    <View>
      <RadioGroup.Label>Express Shipping</RadioGroup.Label>
      <RadioGroup.Description>
        Delivered in 2-3 business days
      </RadioGroup.Description>
    </View>
    <RadioGroup.Indicator />
  </RadioGroup.Item>
</RadioGroup>

```

### Custom Indicator

Replace the default indicator thumb with custom content.

```tsx
<RadioGroup value={value} onValueChange={setValue}>
  <RadioGroup.Item value="custom">
    <RadioGroup.Label>Custom Option</RadioGroup.Label>
    <RadioGroup.Indicator>
      {value === 'custom' && (
        <Animated.View entering={FadeIn}>
          <Icon name="check" size={12} />
        </Animated.View>
      )}
    </RadioGroup.Indicator>
  </RadioGroup.Item>
</RadioGroup>

```

### With Render Function

Use a render function on RadioGroup.Item to access state and customize the entire content.

```tsx
<RadioGroup value={value} onValueChange={setValue}>
  <RadioGroup.Item value="option1">
    {({ isSelected, isInvalid, isDisabled }) => (
      <>
        <RadioGroup.Label>Option 1</RadioGroup.Label>
        <RadioGroup.Indicator>
          {isSelected && <CustomIcon />}
        </RadioGroup.Indicator>
      </>
    )}
  </RadioGroup.Item>
</RadioGroup>

```

### With Error Message

Display validation errors below the radio group.

```tsx
<RadioGroup value={value} onValueChange={setValue} isInvalid={!value}>
  <RadioGroup.Item value="agree">I agree to the terms</RadioGroup.Item>
  <RadioGroup.Item value="disagree">I do not agree</RadioGroup.Item>
  <RadioGroup.ErrorMessage>
    Please select an option to continue
  </RadioGroup.ErrorMessage>
</RadioGroup>

```

## Example

```tsx
import { RadioGroup, useThemeColor } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import React from 'react';
import { View } from 'react-native';

export default function PaymentMethodExample() {
  const [paymentMethod, setPaymentMethod] = React.useState('card');
  const themeColorForeground = useThemeColor('foreground');

return (
    <RadioGroup value={paymentMethod} onValueChange={setPaymentMethod}>
      <RadioGroup.Item value="card">
        <View>
          <View className="flex-row items-center gap-1.5">
            <Ionicons
              name="card-outline"
              size={16}
              color={themeColorForeground}
            />
            <RadioGroup.Label>Credit/Debit Card</RadioGroup.Label>
          </View>
          <RadioGroup.Description>
            Pay securely with your credit or debit card
          </RadioGroup.Description>
        </View>
        <RadioGroup.Indicator />
      </RadioGroup.Item>

<RadioGroup.Item value="paypal">
        <View>
          <RadioGroup.Label>PayPal</RadioGroup.Label>
          <RadioGroup.Description>
            Fast and secure payment with PayPal
          </RadioGroup.Description>
        </View>
        <RadioGroup.Indicator />
      </RadioGroup.Item>

<RadioGroup.Item value="bank">
        <View>
          <RadioGroup.Label>Bank Transfer</RadioGroup.Label>
          <RadioGroup.Description>
            Direct transfer from your bank account
          </RadioGroup.Description>
        </View>
        <RadioGroup.Indicator />
      </RadioGroup.Item>
    </RadioGroup>
  );
}

```

## API Reference

### RadioGroup

| prop            | type                         | default     | description                                                                               |
| --------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children`      | `React.ReactNode`            | `undefined` | Radio group content                                                                       |
| `value`         | `string \| undefined`        | `undefined` | The currently selected value of the radio group                                           |
| `onValueChange` | `(val: string) => void`      | `undefined` | Callback fired when the selected value changes                                            |
| `isDisabled`    | `boolean`                    | `false`     | Whether the entire radio group is disabled                                                |
| `isInvalid`     | `boolean`                    | `false`     | Whether the radio group is invalid                                                        |
| `isOnSurface`   | `boolean`                    | `undefined` | Whether the radio group is on surface                                                     |
| `animation`     | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
| `className`     | `string`                     | `undefined` | Custom class name                                                                         |
| `...ViewProps`  | `ViewProps`                  | -           | All standard React Native View props are supported                                        |

### RadioGroup.Item

| prop                | type                                                                         | default     | description                                                               |
| ------------------- | ---------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
| `children`          | `React.ReactNode \| ((props: RadioGroupItemRenderProps) => React.ReactNode)` | `undefined` | Radio item content or render function to customize the radio item         |
| `value`             | `string`                                                                     | `undefined` | The value associated with this radio item                                 |
| `isDisabled`        | `boolean`                                                                    | `false`     | Whether this specific radio item is disabled                              |
| `isInvalid`         | `boolean`                                                                    | `false`     | Whether the radio item is invalid                                         |
| `isOnSurface`       | `boolean`                                                                    | `undefined` | Whether the radio item is on surface (auto-detected if not set)           |
| `hitSlop`           | `number`                                                                     | `6`         | Hit slop for the pressable area                                           |
| `className`         | `string`                                                                     | `undefined` | Custom class name                                                         |
| `...PressableProps` | `PressableProps`                                                             | -           | All standard React Native Pressable props are supported (except disabled) |

#### RadioGroupItemRenderProps

| prop         | type      | description                        |
| ------------ | --------- | ---------------------------------- |
| `isSelected` | `boolean` | Whether the radio item is selected |
| `isInvalid`  | `boolean` | Whether the radio item is invalid  |
| `isDisabled` | `boolean` | Whether the radio item is disabled |

### RadioGroup.Indicator

| prop                    | type                       | default     | description                                      |
| ----------------------- | -------------------------- | ----------- | ------------------------------------------------ |
| `children`              | `React.ReactNode`          | `undefined` | Indicator content                                |
| `className`             | `string`                   | `undefined` | Custom class name                                |
| `...Animated.ViewProps` | `AnimatedProps<ViewProps>` | -           | All Reanimated Animated.View props are supported |

**Note:** The `isOnSurface` state is automatically provided via context from the parent RadioGroup.Item component.

### RadioGroup.IndicatorThumb

| prop                    | type                                | default     | description                                      |
| ----------------------- | ----------------------------------- | ----------- | ------------------------------------------------ |
| `className`             | `string`                            | `undefined` | Custom class name                                |
| `animation`             | `RadioGroupIndicatorThumbAnimation` | -           | Animation configuration                          |
| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`          | -           | All Reanimated Animated.View props are supported |

#### RadioGroupIndicatorThumbAnimation

Animation configuration for RadioGroupIndicatorThumb component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop                 | type               | default                                              | description                          |
| -------------------- | ------------------ | ---------------------------------------------------- | ------------------------------------ |
| `scale.value`        | `[number, number]` | `[1.5, 1]`                                           | Scale values \[unselected, selected] |
| `scale.timingConfig` | `WithTimingConfig` | `{ duration: 300, easing: Easing.out(Easing.ease) }` | Animation timing configuration       |

### RadioGroup.Label

| prop                    | type                       | default     | description                                      |
| ----------------------- | -------------------------- | ----------- | ------------------------------------------------ |
| `children`              | `React.ReactNode`          | `undefined` | Label text content                               |
| `className`             | `string`                   | `undefined` | Custom class name for the label element          |
| `...Animated.TextProps` | `AnimatedProps<TextProps>` | -           | All Reanimated Animated.Text props are supported |

### RadioGroup.Description

| prop                    | type                       | default     | description                                      |
| ----------------------- | -------------------------- | ----------- | ------------------------------------------------ |
| `children`              | `React.ReactNode`          | `undefined` | Description text content                         |
| `className`             | `string`                   | `undefined` | Custom class name for the description element    |
| `...Animated.TextProps` | `AnimatedProps<TextProps>` | -           | All Reanimated Animated.Text props are supported |

### RadioGroup.ErrorMessage

| prop                    | type                           | default     | description                                      |
| ----------------------- | ------------------------------ | ----------- | ------------------------------------------------ |
| `children`              | `React.ReactNode`              | `undefined` | The content of the error field                   |
| `isInvalid`             | `boolean`                      | `false`     | Controls the visibility of the error field       |
| `className`             | `string`                       | `undefined` | Additional CSS class for styling                 |
| `classNames`            | `ElementSlots<ErrorViewSlots>` | `undefined` | Additional CSS classes for different parts       |
| `textProps`             | `TextProps`                    | `undefined` | Additional props to pass to the Text component   |
| `...Animated.ViewProps` | `AnimatedProps<ViewProps>`     | -           | All Reanimated Animated.View props are supported |

## Hooks

### useRadioGroup

**Returns:**

| Property        | Type                      | Description                                    |
| --------------- | ------------------------- | ---------------------------------------------- |
| `value`         | `string \| undefined`     | Currently selected value                       |
| `isDisabled`    | `boolean`                 | Whether the radio group is disabled            |
| `isInvalid`     | `boolean`                 | Whether the radio group is in an invalid state |
| `onValueChange` | `(value: string) => void` | Function to change the selected value          |

### useRadioGroupItem

**Returns:**

| Property      | Type      | Description                          |
| ------------- | --------- | ------------------------------------ |
| `isSelected`  | `boolean` | Whether the radio item is selected   |
| `isDisabled`  | `boolean` | Whether the radio item is disabled   |
| `isInvalid`   | `boolean` | Whether the radio item is invalid    |
| `isOnSurface` | `boolean` | Whether the radio item is on surface |

</page>

<page url="/docs/native/components/select">
# Select

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/select
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/select.mdx
> Displays a list of options for the user to pick from — triggered by a button.

## Import

```tsx
import { Select } from 'heroui-native';

```

## Anatomy

```tsx
<Select>
  <Select.Trigger>
    <Select.Value />
  </Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content>
      <Select.Close />
      <Select.ListLabel>...</Select.ListLabel>
      <Select.Item>
        <Select.ItemLabel />
        <Select.ItemDescription>...</Select.ItemDescription>
        <Select.ItemIndicator />
      </Select.Item>
    </Select.Content>
  </Select.Portal>
</Select>

```

* **Select**: Main container that manages open/close state, value selection and provides context to child components.
* **Select.Trigger**: Clickable element that toggles the select visibility. Wraps any child element with press handlers.
* **Select.Value**: Displays the selected value or placeholder text. Automatically updates when selection changes.
* **Select.Portal**: Renders select content in a portal layer above other content. Ensures proper stacking and positioning.
* **Select.Overlay**: Optional background overlay. Can be transparent or semi-transparent to capture outside clicks.
* **Select.Content**: Container for select content with three presentation modes: popover (floating with positioning), bottom sheet modal, or dialog modal.
* **Select.Close**: Close button that dismisses the select when pressed. Renders a default X icon if no children provided.
* **Select.ListLabel**: Label for the list of items with pre-styled typography.
* **Select.Item**: Selectable option item. Handles selection state and press events.
* **Select.ItemLabel**: Displays the label text for an item.
* **Select.ItemDescription**: Optional description text for items with muted styling.
* **Select.ItemIndicator**: Optional indicator shown for selected items. Renders a check icon by default.

## Usage

### Basic Usage

The Select component uses compound parts to create dropdown selection interfaces.

```tsx
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content>
      <Select.Item value="1" label="Option 1" />
      <Select.Item value="2" label="Option 2" />
    </Select.Content>
  </Select.Portal>
</Select>

```

### With Value Display

Display the selected value in the trigger using the Value component.

```tsx
<Select>
  <Select.Trigger>
    <Select.Value placeholder="Choose an option" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content>
      <Select.Item value="apple" label="Apple" />
      <Select.Item value="orange" label="Orange" />
      <Select.Item value="banana" label="Banana" />
    </Select.Content>
  </Select.Portal>
</Select>

```

### Popover Presentation

Use popover presentation for floating content with automatic positioning.

```tsx
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="popover" placement="bottom" align="center">
      <Select.Item value="1" label="Item 1" />
      <Select.Item value="2" label="Item 2" />
    </Select.Content>
  </Select.Portal>
</Select>

```

### Width Control

Control the width of the select content using the `width` prop. This only works with popover presentation.

```tsx
{
  /* Fixed width in pixels */
}
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content width={280} presentation="popover">
      <Select.Item value="1" label="Item 1" />
    </Select.Content>
  </Select.Portal>
</Select>;

{
  /* Match trigger width */
}
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content width="trigger" presentation="popover">
      <Select.Item value="1" label="Item 1" />
    </Select.Content>
  </Select.Portal>
</Select>;

{
  /* Full width (100%) */
}
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content width="full" presentation="popover">
      <Select.Item value="1" label="Item 1" />
    </Select.Content>
  </Select.Portal>
</Select>;

{
  /* Auto-size to content (default) */
}
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content width="content-fit" presentation="popover">
      <Select.Item value="1" label="Item 1" />
    </Select.Content>
  </Select.Portal>
</Select>;

```

### Bottom Sheet Presentation

Use bottom sheet for mobile-optimized selection experience.

```tsx
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="bottom-sheet" snapPoints={['35%']}>
      <Select.Item value="1" label="Item 1" />
      <Select.Item value="2" label="Item 2" />
    </Select.Content>
  </Select.Portal>
</Select>

```

### Dialog Presentation

Use dialog presentation for centered modal-style selection.

```tsx
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content presentation="dialog">
      <Select.Close />
      <Select.ListLabel>Choose an option</Select.ListLabel>
      <Select.Item value="1" label="Item 1" />
      <Select.Item value="2" label="Item 2" />
    </Select.Content>
  </Select.Portal>
</Select>

```

### Custom Item Content

Customize item appearance with custom content and indicators.

```tsx
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content>
      <Select.Item value="us" label="United States">
        <View className="flex-row items-center gap-3 flex-1">
          <Text>🇺🇸</Text>
          <Select.ItemLabel />
        </View>
        <Select.ItemIndicator />
      </Select.Item>
      <Select.Item value="uk" label="United Kingdom">
        <View className="flex-row items-center gap-3 flex-1">
          <Text>🇬🇧</Text>
          <Select.ItemLabel />
        </View>
        <Select.ItemIndicator />
      </Select.Item>
    </Select.Content>
  </Select.Portal>
</Select>

```

### With Render Function

Use a render function on `Select.Item` to access state and customize content based on selection.

```tsx
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content>
      <Select.Item value="us" label="United States">
        {({ isSelected, value, isDisabled }) => (
          <>
            <View className="flex-row items-center gap-3 flex-1">
              <Text>🇺🇸</Text>
              <Select.ItemLabel
                className={
                  isSelected ? 'text-accent font-medium' : 'text-foreground'
                }
              />
            </View>
            <Select.ItemIndicator />
          </>
        )}
      </Select.Item>
      <Select.Item value="uk" label="United Kingdom">
        {({ isSelected }) => (
          <>
            <View className="flex-row items-center gap-3 flex-1">
              <Text>🇬🇧</Text>
              <Select.ItemLabel
                className={
                  isSelected ? 'text-accent font-medium' : 'text-foreground'
                }
              />
            </View>
            <Select.ItemIndicator />
          </>
        )}
      </Select.Item>
    </Select.Content>
  </Select.Portal>
</Select>

```

### With Item Description

Add descriptions to items for additional context.

```tsx
<Select>
  <Select.Trigger>...</Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content>
      <Select.Item value="basic" label="Basic">
        <View className="flex-1">
          <Select.ItemLabel />
          <Select.ItemDescription>
            Essential features for personal use
          </Select.ItemDescription>
        </View>
        <Select.ItemIndicator />
      </Select.Item>
    </Select.Content>
  </Select.Portal>
</Select>

```

### Controlled Mode

Control the select state programmatically.

```tsx
const [value, setValue] = useState();
const [isOpen, setIsOpen] = useState(false);

<Select
  value={value}
  onValueChange={setValue}
  isOpen={isOpen}
  onOpenChange={setIsOpen}
>
  <Select.Trigger>
    <Select.Value placeholder="Select..." />
  </Select.Trigger>
  <Select.Portal>
    <Select.Overlay />
    <Select.Content>
      <Select.Item value="1" label="Option 1" />
      <Select.Item value="2" label="Option 2" />
    </Select.Content>
  </Select.Portal>
</Select>;

```

## Example

```tsx
import { Button, Select } from 'heroui-native';
import { useState } from 'react';
import { ScrollView, Text, View } from 'react-native';

type CountryOption = {
  value: string;
  label: string;
  flag: string;
  code: string;
};

const COUNTRIES: CountryOption[] = [
  { value: 'US', label: 'United States', flag: '🇺🇸', code: '+1' },
  { value: 'GB', label: 'United Kingdom', flag: '🇬🇧', code: '+44' },
  { value: 'CA', label: 'Canada', flag: '🇨🇦', code: '+1' },
  { value: 'AU', label: 'Australia', flag: '🇦🇺', code: '+61' },
];

export default function SelectExample() {
  const [country, setCountry] = useState<CountryOption>();

return (
    <Select
      value={country}
      onValueChange={(value) => {
        const selected = COUNTRIES.find((c) => c.value === value?.value);
        setCountry(selected);
      }}
    >
      <Select.Trigger asChild>
        <Button variant="tertiary" size="sm">
          {country ? (
            <View className="flex-row items-center gap-2">
              <Text className="text-base">{country.flag}</Text>
              <Text className="text-sm text-foreground">{country.code}</Text>
            </View>
          ) : (
            <Text className="text-foreground">Select Country</Text>
          )}
        </Button>
      </Select.Trigger>
      <Select.Portal>
        <Select.Overlay />
        <Select.Content width={280} className="rounded-2xl" placement="bottom">
          <ScrollView>
            {COUNTRIES.map((item) => (
              <Select.Item
                key={item.value}
                value={item.value}
                label={item.label}
              >
                <View className="flex-row items-center gap-3 flex-1">
                  <Text className="text-2xl">{item.flag}</Text>
                  <Text className="text-sm text-muted w-10">{item.code}</Text>
                  <Text className="text-base text-foreground flex-1">
                    {item.label}
                  </Text>
                </View>
                <Select.ItemIndicator />
              </Select.Item>
            ))}
          </ScrollView>
        </Select.Content>
      </Select.Portal>
    </Select>
  );
}

```

## API Reference

### Select

| prop                       | type                            | default | description                                                            |
| -------------------------- | ------------------------------- | ------- | ---------------------------------------------------------------------- |
| `children`                 | `ReactNode`                     | -       | The content of the select                                              |
| `value`                    | `SelectOption`                  | -       | The selected value (controlled mode)                                   |
| `onValueChange`            | `(value: SelectOption) => void` | -       | Callback when the value changes                                        |
| `defaultValue`             | `SelectOption`                  | -       | The default selected value (uncontrolled mode)                         |
| `isOpen`                   | `boolean`                       | -       | Whether the select is open (controlled mode)                           |
| `isDefaultOpen`            | `boolean`                       | -       | Whether the select is open when initially rendered (uncontrolled mode) |
| `onOpenChange`             | `(isOpen: boolean) => void`     | -       | Callback when the select open state changes                            |
| `closeDelay`               | `number`                        | `400`   | Delay in milliseconds before closing the select                        |
| `isDisabled`               | `boolean`                       | `false` | Whether the select is disabled                                         |
| `isDismissKeyboardOnClose` | `boolean`                       | `true`  | Whether to dismiss keyboard when select closes                         |
| `animation`                | `SelectRootAnimation`           | -       | Animation configuration                                                |
| `asChild`                  | `boolean`                       | `false` | Whether to render as a child element                                   |
| `...ViewProps`             | `ViewProps`                     | -       | All standard React Native View props are supported                     |

#### SelectRootAnimation

Animation configuration for Select component. Can be:

| prop             | type                                             | default | description                                    |
| ---------------- | ------------------------------------------------ | ------- | ---------------------------------------------- |
| `entering.value` | `SpringAnimationConfig \| TimingAnimationConfig` | -       | Animation configuration for when select opens  |
| `exiting.value`  | `SpringAnimationConfig \| TimingAnimationConfig` | -       | Animation configuration for when select closes |

#### SpringAnimationConfig

| prop     | type               | default | description                               |
| -------- | ------------------ | ------- | ----------------------------------------- |
| `type`   | `'spring'`         | -       | Animation type (must be `'spring'`)       |
| `config` | `WithSpringConfig` | -       | Reanimated spring animation configuration |

#### TimingAnimationConfig

| prop     | type               | default | description                               |
| -------- | ------------------ | ------- | ----------------------------------------- |
| `type`   | `'timing'`         | -       | Animation type (must be `'timing'`)       |
| `config` | `WithTimingConfig` | -       | Reanimated timing animation configuration |

### Select.Trigger

| prop                | type             | default | description                                             |
| ------------------- | ---------------- | ------- | ------------------------------------------------------- |
| `children`          | `ReactNode`      | -       | The trigger element content                             |
| `className`         | `string`         | -       | Additional CSS classes for the trigger                  |
| `asChild`           | `boolean`        | `true`  | Whether to render as a child element                    |
| `...PressableProps` | `PressableProps` | -       | All standard React Native Pressable props are supported |

### Select.Value

| prop           | type        | default | description                                        |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `placeholder`  | `string`    | -       | Placeholder text when no value is selected         |
| `className`    | `string`    | -       | Additional CSS classes for the value               |
| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |

### Select.Portal

| prop           | type        | default | description                                        |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `children`     | `ReactNode` | -       | The portal content (required)                      |
| `className`    | `string`    | -       | Additional CSS classes for the portal container    |
| `hostName`     | `string`    | -       | Optional name of the host element for the portal   |
| `forceMount`   | `boolean`   | -       | Whether to force mount the component in the DOM    |
| `...ViewProps` | `ViewProps` | -       | All standard React Native View props are supported |

### Select.Overlay

| prop                    | type                     | default | description                                         |
| ----------------------- | ------------------------ | ------- | --------------------------------------------------- |
| `className`             | `string`                 | -       | Additional CSS classes for the overlay              |
| `animation`             | `SelectOverlayAnimation` | -       | Animation configuration                             |
| `closeOnPress`          | `boolean`                | `true`  | Whether to close the select when overlay is pressed |
| `forceMount`            | `boolean`                | -       | Whether to force mount the component in the DOM     |
| `asChild`               | `boolean`                | `false` | Whether to render as a child element                |
| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | All Reanimated Animated.View props are supported    |

#### SelectOverlayAnimation

Animation configuration for Select.Overlay component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop            | type                       | default     | description                         |
| --------------- | -------------------------- | ----------- | ----------------------------------- |
| `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values \[idle, open, close] |

### Select.Content (Popover Presentation)

| prop                    | type                                             | default         | description                                            |
| ----------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------ |
| `children`              | `ReactNode`                                      | -               | The select content                                     |
| `width`                 | `number \| 'trigger' \| 'content-fit' \| 'full'` | `'content-fit'` | Width sizing strategy for the content                  |
| `presentation`          | `'popover'`                                      | `'popover'`     | Presentation mode for the select                       |
| `placement`             | `'top' \| 'bottom' \| 'left' \| 'right'`         | `'bottom'`      | Placement of the content relative to trigger           |
| `align`                 | `'start' \| 'center' \| 'end'`                   | `'center'`      | Alignment along the placement axis                     |
| `avoidCollisions`       | `boolean`                                        | `true`          | Whether to flip placement when close to viewport edges |
| `offset`                | `number`                                         | `8`             | Distance from trigger element in pixels                |
| `alignOffset`           | `number`                                         | `0`             | Offset along the alignment axis in pixels              |
| `className`             | `string`                                         | -               | Additional CSS classes for the content container       |
| `animation`             | `SelectContentPopoverAnimation`                  | -               | Animation configuration                                |
| `forceMount`            | `boolean`                                        | -               | Whether to force mount the component in the DOM        |
| `insets`                | `Insets`                                         | -               | Screen edge insets to respect when positioning         |
| `asChild`               | `boolean`                                        | `false`         | Whether to render as a child element                   |
| `...Animated.ViewProps` | `Animated.ViewProps`                             | -               | All Reanimated Animated.View props are supported       |

#### SelectContentPopoverAnimation

Animation configuration for Select.Content component (popover presentation). Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop                    | type                       | default            | description                            |
| ----------------------- | -------------------------- | ------------------ | -------------------------------------- |
| `opacity.value`         | `[number, number, number]` | `[0, 1, 0]`        | Opacity values \[idle, open, close]    |
| `scale.value`           | `[number, number, number]` | `[0.95, 1, 0.95]`  | Scale values \[idle, open, close]      |
| `translateX.value`      | `[number, number, number]` | Based on placement | TranslateX values \[idle, open, close] |
| `translateY.value`      | `[number, number, number]` | Based on placement | TranslateY values \[idle, open, close] |
| `transformOrigin.value` | `string`                   | Based on placement | Transform origin value                 |

### Select.Content (Bottom Sheet Presentation)

| prop                       | type               | default | description                                      |
| -------------------------- | ------------------ | ------- | ------------------------------------------------ |
| `children`                 | `ReactNode`        | -       | The bottom sheet content                         |
| `presentation`             | `'bottom-sheet'`   | -       | Presentation mode for the select                 |
| `bottomSheetViewClassName` | `string`           | -       | Additional CSS classes for the bottom sheet view |
| `...BottomSheetProps`      | `BottomSheetProps` | -       | All @gorhom/bottom-sheet props are supported     |

### Select.Content (Dialog Presentation)

| prop                    | type                                     | default | description                                         |
| ----------------------- | ---------------------------------------- | ------- | --------------------------------------------------- |
| `children`              | `ReactNode`                              | -       | The dialog content                                  |
| `presentation`          | `'dialog'`                               | -       | Presentation mode for the select                    |
| `classNames`            | `{ wrapper?: string; content?: string }` | -       | Additional CSS classes for wrapper and content      |
| `animation`             | `SelectContentAnimation`                 | -       | Animation configuration                             |
| `isSwipeable`           | `boolean`                                | `true`  | Whether the dialog content can be swiped to dismiss |
| `forceMount`            | `boolean`                                | -       | Whether to force mount the component in the DOM     |
| `asChild`               | `boolean`                                | `false` | Whether to render as a child element                |
| `...Animated.ViewProps` | `Animated.ViewProps`                     | -       | All Reanimated Animated.View props are supported    |

#### SelectContentAnimation

Animation configuration for Select.Content component (dialog presentation). Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop            | type                       | default           | description                         |
| --------------- | -------------------------- | ----------------- | ----------------------------------- |
| `opacity.value` | `[number, number, number]` | `[0, 1, 0]`       | Opacity values \[idle, open, close] |
| `scale.value`   | `[number, number, number]` | `[0.97, 1, 0.97]` | Scale values \[idle, open, close]   |

### Select.Close

| prop                | type                   | default | description                                             |
| ------------------- | ---------------------- | ------- | ------------------------------------------------------- |
| `children`          | `ReactNode`            | -       | The close button content                                |
| `className`         | `string`               | -       | Additional CSS classes for the close button             |
| `iconProps`         | `SelectCloseIconProps` | -       | Close icon configuration                                |
| `asChild`           | `boolean`              | -       | Whether to render as a child element                    |
| `...PressableProps` | `PressableProps`       | -       | All standard React Native Pressable props are supported |

#### SelectCloseIconProps

| prop    | type     | default          | description       |
| ------- | -------- | ---------------- | ----------------- |
| `size`  | `number` | `18`             | Size of the icon  |
| `color` | `string` | `--colors-muted` | Color of the icon |

### Select.ListLabel

| prop           | type        | default | description                                        |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `children`     | `ReactNode` | -       | The label text content                             |
| `className`    | `string`    | -       | Additional CSS classes for the list label          |
| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |

### Select.Item

| prop                | type                                                         | default | description                                                                |
| ------------------- | ------------------------------------------------------------ | ------- | -------------------------------------------------------------------------- |
| `children`          | `ReactNode \| ((props: SelectItemRenderProps) => ReactNode)` | -       | Custom item content. Defaults to label and indicator, or a render function |
| `value`             | `any`                                                        | -       | The value associated with this item (required)                             |
| `label`             | `string`                                                     | -       | The label text for this item (required)                                    |
| `isDisabled`        | `boolean`                                                    | `false` | Whether this item is disabled                                              |
| `className`         | `string`                                                     | -       | Additional CSS classes for the item                                        |
| `...PressableProps` | `PressableProps`                                             | -       | All standard React Native Pressable props are supported                    |

#### SelectItemRenderProps

When using a render function for `children`, the following props are provided:

| property     | type      | description                             |
| ------------ | --------- | --------------------------------------- |
| `isSelected` | `boolean` | Whether this item is currently selected |
| `value`      | `string`  | The value of the item                   |
| `isDisabled` | `boolean` | Whether the item is disabled            |

### Select.ItemLabel

| prop           | type        | default | description                                        |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `className`    | `string`    | -       | Additional CSS classes for the item label          |
| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |

### Select.ItemDescription

| prop           | type        | default | description                                        |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `children`     | `ReactNode` | -       | The description text content                       |
| `className`    | `string`    | -       | Additional CSS classes for the item description    |
| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |

### Select.ItemIndicator

| prop           | type                           | default | description                                        |
| -------------- | ------------------------------ | ------- | -------------------------------------------------- |
| `children`     | `ReactNode`                    | -       | Custom indicator content. Defaults to check icon   |
| `className`    | `string`                       | -       | Additional CSS classes for the item indicator      |
| `iconProps`    | `SelectItemIndicatorIconProps` | -       | Check icon configuration                           |
| `...ViewProps` | `ViewProps`                    | -       | All standard React Native View props are supported |

#### SelectItemIndicatorIconProps

| prop    | type     | default          | description       |
| ------- | -------- | ---------------- | ----------------- |
| `size`  | `number` | `16`             | Size of the icon  |
| `color` | `string` | `--colors-muted` | Color of the icon |

## Hooks

### useSelect

Hook to access the Select root context. Returns the select state and control functions.

```tsx
import { useSelect } from 'heroui-native';

const {
  isOpen,
  onOpenChange,
  isDefaultOpen,
  isDisabled,
  triggerPosition,
  setTriggerPosition,
  contentLayout,
  setContentLayout,
  nativeID,
  closeDelay,
  value,
  onValueChange,
} = useSelect();

```

#### Return Value

| property             | type                                         | description                                               |
| -------------------- | -------------------------------------------- | --------------------------------------------------------- |
| `isOpen`             | `boolean`                                    | Whether the select is currently open                      |
| `onOpenChange`       | `(open: boolean) => void`                    | Callback to change the open state                         |
| `isDefaultOpen`      | `boolean \| undefined`                       | Whether the select is open by default (uncontrolled mode) |
| `isDisabled`         | `boolean \| undefined`                       | Whether the select is disabled                            |
| `triggerPosition`    | `LayoutPosition \| null`                     | Position of the trigger element relative to viewport      |
| `setTriggerPosition` | `(position: LayoutPosition \| null) => void` | Updates the trigger element's position                    |
| `contentLayout`      | `LayoutRectangle \| null`                    | Layout measurements of the select content                 |
| `setContentLayout`   | `(layout: LayoutRectangle \| null) => void`  | Updates the content layout measurements                   |
| `nativeID`           | `string`                                     | Unique identifier for the select instance                 |
| `closeDelay`         | `number \| undefined`                        | Delay in milliseconds before the select closes            |
| `value`              | `SelectOption`                               | Currently selected option                                 |
| `onValueChange`      | `(option: SelectOption) => void`             | Callback fired when the selected value changes            |

**Note:** This hook must be used within a `Select` component. It will throw an error if called outside of the select context.

### useSelectAnimation

Hook to access the Select animation state values within custom components or compound components.

```tsx
import { useSelectAnimation } from 'heroui-native';

const { selectState, progress, isDragging, isGestureReleaseAnimationRunning } =
  useSelectAnimation();

```

#### Return Value

| property                           | type                          | description                                                |
| ---------------------------------- | ----------------------------- | ---------------------------------------------------------- |
| `selectState`                      | `'idle' \| 'open' \| 'close'` | Extended internal state for coordinating animations        |
| `progress`                         | `SharedValue<number>`         | Progress value for animations (0=idle, 1=open, 2=close)    |
| `isDragging`                       | `SharedValue<boolean>`        | Whether the select content is currently being dragged      |
| `isGestureReleaseAnimationRunning` | `SharedValue<boolean>`        | Whether the gesture release animation is currently running |

**Note:** This hook must be used within a `Select` component. It will throw an error if called outside of the select animation context.

#### SelectOption

| property | type     | description                  |
| -------- | -------- | ---------------------------- |
| `value`  | `string` | The value of the option      |
| `label`  | `string` | The label text of the option |

### useSelectItem

Hook to access the Select Item context. Returns the item's value and label.

```tsx
import { useSelectItem } from 'heroui-native';

const { itemValue, label } = useSelectItem();

```

#### Return Value

| property    | type     | description                        |
| ----------- | -------- | ---------------------------------- |
| `itemValue` | `string` | The value of the current item      |
| `label`     | `string` | The label text of the current item |

</page>

<page url="/docs/native/components/switch">
# Switch

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/switch
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/switch.mdx
> A toggle control that allows users to switch between on and off states.

## Import

```tsx
import { Switch } from 'heroui-native';

```

## Anatomy

```tsx
<Switch>
  <Switch.Thumb>...</Switch.Thumb>
  <Switch.StartContent>...</Switch.StartContent>
  <Switch.EndContent>...</Switch.EndContent>
</Switch>

```

* **Switch**: Main container that handles toggle state and user interaction. Renders default thumb if no children provided. Animates scale (on press) and background color based on selection state. Acts as a pressable area for toggling.
* **Switch.Thumb**: Optional sliding thumb element that moves between positions. Uses spring animation for smooth transitions. Can contain custom content like icons or be customized with different styles and animations.
* **Switch.StartContent**: Optional content displayed on the left side of the switch. Typically used for icons or text that appear when switch is off. Positioned absolutely within the switch container.
* **Switch.EndContent**: Optional content displayed on the right side of the switch. Typically used for icons or text that appear when switch is on. Positioned absolutely within the switch container.

## Usage

### Basic Usage

The Switch component renders with default thumb if no children provided.

```tsx
<Switch isSelected={isSelected} onSelectedChange={setIsSelected} />

```

### With Custom Thumb

Replace the default thumb with custom content using the Thumb component.

```tsx
<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
  <Switch.Thumb>...</Switch.Thumb>
</Switch>

```

### With Start and End Content

Add icons or text that appear on each side of the switch.

```tsx
<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
  <Switch.Thumb />
  <Switch.StartContent>...</Switch.StartContent>
  <Switch.EndContent>...</Switch.EndContent>
</Switch>

```

### With Render Function

Use render functions for dynamic content based on switch state.

```tsx
<Switch isSelected={isSelected} onSelectedChange={setIsSelected}>
  {({ isSelected, isDisabled }) => (
    <>
      <Switch.Thumb>
        {({ isSelected }) => (isSelected ? <CheckIcon /> : <XIcon />)}
      </Switch.Thumb>
    </>
  )}
</Switch>

```

### With Custom Animations

Customize animations for the switch root and thumb components.

```tsx
<Switch
  animation={{
    scale: {
      value: [1, 0.9],
      timingConfig: { duration: 200 },
    },
    backgroundColor: {
      value: ['#172554', '#eab308'],
    },
  }}
>
  <Switch.Thumb
    animation={{
      left: {
        value: 4,
        springConfig: {
          damping: 30,
          stiffness: 300,
          mass: 1,
        },
      },
      backgroundColor: {
        value: ['#dbeafe', '#854d0e'],
      },
    }}
  />
</Switch>

```

### Disable Animations

Disable animations entirely or only for specific components.

```tsx
{
  /* Disable all animations including children */
}
<Switch animation="disable-all">
  <Switch.Thumb />
</Switch>;

{
  /* Disable only root animations, thumb can still animate */
}
<Switch>
  <Switch.Thumb animation={false} />
</Switch>;

```

## Example

```tsx
import { Switch } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import React from 'react';
import { View } from 'react-native';
import Animated, { ZoomIn } from 'react-native-reanimated';

export default function SwitchExample() {
  const [darkMode, setDarkMode] = React.useState(false);

return (
    <View className="flex-row gap-4">
      <Switch
        isSelected={darkMode}
        onSelectedChange={setDarkMode}
        className="w-[56px] h-[32px]"
        animation={{
          backgroundColor: {
            value: ['#172554', '#eab308'],
          },
        }}
      >
        <Switch.Thumb
          className="size-[22px]"
          animation={{
            left: {
              value: 4,
              springConfig: {
                damping: 30,
                stiffness: 300,
                mass: 1,
              },
            },
          }}
        />
        <Switch.StartContent className="left-2">
          {darkMode && (
            <Animated.View key="sun" entering={ZoomIn.springify()}>
              <Ionicons name="sunny" size={16} color="#854d0e" />
            </Animated.View>
          )}
        </Switch.StartContent>
        <Switch.EndContent className="right-2">
          {!darkMode && (
            <Animated.View key="moon" entering={ZoomIn.springify()}>
              <Ionicons name="moon" size={16} color="#dbeafe" />
            </Animated.View>
          )}
        </Switch.EndContent>
      </Switch>
    </View>
  );
}

```

## API Reference

### Switch

| prop                        | type                                                                 | default     | description                                                  |
| --------------------------- | -------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ |
| `children`                  | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | Content to render inside the switch, or a render function    |
| `isSelected`                | `boolean`                                                            | `undefined` | Whether the switch is currently selected                     |
| `isDisabled`                | `boolean`                                                            | `false`     | Whether the switch is disabled and cannot be interacted with |
| `className`                 | `string`                                                             | `undefined` | Custom class name for the switch                             |
| `animation`                 | `SwitchRootAnimation`                                                | -           | Animation configuration                                      |
| `onSelectedChange`          | `(isSelected: boolean) => void`                                      | -           | Callback fired when the switch selection state changes       |
| `...AnimatedPressableProps` | `AnimatedProps<PressableProps>`                                      | -           | All React Native Reanimated Pressable props are supported    |

#### SwitchRenderProps

| prop         | type      | description                    |
| ------------ | --------- | ------------------------------ |
| `isSelected` | `boolean` | Whether the switch is selected |
| `isDisabled` | `boolean` | Whether the switch is disabled |

#### SwitchRootAnimation

Animation configuration for Switch component. Can be:

| prop                           | type               | default                                                        | description                                     |
| ------------------------------ | ------------------ | -------------------------------------------------------------- | ----------------------------------------------- |
| `scale.value`                  | `[number, number]` | `[1, 0.96]`                                                    | Scale values \[unpressed, pressed]              |
| `scale.timingConfig`           | `WithTimingConfig` | `{ duration: 150 }`                                            | Animation timing configuration                  |
| `backgroundColor.value`        | `[string, string]` | Uses theme colors                                              | Background color values \[unselected, selected] |
| `backgroundColor.timingConfig` | `WithTimingConfig` | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | Animation timing configuration                  |

### Switch.Thumb

| prop           | type                                                                 | default     | description                                              |
| -------------- | -------------------------------------------------------------------- | ----------- | -------------------------------------------------------- |
| `children`     | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | Content to render inside the thumb, or a render function |
| `className`    | `string`                                                             | `undefined` | Custom class name for the thumb element                  |
| `animation`    | `SwitchThumbAnimation`                                               | -           | Animation configuration                                  |
| `...ViewProps` | `ViewProps`                                                          | -           | All standard React Native View props are supported       |

#### SwitchThumbAnimation

Animation configuration for Switch.Thumb component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop                           | type               | default                                                        | description                                                             |
| ------------------------------ | ------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `left.value`                   | `number`           | `2`                                                            | Offset value from the edges (left when unselected, right when selected) |
| `left.springConfig`            | `WithSpringConfig` | `{ damping: 120, stiffness: 1600, mass: 2 }`                   | Spring animation configuration for thumb position                       |
| `backgroundColor.value`        | `[string, string]` | `['white', theme accent-foreground color]`                     | Background color values \[unselected, selected]                         |
| `backgroundColor.timingConfig` | `WithTimingConfig` | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | Animation timing configuration                                          |

### Switch.StartContent

| prop           | type              | default     | description                                        |
| -------------- | ----------------- | ----------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | `undefined` | Content to render inside the switch content        |
| `className`    | `string`          | `undefined` | Custom class name for the content element          |
| `...ViewProps` | `ViewProps`       | -           | All standard React Native View props are supported |

### Switch.EndContent

## Hooks

### useSwitch

A hook that provides access to the Switch context. This is useful when building custom switch components or when you need to access switch state in child components.

**Returns:**

| Property     | Type      | Description                    |
| ------------ | --------- | ------------------------------ |
| `isSelected` | `boolean` | Whether the switch is selected |
| `isDisabled` | `boolean` | Whether the switch is disabled |

**Example:**

```tsx
import { useSwitch } from 'heroui-native';

function CustomSwitchContent() {
  const { isSelected, isDisabled } = useSwitch();

return (
    <View>
      <Text>Status: {isSelected ? 'On' : 'Off'}</Text>
      {isDisabled && <Text>Disabled</Text>}
    </View>
  );
}

// Usage
<Switch>
  <CustomSwitchContent />
  <Switch.Thumb />
</Switch>;

```

## Special Notes

### Border Styling

If you need to apply a border to the switch root, use the `outline` style properties instead of `border`. This ensures the border doesn't affect the internal layout calculations for the thumb position:

```tsx
<Switch className="outline outline-accent">
  <Switch.Thumb />
</Switch>

```

Using `outline` keeps the border visual without impacting the switch's internal width calculations, ensuring the thumb animates correctly.

### Integration with FormField

The Switch component integrates seamlessly with FormField for press state sharing:

```tsx
<FormField isSelected={isSelected} onSelectedChange={setIsSelected}>
  <View className="flex-1">
    <FormField.Label>Enable notifications</FormField.Label>
    <FormField.Description>Receive push notifications</FormField.Description>
  </View>
  <FormField.Indicator />
</FormField>

```

When wrapped in FormField, the Switch will automatically respond to press events on the entire FormField container, creating a larger touch target and better user experience.

</page>

<page url="/docs/native/components/text-field">
# TextField

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/text-field
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/text-field.mdx
> A text input component with label, description, and error handling for collecting user input.

## Import

```tsx
import { TextField } from 'heroui-native';

```

## Anatomy

```tsx
<TextField>
  <TextField.Label>...</TextField.Label>
  <TextField.Input>
    <TextField.InputStartContent>...</TextField.InputStartContent>
    <TextField.InputEndContent>...</TextField.InputEndContent>
  </TextField.Input>
  <TextField.Description>...</TextField.Description>
  <TextField.ErrorMessage>...</TextField.ErrorMessage>
</TextField>

```

* **TextField**: Root container that provides spacing and state management
* **TextField.Label**: Label with optional asterisk for required fields
* **TextField.Input**: Input container with animated border and background
* **TextField.InputStartContent**: Optional content at the start of the input
* **TextField.InputEndContent**: Optional content at the end of the input
* **TextField.Description**: Helper text displayed below the input
* **TextField.ErrorMessage**: Error message shown when field is invalid

## Usage

### Basic Usage

TextField provides a complete form input structure with label and description.

```tsx
<TextField>
  <TextField.Label>Email</TextField.Label>
  <TextField.Input placeholder="Enter your email" />
  <TextField.Description>We'll never share your email</TextField.Description>
</TextField>

```

### With Required Field

Mark fields as required to show an asterisk in the label.

```tsx
<TextField isRequired>
  <TextField.Label>Username</TextField.Label>
  <TextField.Input placeholder="Choose a username" />
</TextField>

```

### With Start and End Content

Add icons or other content at the beginning or end of the input.

```tsx
<TextField>
  <TextField.Label>Password</TextField.Label>
  <TextField.Input placeholder="Enter password" secureTextEntry>
    <TextField.InputStartContent>...</TextField.InputStartContent>
    <TextField.InputEndContent>...</TextField.InputEndContent>
  </TextField.Input>
</TextField>

```

### With Validation

Display error messages when the field is invalid.

```tsx
<TextField isRequired isInvalid={true}>
  <TextField.Label>Email</TextField.Label>
  <TextField.Input placeholder="Enter your email" />
  <TextField.ErrorMessage>Please enter a valid email</TextField.ErrorMessage>
</TextField>

```

### With Local Invalid State Override

Override the context's invalid state for individual components.

```tsx
<TextField isInvalid={true}>
  <TextField.Label isInvalid={false}>Email</TextField.Label>
  <TextField.Input placeholder="Enter your email" isInvalid={false} />
  <TextField.Description>
    This shows despite input being invalid
  </TextField.Description>
  <TextField.ErrorMessage>Email format is incorrect</TextField.ErrorMessage>
</TextField>

```

### Multiline Input

Create text areas for longer content.

```tsx
<TextField>
  <TextField.Label>Message</TextField.Label>
  <TextField.Input
    placeholder="Type your message..."
    multiline
    numberOfLines={4}
  />
  <TextField.Description>Maximum 500 characters</TextField.Description>
</TextField>

```

### Disabled State

Disable the entire field to prevent interaction.

```tsx
<TextField isDisabled>
  <TextField.Label>Disabled Field</TextField.Label>
  <TextField.Input placeholder="Cannot edit" value="Read only value" />
</TextField>

```

### Custom Colors

Customize the input colors for different states using the animation prop.

```tsx
<TextField>
  <TextField.Label>Custom Styled</TextField.Label>
  <TextField.Input
    placeholder="Custom colors"
    animation={{
      backgroundColor: {
        value: {
          blur: '#eff6ff',
          focus: '#dbeafe',
          error: '#eff6ff',
        },
      },
      borderColor: {
        value: {
          blur: '#2563eb',
          focus: '#1d4ed8',
          error: '#dc2626',
        },
      },
    }}
  />
</TextField>

```

## Example

```tsx
import { Ionicons } from '@expo/vector-icons';
import { TextField, useThemeColor } from 'heroui-native';
import React from 'react';
import { ScrollView, View } from 'react-native';

export default function TextFieldExample() {
  const themeColorMuted = useThemeColor('muted');
  const [email, setEmail] = React.useState('');
  const isInvalidEmail =
    email !== '' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email);

return (
    <ScrollView className="bg-background p-6">
      <View className="gap-6">
        <TextField isRequired isInvalid={isInvalidEmail}>
          <TextField.Label>Email Address</TextField.Label>
          <TextField.Input
            placeholder="Enter your email"
            keyboardType="email-address"
            autoCapitalize="none"
            value={email}
            onChangeText={setEmail}
          >
            <TextField.InputStartContent>
              <Ionicons name="mail-outline" size={16} color={themeColorMuted} />
            </TextField.InputStartContent>
          </TextField.Input>
          <TextField.Description>
            We'll send a confirmation to this email
          </TextField.Description>
          <TextField.ErrorMessage>
            Please enter a valid email address
          </TextField.ErrorMessage>
        </TextField>

<TextField isRequired>
          <TextField.Label>Password</TextField.Label>
          <TextField.Input placeholder="Enter password" secureTextEntry>
            <TextField.InputStartContent>
              <Ionicons
                name="lock-closed-outline"
                size={16}
                color={themeColorMuted}
              />
            </TextField.InputStartContent>
            <TextField.InputEndContent>
              <Ionicons name="eye-outline" size={16} color={themeColorMuted} />
            </TextField.InputEndContent>
          </TextField.Input>
        </TextField>

<TextField>
          <TextField.Label>Bio</TextField.Label>
          <TextField.Input
            placeholder="Tell us about yourself..."
            multiline
            numberOfLines={4}
          />
          <TextField.Description>
            Brief description for your profile
          </TextField.Description>
        </TextField>
      </View>
    </ScrollView>
  );
}

```

## API Reference

### TextField

| prop         | type                         | default     | description                                                                               |
| ------------ | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| children     | `React.ReactNode`            | -           | Content to render inside the text field                                                   |
| isDisabled   | `boolean`                    | `false`     | Whether the entire text field is disabled                                                 |
| isInvalid    | `boolean`                    | `false`     | Whether the text field is in an invalid state                                             |
| isRequired   | `boolean`                    | `false`     | Whether the text field is required (shows asterisk)                                       |
| className    | `string`                     | -           | Custom class name for the root element                                                    |
| animation    | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
| ...ViewProps | `ViewProps`                  | -           | All standard React Native View props are supported                                        |

### TextField.Label

| prop                  | type                       | default     | description                                                  |
| --------------------- | -------------------------- | ----------- | ------------------------------------------------------------ |
| children              | `React.ReactNode`          | -           | Label text content                                           |
| isInvalid             | `boolean`                  | `undefined` | Whether the label is in an invalid state (overrides context) |
| className             | `string`                   | -           | Custom class name for the label element                      |
| classNames            | `ElementSlots<LabelSlots>` | -           | Custom class names for different parts of the label          |
| animation             | `TextFieldLabelAnimation`  | -           | Animation configuration                                      |
| ...Animated.TextProps | `AnimatedProps<TextProps>` | -           | All Reanimated Animated.Text props are supported             |

#### `ElementSlots<LabelSlots>`

| prop     | type     | description                          |
| -------- | -------- | ------------------------------------ |
| text     | `string` | Custom class name for the label text |
| asterisk | `string` | Custom class name for the asterisk   |

#### TextFieldLabelAnimation

Animation configuration for TextField.Label component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop             | type                    | default                                                                 | description               |
| ---------------- | ----------------------- | ----------------------------------------------------------------------- | ------------------------- |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br />`.duration(150)`<br />`.easing(Easing.out(Easing.ease))`  | Custom entering animation |
| `exiting.value`  | `EntryOrExitLayoutType` | `FadeOut`<br />`.duration(150)`<br />`.easing(Easing.out(Easing.ease))` | Custom exiting animation  |

### TextField.Input

| prop              | type                       | default     | description                                                  |
| ----------------- | -------------------------- | ----------- | ------------------------------------------------------------ |
| children          | `React.ReactNode`          | -           | Content to render inside the input container                 |
| isInvalid         | `boolean`                  | `undefined` | Whether the input is in an invalid state (overrides context) |
| className         | `string`                   | -           | Custom class name for the input container                    |
| classNames        | `ElementSlots<InputSlots>` | -           | Custom class names for different parts of the input          |
| animation         | `TextFieldInputAnimation`  | -           | Animation configuration                                      |
| ...TextInputProps | `TextInputProps`           | -           | All standard React Native TextInput props are supported      |

#### `ElementSlots<InputSlots>`

| prop      | type     | description                                  |
| --------- | -------- | -------------------------------------------- |
| container | `string` | Custom class name for the input container    |
| input     | `string` | Custom class name for the text input element |

#### TextFieldInputAnimation

Animation configuration for TextField.Input component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop                                          | type               | default                                              | description                                                     |
| --------------------------------------------- | ------------------ | ---------------------------------------------------- | --------------------------------------------------------------- |
| `backgroundColor`<br />`.value`<br />`.blur`  | `string`           | Uses theme color                                     | Background color when input is blurred                          |
| `backgroundColor`<br />`.value`<br />`.focus` | `string`           | Uses theme color                                     | Background color when input is focused                          |
| `backgroundColor`<br />`.value`<br />`.error` | `string`           | Uses theme color                                     | Background color when input is invalid                          |
| `backgroundColor`<br />`.timingConfig`        | `WithTimingConfig` | `{ duration: 150, easing: Easing.out(Easing.ease) }` | Animation timing configuration for background color transitions |
| `borderColor`<br />`.value`<br />`.blur`      | `string`           | Uses theme color                                     | Border color when input is blurred                              |
| `borderColor`<br />`.value`<br />`.focus`     | `string`           | Uses theme color                                     | Border color when input is focused                              |
| `borderColor`<br />`.value`<br />`.error`     | `string`           | Uses theme color                                     | Border color when input is invalid                              |
| `borderColor`<br />`.timingConfig`            | `WithTimingConfig` | `{ duration: 150, easing: Easing.out(Easing.ease) }` | Animation timing configuration for border color transitions     |

### TextField.InputStartContent

| prop         | type              | default | description                                        |
| ------------ | ----------------- | ------- | -------------------------------------------------- |
| children     | `React.ReactNode` | -       | Content to render at the start of the input        |
| className    | `string`          | -       | Custom class name for the start content element    |
| ...ViewProps | `ViewProps`       | -       | All standard React Native View props are supported |

### TextField.InputEndContent

| prop         | type              | default | description                                        |
| ------------ | ----------------- | ------- | -------------------------------------------------- |
| children     | `React.ReactNode` | -       | Content to render at the end of the input          |
| className    | `string`          | -       | Custom class name for the end content element      |
| ...ViewProps | `ViewProps`       | -       | All standard React Native View props are supported |

### TextField.Description

| prop                  | type                            | default     | description                                                        |
| --------------------- | ------------------------------- | ----------- | ------------------------------------------------------------------ |
| children              | `React.ReactNode`               | -           | Description text content                                           |
| isInvalid             | `boolean`                       | `undefined` | Whether the description is in an invalid state (overrides context) |
| className             | `string`                        | -           | Custom class name for the description element                      |
| animation             | `TextFieldDescriptionAnimation` | -           | Animation configuration                                            |
| ...Animated.TextProps | `AnimatedProps<TextProps>`      | -           | All Reanimated Animated.Text props are supported                   |

#### TextFieldDescriptionAnimation

Animation configuration for TextField.Description component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop             | type                    | default                                                                 | description               |
| ---------------- | ----------------------- | ----------------------------------------------------------------------- | ------------------------- |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br />`.duration(150)`<br />`.easing(Easing.out(Easing.ease))`  | Custom entering animation |
| `exiting.value`  | `EntryOrExitLayoutType` | `FadeOut`<br />`.duration(150)`<br />`.easing(Easing.out(Easing.ease))` | Custom exiting animation  |

### TextField.ErrorMessage

> **Note**: `TextField.ErrorMessage` extends `ErrorView` component. For complete API reference, see [ErrorView documentation](error-view).

## Hooks

### useTextField

Hook to access the TextField context values. Must be used within a `TextField` component.

```tsx
import { TextField, useTextField } from 'heroui-native';

function CustomComponent() {
  const { isDisabled, isInvalid, isRequired } = useTextField();

// Use the context values...
}

```

#### Returns

| property   | type      | description                                   |
| ---------- | --------- | --------------------------------------------- |
| isDisabled | `boolean` | Whether the entire text field is disabled     |
| isInvalid  | `boolean` | Whether the text field is in an invalid state |
| isRequired | `boolean` | Whether the text field is required            |

</page>

<page url="/docs/native/components/card">
# Card

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/card
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(layout)/card.mdx
> Displays a card container with flexible layout sections for structured content.

## Import

```tsx
import { Card } from 'heroui-native';

```

## Anatomy

```tsx
<Card>
  <Card.Header>...</Card.Header>
  <Card.Body>
    <Card.Title>...</Card.Title>
    <Card.Description>...</Card.Description>
  </Card.Body>
  <Card.Footer>...</Card.Footer>
</Card>

```

* **Card**: Main container that extends Surface component. Provides base card structure with configurable surface variants and handles overall layout.
* **Card.Header**: Header section for top-aligned content like icons or badges.
* **Card.Body**: Main content area with flex-1 that expands to fill all available space between Card.Header and Card.Footer.
* **Card.Title**: Title text with foreground color and medium font weight.
* **Card.Description**: Description text with muted color and smaller font size.
* **Card.Footer**: Footer section for bottom-aligned actions like buttons.

## Usage

### Basic Usage

The Card component creates a container with built-in sections for organized content.

```tsx
<Card>
  <Card.Body>...</Card.Body>
</Card>

```

### With Title and Description

Combine title and description components for structured text content.

```tsx
<Card>
  <Card.Body>
    <Card.Title>...</Card.Title>
    <Card.Description>...</Card.Description>
  </Card.Body>
</Card>

```

### With Header and Footer

Add header and footer sections for icons, badges, or actions.

```tsx
<Card>
  <Card.Header>...</Card.Header>
  <Card.Body>...</Card.Body>
  <Card.Footer>...</Card.Footer>
</Card>

```

### Variants

Control the card's background appearance using different variants.

```tsx
<Card variant="default">...</Card>
<Card variant="secondary">...</Card>
<Card variant="tertiary">...</Card>
<Card variant="quaternary">...</Card>
<Card variant="transparent">...</Card>

```

### Horizontal Layout

Create horizontal cards by using flex-row styling.

```tsx
<Card className="flex-row gap-4">
  <Image source={...} className="size-24 rounded-lg" />
</Card>

```

### Background Image

Use an image as an absolute positioned background.

```tsx
<Card>
  <Image source={...} className="absolute inset-0" />
  <View className="gap-4">...</View>
</Card>

```

## Example

```tsx
import { Button, Card } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import { View } from 'react-native';

export default function CardExample() {
  return (
    <Card>
      <View className="gap-4">
        <Card.Body className="mb-4">
          <View className="gap-1 mb-2">
            <Card.Title className="text-pink-500">$450</Card.Title>
            <Card.Title>Living room Sofa • Collection 2025</Card.Title>
          </View>
          <Card.Description>
            This sofa is perfect for modern tropical spaces, baroque inspired
            spaces.
          </Card.Description>
        </Card.Body>
        <Card.Footer className="gap-3">
          <Button variant="primary">Buy now</Button>
          <Button variant="ghost">
            <Button.Label>Add to cart</Button.Label>
            <Ionicons name="bag-outline" size={16} />
          </Button>
        </Card.Footer>
      </View>
    </Card>
  );
}

```

## API Reference

### Card

| prop           | type                                                                      | default     | description                                                                               |
| -------------- | ------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children`     | `React.ReactNode`                                                         | -           | Content to be rendered inside the card                                                    |
| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'quaternary' \| 'transparent'` | `'default'` | Visual variant of the card surface                                                        |
| `className`    | `string`                                                                  | -           | Additional CSS classes to apply                                                           |
| `animation`    | `"disable-all" \| undefined`                                              | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
| `...ViewProps` | `ViewProps`                                                               | -           | All standard React Native View props are supported                                        |

### Card.Header

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the header |
| `className`    | `string`          | -       | Additional CSS classes                             |
| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |

### Card.Body

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the body   |
| `className`    | `string`          | -       | Additional CSS classes                             |
| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |

### Card.Footer

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the footer |
| `className`    | `string`          | -       | Additional CSS classes                             |
| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |

### Card.Title

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Children elements to be rendered as the title text |
| `className`    | `string`          | -       | Additional CSS classes                             |
| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |

### Card.Description

| prop           | type              | default | description                                              |
| -------------- | ----------------- | ------- | -------------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Children elements to be rendered as the description text |
| `className`    | `string`          | -       | Additional CSS classes                                   |
| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported       |

</page>

<page url="/docs/native/components/divider">
# Divider

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/divider
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(layout)/divider.mdx
> A simple line to separate content visually.

## Import

```tsx
import { Divider } from 'heroui-native';

```

## Anatomy

```tsx
<Divider />

```

* **Divider**: A simple line component that separates content visually. Can be oriented horizontally or vertically, with customizable thickness and variant styles.

## Usage

### Basic Usage

The Divider component creates a visual separation between content sections.

```tsx
<Divider />

```

### Orientation

Control the direction of the divider with the `orientation` prop.

```tsx
<View>
  <Text>Horizontal divider</Text>
  <Divider orientation="horizontal" />
  <Text>Content below</Text>
</View>

<View className="h-24 flex-row">
  <Text>Left</Text>
  <Divider orientation="vertical" />
  <Text>Right</Text>
</View>

```

### Variants

Choose between thin and thick variants for different visual emphasis.

```tsx
<Divider variant="thin" />
<Divider variant="thick" />

```

### Custom Thickness

Set a specific thickness value for precise control.

```tsx
<Divider thickness={1} />
<Divider thickness={5} />
<Divider thickness={10} />

```

## Example

```tsx
import { Divider, Surface } from 'heroui-native';
import { Text, View } from 'react-native';

export default function DividerExample() {
  return (
    <Surface variant="secondary" className="px-6 py-7">
      <Text className="text-base font-medium text-foreground">
        HeroUI Native
      </Text>
      <Text className="text-sm text-muted">
        A modern React Native component library.
      </Text>
      <Divider className="my-4" />
      <View className="flex-row items-center h-5">
        <Text className="text-sm text-foreground">Components</Text>
        <Divider orientation="vertical" className="mx-3" />
        <Text className="text-sm text-foreground">Themes</Text>
        <Divider orientation="vertical" className="mx-3" />
        <Text className="text-sm text-foreground">Examples</Text>
      </View>
    </Surface>
  );
}

```

## API Reference

### Divider

| prop           | type                         | default        | description                                                                                  |
| -------------- | ---------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
| `variant`      | `'thin' \| 'thick'`          | `'thin'`       | Variant style of the divider                                                                 |
| `orientation`  | `'horizontal' \| 'vertical'` | `'horizontal'` | Orientation of the divider                                                                   |
| `thickness`    | `number`                     | `undefined`    | Custom thickness in pixels. Controls height for horizontal or width for vertical orientation |
| `className`    | `string`                     | `undefined`    | Additional CSS classes to apply                                                              |
| `...ViewProps` | `ViewProps`                  | -              | All standard React Native View props are supported                                           |

</page>

<page url="/docs/native/components/surface">
# Surface

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/surface
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(layout)/surface.mdx
> Container component that provides elevation and background styling.

## Import

```tsx
import { Surface } from 'heroui-native';

```

## Anatomy

The Surface component is a container that provides elevation and background styling. It accepts children and can be customized with variants and styling props.

```tsx
<Surface>...</Surface>

```

* **Surface**: Main container component that provides consistent padding, background styling, and elevation through variants.

## Usage

### Basic Usage

The Surface component creates a container with consistent padding and styling.

```tsx
<Surface>...</Surface>

```

### Variants

Control the visual appearance with different surface levels.

```tsx
<Surface variant="default">
  ...
</Surface>

```

### Nested Surfaces

Create visual hierarchy by nesting surfaces with different variants.

```tsx
<Surface variant="default">
  ...
  <Surface variant="secondary">
    ...
    <Surface variant="tertiary">
      ...
      <Surface variant="quaternary">...</Surface>
    </Surface>
  </Surface>
</Surface>

```

### Custom Styling

Apply custom styles using className or style props.

```tsx
<Surface className="bg-accent-soft">
  ...
</Surface>

```

### Disable All Animations

Disable all animations including children by using the `"disable-all"` value for the `animation` prop.

```tsx
{
  /* Disable all animations including children */
}
<Surface animation="disable-all">No Animations</Surface>;

```

## Example

```tsx
import { Surface } from 'heroui-native';
import { Text, View } from 'react-native';

export default function SurfaceExample() {
  return (
    <View className="gap-4">
      <Surface variant="default" className="gap-2">
        <AppText className="text-foreground">Surface Content</AppText>
        <AppText className="text-muted">
          This is a default surface variant. It uses bg-surface styling.
        </AppText>
      </Surface>

<Surface variant="secondary" className="gap-2">
        <AppText className="text-foreground">Surface Content</AppText>
        <AppText className="text-muted">
          This is a secondary surface variant. It uses bg-surface-secondary
          styling.
        </AppText>
      </Surface>

<Surface variant="tertiary" className="gap-2">
        <AppText className="text-foreground">Surface Content</AppText>
        <AppText className="text-muted">
          This is a tertiary surface variant. It uses bg-surface-tertiary
          styling.
        </AppText>
      </Surface>

<Surface variant="quaternary" className="gap-2">
        <AppText className="text-foreground">Surface Content</AppText>
        <AppText className="text-muted">
          This is a quaternary surface variant. It uses bg-surface-quaternary
          styling.
        </AppText>
      </Surface>
    </View>
  );
}

```

## API Reference

### Surface

| prop           | type                                                                      | default     | description                                                                               |
| -------------- | ------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| 'quaternary' \| 'transparent'` | `'default'` | Visual variant controlling background color and border                                    |
| `children`     | `React.ReactNode`                                                         | -           | Content to be rendered inside the surface                                                 |
| `className`    | `string`                                                                  | -           | Additional CSS classes to apply                                                           |
| `animation`    | `"disable-all" \| undefined`                                              | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
| `...ViewProps` | `ViewProps`                                                               | -           | All standard React Native View props are supported                                        |

</page>

<page url="/docs/native/components/avatar">
# Avatar

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/avatar
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(media)/avatar.mdx
> Displays a user avatar with support for images, text initials, or fallback icons.

## Import

```tsx
import { Avatar } from 'heroui-native';

```

## Anatomy

```tsx
<Avatar>
  <Avatar.Image />
  <Avatar.Fallback />
</Avatar>

```

* **Avatar**: Main container that manages avatar display state. Provides size and color context to child components. Supports animation configuration to control all child animations.
* **Avatar.Image**: Optional image component that displays the avatar image. Handles loading states and errors automatically with opacity-based fade-in animation.
* **Avatar.Fallback**: Optional fallback component shown when image fails to load or is unavailable. Displays a default person icon when no children are provided. Supports configurable entering animations with delay support.

## Usage

### Basic Usage

The Avatar component displays a default person icon when no image or text is provided.

```tsx
<Avatar>
  <Avatar.Fallback />
</Avatar>

```

### With Image

Display an avatar image with automatic fallback handling.

```tsx
<Avatar>
  <Avatar.Image source={{ uri: 'https://example.com/avatar.jpg' }} />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

```

### With Text Initials

Show text initials as the avatar content.

```tsx
<Avatar>
  <Avatar.Fallback>AB</Avatar.Fallback>
</Avatar>

```

### With Custom Icon

Provide a custom icon as fallback content.

```tsx
<Avatar>
  <Avatar.Fallback>
    <Ionicons name="person" size={18} />
  </Avatar.Fallback>
</Avatar>

```

### Sizes

Control the avatar size with the size prop.

```tsx
<Avatar size="sm">
  <Avatar.Fallback />
</Avatar>

```

### Variants

Choose between different visual styles with the `variant` prop.

```tsx
<Avatar variant="default">
  <Avatar.Fallback>DF</Avatar.Fallback>
</Avatar>

```

### Colors

Apply different color variants to the avatar.

```tsx
<Avatar color="default">
  <Avatar.Fallback>DF</Avatar.Fallback>
</Avatar>

```

### Delayed Fallback

Show fallback after a delay to prevent flashing during image load.

```tsx
<Avatar>
  <Avatar.Image source={{ uri: imageUrl }} />
  <Avatar.Fallback delayMs={600}>NA</Avatar.Fallback>
</Avatar>

```

### Custom Image Component

Use a custom image component with the asChild prop.

```tsx
import { Image } from 'expo-image';

<Avatar>
  <Avatar.Image source={{ uri: imageUrl }} asChild>
    <Image style={{ width: '100%', height: '100%' }} contentFit="cover" />
  </Avatar.Image>
  <Avatar.Fallback>EI</Avatar.Fallback>
</Avatar>;

```

### Animation Control

Control animations at different levels of the Avatar component.

#### Disable All Animations

Disable all animations including children from the root component:

```tsx
<Avatar animation="disable-all">
  <Avatar.Image source={{ uri: imageUrl }} />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

```

#### Custom Image Animation

Customize the image opacity animation:

```tsx
<Avatar>
  <Avatar.Image
    source={{ uri: imageUrl }}
    animation={{
      opacity: {
        value: [0.3, 1],
        timingConfig: { duration: 300 },
      },
    }}
  />
  <Avatar.Fallback>JD</Avatar.Fallback>
</Avatar>

```

#### Custom Fallback Animation

Customize the fallback entering animation:

```tsx
import { FadeInDown } from 'react-native-reanimated';

<Avatar>
  <Avatar.Image source={{ uri: imageUrl }} />
  <Avatar.Fallback
    animation={{
      entering: {
        value: FadeInDown.duration(400),
      },
    }}
  >
    JD
  </Avatar.Fallback>
</Avatar>;

```

#### Disable Individual Animations

Disable animations for specific components:

```tsx
<Avatar>
  <Avatar.Image source={{ uri: imageUrl }} animation={false} />
  <Avatar.Fallback animation="disabled">JD</Avatar.Fallback>
</Avatar>

```

## Example

```tsx
import { Avatar } from 'heroui-native';
import { View } from 'react-native';

export default function AvatarExample() {
  const users = [
    { id: 1, image: 'https://example.com/user1.jpg', name: 'John Doe' },
    { id: 2, image: 'https://example.com/user2.jpg', name: 'Jane Smith' },
    { id: 3, image: 'https://example.com/user3.jpg', name: 'Bob Johnson' },
  ];

return (
    <View className="flex-row gap-4">
      {users.map((user) => (
        <Avatar key={user.id} size="lg" color="accent">
          <Avatar.Image source={{ uri: user.image }} />
          <Avatar.Fallback>
            {user.name
              .split(' ')
              .map((n) => n[0])
              .join('')}
          </Avatar.Fallback>
        </Avatar>
      ))}
    </View>
  );
}

```

## API Reference

### Avatar

| prop           | type                                                          | default     | description                                                                               |
| -------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children`     | `React.ReactNode`                                             | -           | Avatar content (Image and/or Fallback components)                                         |
| `size`         | `'sm' \| 'md' \| 'lg'`                                        | `'md'`      | Size of the avatar                                                                        |
| `variant`      | `'default' \| 'soft'`                                         | `'default'` | Visual variant of the avatar                                                              |
| `color`        | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'accent'`  | Color variant of the avatar                                                               |
| `className`    | `string`                                                      | -           | Additional CSS classes to apply                                                           |
| `animation`    | `"disable-all"` \| `undefined`                                | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
| `alt`          | `string`                                                      | -           | Alternative text description for accessibility                                            |
| `...ViewProps` | `ViewProps`                                                   | -           | All standard React Native View props are supported                                        |

### Avatar.Image

Props extend different base types depending on the `asChild` prop value:

* When `asChild={false}` (default): extends `AnimatedProps<ImageProps>` from React Native Reanimated
* When `asChild={true}`: extends primitive image props for custom image components

**Note:** When using `asChild={true}` with custom image components, the `className` prop may not be applied in some cases depending on the custom component's implementation. Ensure your custom component properly handles style props.

| prop               | type                                           | default | description                                      |
| ------------------ | ---------------------------------------------- | ------- | ------------------------------------------------ |
| `source`           | `ImageSourcePropType`                          | -       | Image source (required when `asChild={false}`)   |
| `asChild`          | `boolean`                                      | `false` | Whether to use a custom image component as child |
| `className`        | `string`                                       | -       | Additional CSS classes to apply                  |
| `animation`        | `AvatarImageAnimation`                         | -       | Animation configuration                          |
| `...AnimatedProps` | `AnimatedProps<ImageProps>` or primitive props | -       | Additional props based on `asChild` value        |

#### AvatarImageAnimation

Animation configuration for avatar image component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop                   | type               | default                                             | description                                           |
| ---------------------- | ------------------ | --------------------------------------------------- | ----------------------------------------------------- |
| `opacity.value`        | `[number, number]` | `[0, 1]`                                            | Opacity values \[initial, loaded] for image animation |
| `opacity.timingConfig` | `WithTimingConfig` | `{ duration: 200, easing: Easing.in(Easing.ease) }` | Animation timing configuration                        |

**Note:** Animation is automatically disabled when `asChild={true}`

### Avatar.Fallback

| prop                    | type                                                          | default               | description                                                                       |
| ----------------------- | ------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------- |
| `children`              | `React.ReactNode`                                             | -                     | Fallback content (text, icon, or custom element)                                  |
| `delayMs`               | `number`                                                      | `0`                   | Delay in milliseconds before showing the fallback (applied to entering animation) |
| `color`                 | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | inherited from parent | Color variant of the fallback                                                     |
| `className`             | `string`                                                      | -                     | Additional CSS classes for the container                                          |
| `classNames`            | `ElementSlots<AvatarFallbackSlots>`                           | -                     | Additional CSS classes for different parts                                        |
| `textProps`             | `TextProps`                                                   | -                     | Props to pass to Text component when children is a string                         |
| `iconProps`             | `PersonIconProps`                                             | -                     | Props to customize the default person icon                                        |
| `animation`             | `AvatarFallbackAnimation`                                     | -                     | Animation configuration                                                           |
| `...Animated.ViewProps` | `Animated.ViewProps`                                          | -                     | All Reanimated Animated.View props are supported                                  |

**classNames prop:** `ElementSlots<AvatarFallbackSlots>` provides type-safe CSS classes for different parts of the fallback component. Available slots: `container`, `text`.

#### AvatarFallbackAnimation

Animation configuration for avatar fallback component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop             | type                    | default                                                                                | description                            |
| ---------------- | ----------------------- | -------------------------------------------------------------------------------------- | -------------------------------------- |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br />`.duration(200)`<br />`.easing(Easing.in(Easing.ease))`<br />`.delay(0)` | Custom entering animation for fallback |

#### PersonIconProps

| prop    | type     | description                           |
| ------- | -------- | ------------------------------------- |
| `size`  | `number` | Size of the icon in pixels (optional) |
| `color` | `string` | Color of the icon (optional)          |

## Hooks

### useAvatar Hook

Hook to access Avatar primitive root context. Provides access to avatar status.

**Note:** The `status` property is particularly useful for adding a skeleton loader while the image is loading.

```tsx
import { Avatar, useAvatar, Skeleton } from 'heroui-native';

function AvatarWithSkeleton() {
  return (
    <Avatar>
      <Avatar.Image source={{ uri: imageUrl }} />
      <AvatarContent />
      <Avatar.Fallback>JD</Avatar.Fallback>
    </Avatar>
  );
}

function AvatarContent() {
  const { status } = useAvatar();

if (status === 'loading') {
    return <Skeleton className="absolute inset-0 rounded-full" />;
  }

return null;
}

```

| property    | type                                                 | description                                                 |
| ----------- | ---------------------------------------------------- | ----------------------------------------------------------- |
| `status`    | `'loading' \| 'loaded' \| 'error'`                   | Current loading state of the avatar image.                  |
| `setStatus` | `(status: 'loading' \| 'loaded' \| 'error') => void` | Function to manually set the avatar status (advanced usage) |

**Status Values:**

* `'loading'`: Image is currently being loaded. Use this state to show a skeleton loader.
* `'loaded'`: Image has successfully loaded.
* `'error'`: Image failed to load or source is invalid. The fallback component is automatically shown in this state.

</page>

<page url="/docs/native/components/accordion">
# Accordion

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/accordion
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(navigation)/accordion.mdx
> A collapsible content panel for organizing information in a compact space

## Import

```tsx
import { Accordion } from 'heroui-native';

```

## Anatomy

```tsx
<Accordion>
  <Accordion.Item>
    <Accordion.Trigger>
      ...
      <Accordion.Indicator>...</Accordion.Indicator>
    </Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
</Accordion>

```

* **Accordion**: Main container that manages the accordion state and behavior. Controls expansion/collapse of items, supports single or multiple selection modes, and provides variant styling (default or surface).
* **Accordion.Item**: Container for individual accordion items. Wraps the trigger and content, managing the expanded state for each item.
* **Accordion.Trigger**: Interactive element that toggles item expansion. Built on Header and Trigger primitives.
* **Accordion.Indicator**: Optional visual indicator showing expansion state. Defaults to an animated chevron icon that rotates based on item state.
* **Accordion.Content**: Container for expandable content. Animated with layout transitions for smooth expand/collapse effects.

## Usage

### Basic Usage

The Accordion component uses compound parts to create expandable content sections.

```tsx
<Accordion selectionMode="single">
  <Accordion.Item value="1">
    <Accordion.Trigger>
      ...
      <Accordion.Indicator />
    </Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
</Accordion>

```

### Single Selection Mode

Allow only one item to be expanded at a time.

```tsx
<Accordion selectionMode="single" defaultValue="2">
  <Accordion.Item value="1">
    <Accordion.Trigger>...</Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
  <Accordion.Item value="2">
    <Accordion.Trigger>...</Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
</Accordion>

```

### Multiple Selection Mode

Allow multiple items to be expanded simultaneously.

```tsx
<Accordion selectionMode="multiple" defaultValue={['1', '3']}>
  <Accordion.Item value="1">
    <Accordion.Trigger>...</Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
  <Accordion.Item value="2">
    <Accordion.Trigger>...</Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
  <Accordion.Item value="3">
    <Accordion.Trigger>...</Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
</Accordion>

```

### Surface Variant

Apply a surface container style to the accordion.

```tsx
<Accordion selectionMode="single" variant="surface">
  <Accordion.Item value="1">
    <Accordion.Trigger>
      ...
      <Accordion.Indicator />
    </Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
</Accordion>

```

### Custom Indicator

Replace the default chevron indicator with custom content.

```tsx
<Accordion selectionMode="single">
  <Accordion.Item value="1">
    <Accordion.Trigger>
      ...
      <Accordion.Indicator>
        <CustomIndicator />
      </Accordion.Indicator>
    </Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
</Accordion>

```

### Without Dividers

Hide the dividers between accordion items.

```tsx
<Accordion selectionMode="single" isDividerVisible={false}>
  <Accordion.Item value="1">
    <Accordion.Trigger>...</Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
  <Accordion.Item value="2">
    <Accordion.Trigger>...</Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
</Accordion>

```

### With PressableFeedback

Wrap `Accordion.Trigger` with `PressableFeedback` to add custom press feedback animations.

```tsx
import { Accordion, PressableFeedback } from 'heroui-native';

<Accordion selectionMode="single">
  <Accordion.Item value="1">
    <PressableFeedback
      feedbackVariant="highlight"
      animation={{
        highlight: {
          opacity: { value: [0, 0.05] },
        },
      }}
    >
      <Accordion.Trigger>
        <Text>Item Title</Text>
        <Accordion.Indicator />
      </Accordion.Trigger>
    </PressableFeedback>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
</Accordion>;

```

## Example

```tsx
import { Accordion, useThemeColor } from 'heroui-native';
import { Ionicons } from '@expo/vector-icons';
import { View, Text } from 'react-native';

export default function AccordionExample() {
  const themeColorMuted = useThemeColor('muted');

const accordionData = [
    {
      id: '1',
      title: 'How do I place an order?',
      icon: <Ionicons name="bag-outline" size={16} color={themeColorMuted} />,
      content:
        'Lorem ipsum dolor sit amet consectetur. Netus nunc mauris risus consequat. Libero placerat dignissim consectetur nisl.',
    },
    {
      id: '2',
      title: 'What payment methods do you accept?',
      icon: <Ionicons name="card-outline" size={16} color={themeColorMuted} />,
      content:
        'Lorem ipsum dolor sit amet consectetur. Netus nunc mauris risus consequat. Libero placerat dignissim consectetur nisl.',
    },
    {
      id: '3',
      title: 'How much does shipping cost?',
      icon: <Ionicons name="cube-outline" size={16} color={themeColorMuted} />,
      content:
        'Lorem ipsum dolor sit amet consectetur. Netus nunc mauris risus consequat. Libero placerat dignissim consectetur nisl.',
    },
  ];

return (
    <Accordion selectionMode="single" variant="surface" defaultValue="2">
      {accordionData.map((item) => (
        <Accordion.Item key={item.id} value={item.id}>
          <Accordion.Trigger>
            <View className="flex-row items-center flex-1 gap-3">
              {item.icon}
              <Text className="text-foreground text-base flex-1">
                {item.title}
              </Text>
            </View>
            <Accordion.Indicator />
          </Accordion.Trigger>
          <Accordion.Content>
            <Text className="text-muted text-base/relaxed px-[25px]">
              {item.content}
            </Text>
          </Accordion.Content>
        </Accordion.Item>
      ))}
    </Accordion>
  );
}

```

## API Reference

### Accordion

| prop                    | type                                               | default     | description                                                       |
| ----------------------- | -------------------------------------------------- | ----------- | ----------------------------------------------------------------- |
| `children`              | `React.ReactNode`                                  | -           | Children elements to be rendered inside the accordion             |
| `selectionMode`         | `'single' \| 'multiple'`                           | -           | Whether the accordion allows single or multiple expanded items    |
| `variant`               | `'default' \| 'surface'`                           | `'default'` | Visual variant of the accordion                                   |
| `isDividerVisible`      | `boolean`                                          | `true`      | Whether to display a divider at the bottom of each accordion item |
| `defaultValue`          | `string \| string[] \| undefined`                  | -           | Default expanded item(s) in uncontrolled mode                     |
| `value`                 | `string \| string[] \| undefined`                  | -           | Controlled expanded item(s)                                       |
| `isDisabled`            | `boolean`                                          | -           | Whether all accordion items are disabled                          |
| `isCollapsible`         | `boolean`                                          | `true`      | Whether expanded items can be collapsed                           |
| `animation`             | `AccordionRootAnimation`                           | -           | Animation configuration for accordion                             |
| `className`             | `string`                                           | -           | Additional CSS classes for the container                          |
| `classNames`            | `ElementSlots<RootSlots>`                          | -           | Additional CSS classes for the slots                              |
| `onValueChange`         | `(value: string \| string[] \| undefined) => void` | -           | Callback when expanded items change                               |
| `...Animated.ViewProps` | `Animated.ViewProps`                               | -           | All Reanimated Animated.View props are supported                  |

#### `ElementSlots<RootSlots>`

| prop        | type     | description                                     |
| ----------- | -------- | ----------------------------------------------- |
| `container` | `string` | Custom class name for the accordion container   |
| `divider`   | `string` | Custom class name for the divider between items |

#### AccordionRootAnimation

Animation configuration for accordion root component. Can be:

| prop           | type               | default                                                                                             | description                                       |
| -------------- | ------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `layout.value` | `LayoutTransition` | `LinearTransition`<br />`.springify()`<br />`.damping(140)`<br />`.stiffness(1600)`<br />`.mass(4)` | Custom layout animation for accordion transitions |

### Accordion.Item

| prop                    | type                                                                        | default | description                                                                      |
| ----------------------- | --------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------- |
| `children`              | `React.ReactNode \| ((props: AccordionItemRenderProps) => React.ReactNode)` | -       | Children elements to be rendered inside the accordion item, or a render function |
| `value`                 | `string`                                                                    | -       | Unique value to identify this item                                               |
| `isDisabled`            | `boolean`                                                                   | -       | Whether this specific item is disabled                                           |
| `className`             | `string`                                                                    | -       | Additional CSS classes                                                           |
| `...Animated.ViewProps` | `Animated.ViewProps`                                                        | -       | All Reanimated Animated.View props are supported                                 |

#### AccordionItemRenderProps

| prop         | type      | description                                      |
| ------------ | --------- | ------------------------------------------------ |
| `isExpanded` | `boolean` | Whether the accordion item is currently expanded |
| `value`      | `string`  | Unique value identifier for this accordion item  |

### Accordion.Trigger

| prop                | type              | default | description                                             |
| ------------------- | ----------------- | ------- | ------------------------------------------------------- |
| `children`          | `React.ReactNode` | -       | Children elements to be rendered inside the trigger     |
| `className`         | `string`          | -       | Additional CSS classes                                  |
| `isDisabled`        | `boolean`         | -       | Whether the trigger is disabled                         |
| `...PressableProps` | `PressableProps`  | -       | All standard React Native Pressable props are supported |

### Accordion.Indicator

| prop                    | type                          | default | description                                                            |
| ----------------------- | ----------------------------- | ------- | ---------------------------------------------------------------------- |
| `children`              | `React.ReactNode`             | -       | Custom indicator content, if not provided defaults to animated chevron |
| `className`             | `string`                      | -       | Additional CSS classes                                                 |
| `iconProps`             | `AccordionIndicatorIconProps` | -       | Icon configuration                                                     |
| `animation`             | `AccordionIndicatorAnimation` | -       | Animation configuration for indicator                                  |
| `...Animated.ViewProps` | `Animated.ViewProps`          | -       | All Reanimated Animated.View props are supported                       |

#### AccordionIndicatorIconProps

| prop    | type     | default      | description       |
| ------- | -------- | ------------ | ----------------- |
| `size`  | `number` | `16`         | Size of the icon  |
| `color` | `string` | `foreground` | Color of the icon |

#### AccordionIndicatorAnimation

Animation configuration for accordion indicator component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop                    | type               | default                                      | description                                       |
| ----------------------- | ------------------ | -------------------------------------------- | ------------------------------------------------- |
| `rotation.value`        | `[number, number]` | `[0, -180]`                                  | Rotation values \[collapsed, expanded] in degrees |
| `rotation.springConfig` | `WithSpringConfig` | `{ damping: 140, stiffness: 1000, mass: 4 }` | Spring animation configuration for rotation       |

### Accordion.Content

| prop           | type                        | default | description                                         |
| -------------- | --------------------------- | ------- | --------------------------------------------------- |
| `children`     | `React.ReactNode`           | -       | Children elements to be rendered inside the content |
| `className`    | `string`                    | -       | Additional CSS classes                              |
| `animation`    | `AccordionContentAnimation` | -       | Animation configuration for content                 |
| `...ViewProps` | `ViewProps`                 | -       | All standard React Native View props are supported  |

#### AccordionContentAnimation

Animation configuration for accordion content component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop             | type                    | default                                                                | description                           |
| ---------------- | ----------------------- | ---------------------------------------------------------------------- | ------------------------------------- |
| `entering.value` | `EntryOrExitLayoutType` | `FadeIn`<br />`.duration(200)`<br />`.easing(Easing.out(Easing.ease))` | Custom entering animation for content |
| `exiting.value`  | `EntryOrExitLayoutType` | `FadeOut`<br />`.duration(200)`<br />`.easing(Easing.in(Easing.ease))` | Custom exiting animation for content  |

## Hooks

### useAccordion

Hook to access the accordion root context. Must be used within an `Accordion` component.

```tsx
import { useAccordion } from 'heroui-native';

const { value, onValueChange, selectionMode, isCollapsible, isDisabled } =
  useAccordion();

```

#### Returns

| property        | type                                                                  | description                                                                  |
| --------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| `selectionMode` | `'single' \| 'multiple' \| undefined`                                 | Whether the accordion allows single or multiple expanded items               |
| `value`         | `(string \| undefined) \| string[]`                                   | Currently expanded item(s) - string for single mode, array for multiple mode |
| `onValueChange` | `(value: string \| undefined) => void \| ((value: string[]) => void)` | Callback function to update expanded items                                   |
| `isCollapsible` | `boolean`                                                             | Whether expanded items can be collapsed                                      |
| `isDisabled`    | `boolean \| undefined`                                                | Whether all accordion items are disabled                                     |

### useAccordionItem

Hook to access the accordion item context. Must be used within an `Accordion.Item` component.

```tsx
import { useAccordionItem } from 'heroui-native';

const { value, isExpanded, isDisabled, nativeID } = useAccordionItem();

```

#### Returns

| property     | type                   | description                                          |
| ------------ | ---------------------- | ---------------------------------------------------- |
| `value`      | `string`               | Unique value identifier for this accordion item      |
| `isExpanded` | `boolean`              | Whether the accordion item is currently expanded     |
| `isDisabled` | `boolean \| undefined` | Whether this specific item is disabled               |
| `nativeID`   | `string`               | Native ID used for accessibility and ARIA attributes |

## Special Notes

When using the Accordion component alongside other components in the same view, you should import and apply `AccordionLayoutTransition` to those components to ensure smooth and consistent layout animations across the entire screen.

```jsx
import { Accordion, AccordionLayoutTransition } from 'heroui-native';
import Animated from 'react-native-reanimated';

<Animated.ScrollView layout={AccordionLayoutTransition}>
  <Animated.View layout={AccordionLayoutTransition}>
    {/* Other content */}
  </Animated.View>

<Accordion>{/* Accordion items */}</Accordion>
</Animated.ScrollView>;

```

This ensures that when the accordion expands or collapses, all components on the screen animate with the same timing and easing, creating a cohesive user experience.

</page>

<page url="/docs/native/components/tabs">
# Tabs

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/tabs
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(navigation)/tabs.mdx
> Organize content into tabbed views with animated transitions and indicators.

## Import

```tsx
import { Tabs } from 'heroui-native';

```

## Anatomy

```tsx
<Tabs>
  <Tabs.List>
    <Tabs.ScrollView>
      <Tabs.Indicator />
      <Tabs.Trigger>
        <Tabs.Label>...</Tabs.Label>
      </Tabs.Trigger>
    </Tabs.ScrollView>
  </Tabs.List>
  <Tabs.Content>...</Tabs.Content>
</Tabs>

```

* **Tabs**: Main container that manages tab state and selection. Controls active tab, handles value changes, and provides context to child components.
* **Tabs.List**: Container for tab triggers. Groups triggers together with optional styling variants (pill or line).
* **Tabs.ScrollView**: Optional scrollable wrapper for tab triggers. Enables horizontal scrolling when tabs overflow with automatic centering of active tab.
* **Tabs.Trigger**: Interactive button for each tab. Handles press events to change active tab and measures its position for indicator animation.
* **Tabs.Label**: Text content for tab triggers. Displays the tab title with appropriate styling.
* **Tabs.Indicator**: Animated visual indicator for active tab. Smoothly transitions between tabs using spring or timing animations.
* **Tabs.Content**: Container for tab panel content. Shows content when its value matches the active tab.

## Usage

### Basic Usage

The Tabs component uses compound parts to create navigable content sections.

```tsx
<Tabs value="tab1" onValueChange={setActiveTab}>
  <Tabs.List>
    <Tabs.Indicator />
    <Tabs.Trigger value="tab1">
      <Tabs.Label>Tab 1</Tabs.Label>
    </Tabs.Trigger>
    <Tabs.Trigger value="tab2">
      <Tabs.Label>Tab 2</Tabs.Label>
    </Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="tab1">...</Tabs.Content>
  <Tabs.Content value="tab2">...</Tabs.Content>
</Tabs>

```

### Pill Variant

Default rounded pill style for tab triggers.

```tsx
<Tabs value={activeTab} onValueChange={setActiveTab} variant="pill">
  <Tabs.List>
    <Tabs.Indicator />
    <Tabs.Trigger value="settings">
      <Tabs.Label>Settings</Tabs.Label>
    </Tabs.Trigger>
    <Tabs.Trigger value="profile">
      <Tabs.Label>Profile</Tabs.Label>
    </Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="settings">...</Tabs.Content>
  <Tabs.Content value="profile">...</Tabs.Content>
</Tabs>

```

### Line Variant

Underline style indicator for a more minimal appearance.

```tsx
<Tabs value={activeTab} onValueChange={setActiveTab} variant="line">
  <Tabs.List>
    <Tabs.Indicator />
    <Tabs.Trigger value="overview">
      <Tabs.Label>Overview</Tabs.Label>
    </Tabs.Trigger>
    <Tabs.Trigger value="analytics">
      <Tabs.Label>Analytics</Tabs.Label>
    </Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="overview">...</Tabs.Content>
  <Tabs.Content value="analytics">...</Tabs.Content>
</Tabs>

```

### Scrollable Tabs

Handle many tabs with horizontal scrolling.

```tsx
<Tabs value={activeTab} onValueChange={setActiveTab}>
  <Tabs.List>
    <Tabs.ScrollView scrollAlign="center">
      <Tabs.Indicator />
      <Tabs.Trigger value="tab1">
        <Tabs.Label>First Tab</Tabs.Label>
      </Tabs.Trigger>
      <Tabs.Trigger value="tab2">
        <Tabs.Label>Second Tab</Tabs.Label>
      </Tabs.Trigger>
      <Tabs.Trigger value="tab3">
        <Tabs.Label>Third Tab</Tabs.Label>
      </Tabs.Trigger>
      <Tabs.Trigger value="tab4">
        <Tabs.Label>Fourth Tab</Tabs.Label>
      </Tabs.Trigger>
      <Tabs.Trigger value="tab5">
        <Tabs.Label>Fifth Tab</Tabs.Label>
      </Tabs.Trigger>
    </Tabs.ScrollView>
  </Tabs.List>
  <Tabs.Content value="tab1">...</Tabs.Content>
  <Tabs.Content value="tab2">...</Tabs.Content>
  <Tabs.Content value="tab3">...</Tabs.Content>
  <Tabs.Content value="tab4">...</Tabs.Content>
  <Tabs.Content value="tab5">...</Tabs.Content>
</Tabs>

```

### Disabled Tabs

Disable specific tabs to prevent interaction.

```tsx
<Tabs value={activeTab} onValueChange={setActiveTab}>
  <Tabs.List>
    <Tabs.Indicator />
    <Tabs.Trigger value="active">
      <Tabs.Label>Active</Tabs.Label>
    </Tabs.Trigger>
    <Tabs.Trigger value="disabled" isDisabled>
      <Tabs.Label>Disabled</Tabs.Label>
    </Tabs.Trigger>
    <Tabs.Trigger value="another">
      <Tabs.Label>Another</Tabs.Label>
    </Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="active">...</Tabs.Content>
  <Tabs.Content value="another">...</Tabs.Content>
</Tabs>

```

### With Icons

Combine icons with labels for enhanced visual context.

```tsx
<Tabs value={activeTab} onValueChange={setActiveTab}>
  <Tabs.List>
    <Tabs.Indicator />
    <Tabs.Trigger value="home">
      <Icon name="home" size={16} />
      <Tabs.Label>Home</Tabs.Label>
    </Tabs.Trigger>
    <Tabs.Trigger value="search">
      <Icon name="search" size={16} />
      <Tabs.Label>Search</Tabs.Label>
    </Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="home">...</Tabs.Content>
  <Tabs.Content value="search">...</Tabs.Content>
</Tabs>

```

### With Render Function

Use a render function on `Tabs.Trigger` to access state and customize content based on selection.

```tsx
<Tabs value={activeTab} onValueChange={setActiveTab}>
  <Tabs.List>
    <Tabs.Indicator />
    <Tabs.Trigger value="settings">
      {({ isSelected, value, isDisabled }) => (
        <Tabs.Label
          className={isSelected ? 'text-accent font-medium' : 'text-foreground'}
        >
          Settings
        </Tabs.Label>
      )}
    </Tabs.Trigger>
    <Tabs.Trigger value="profile">
      {({ isSelected }) => (
        <>
          <Icon name="user" size={16} />
          <Tabs.Label className={isSelected ? 'text-accent' : 'text-muted'}>
            Profile
          </Tabs.Label>
        </>
      )}
    </Tabs.Trigger>
  </Tabs.List>
  <Tabs.Content value="settings">...</Tabs.Content>
  <Tabs.Content value="profile">...</Tabs.Content>
</Tabs>

```

## Example

```tsx
import { Tabs, TextField, FormField, Checkbox, Button } from 'heroui-native';
import { useState } from 'react';
import { View, Text } from 'react-native';
import Animated, {
  FadeIn,
  FadeOut,
  LinearTransition,
} from 'react-native-reanimated';

const AnimatedContentContainer = ({
  children,
}: {
  children: React.ReactNode;
}) => (
  <Animated.View
    entering={FadeIn.duration(200)}
    exiting={FadeOut.duration(200)}
    className="gap-6"
  >
    {children}
  </Animated.View>
);

export default function TabsExample() {
  const [activeTab, setActiveTab] = useState('general');

const [showSidebar, setShowSidebar] = useState(true);
  const [accountActivity, setAccountActivity] = useState(true);
  const [name, setName] = useState('');

return (
    <Tabs value={activeTab} onValueChange={setActiveTab} variant="pill">
      <Tabs.List>
        <Tabs.ScrollView>
          <Tabs.Indicator />
          <Tabs.Trigger value="general">
            <Tabs.Label>General</Tabs.Label>
          </Tabs.Trigger>
          <Tabs.Trigger value="notifications">
            <Tabs.Label>Notifications</Tabs.Label>
          </Tabs.Trigger>
          <Tabs.Trigger value="profile">
            <Tabs.Label>Profile</Tabs.Label>
          </Tabs.Trigger>
        </Tabs.ScrollView>
      </Tabs.List>

<Animated.View
        layout={LinearTransition.duration(200)}
        className="px-4 py-6 border border-border rounded-xl"
      >
        <Tabs.Content value="general">
          <AnimatedContentContainer>
            <FormField
              isSelected={showSidebar}
              onSelectedChange={setShowSidebar}
            >
              <FormField.Indicator variant="checkbox" />
              <View className="flex-1">
                <FormField.Label>Show sidebar</FormField.Label>
                <FormField.Description>
                  Display the sidebar navigation panel
                </FormField.Description>
              </View>
            </FormField>
          </AnimatedContentContainer>
        </Tabs.Content>

<Tabs.Content value="notifications">
          <AnimatedContentContainer>
            <FormField
              isSelected={accountActivity}
              onSelectedChange={setAccountActivity}
            >
              <FormField.Indicator variant="checkbox" />
              <View className="flex-1">
                <FormField.Label>Account activity</FormField.Label>
                <FormField.Description>
                  Notifications about your account activity
                </FormField.Description>
              </View>
            </FormField>
          </AnimatedContentContainer>
        </Tabs.Content>

<Tabs.Content value="profile">
          <AnimatedContentContainer>
            <TextField isRequired>
              <TextField.Label>Name</TextField.Label>
              <TextField.Input
                value={name}
                onChangeText={setName}
                placeholder="Enter your full name"
              />
            </TextField>
            <Button size="sm" className="self-start">
              <Button.Label>Update profile</Button.Label>
            </Button>
          </AnimatedContentContainer>
        </Tabs.Content>
      </Animated.View>
    </Tabs>
  );
}

```

## API Reference

### Tabs

| prop            | type                         | default     | description                                                                               |
| --------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children`      | `React.ReactNode`            | -           | Children elements to be rendered inside tabs                                              |
| `value`         | `string`                     | -           | Currently active tab value                                                                |
| `variant`       | `'pill' \| 'line'`           | `'pill'`    | Visual variant of the tabs                                                                |
| `className`     | `string`                     | -           | Additional CSS classes for the container                                                  |
| `animation`     | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children |
| `onValueChange` | `(value: string) => void`    | -           | Callback when the active tab changes                                                      |
| `...ViewProps`  | `ViewProps`                  | -           | All standard React Native View props are supported                                        |

### Tabs.List

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the list   |
| `className`    | `string`          | -       | Additional CSS classes                             |
| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported |

### Tabs.ScrollView

| prop                        | type                                     | default    | description                                              |
| --------------------------- | ---------------------------------------- | ---------- | -------------------------------------------------------- |
| `children`                  | `React.ReactNode`                        | -          | Children elements to be rendered inside the scroll view  |
| `scrollAlign`               | `'start' \| 'center' \| 'end' \| 'none'` | `'center'` | Scroll alignment variant for the selected item           |
| `className`                 | `string`                                 | -          | Additional CSS classes for the scroll view               |
| `contentContainerClassName` | `string`                                 | -          | Additional CSS classes for the content container         |
| `...ScrollViewProps`        | `ScrollViewProps`                        | -          | All standard React Native ScrollView props are supported |

### Tabs.Trigger

| prop                | type                                                                      | default | description                                                               |
| ------------------- | ------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------- |
| `children`          | `React.ReactNode \| ((props: TabsTriggerRenderProps) => React.ReactNode)` | -       | Children elements to be rendered inside the trigger, or a render function |
| `value`             | `string`                                                                  | -       | The unique value identifying this tab                                     |
| `isDisabled`        | `boolean`                                                                 | `false` | Whether the trigger is disabled                                           |
| `className`         | `string`                                                                  | -       | Additional CSS classes                                                    |
| `...PressableProps` | `PressableProps`                                                          | -       | All standard React Native Pressable props are supported                   |

#### TabsTriggerRenderProps

When using a render function for `children`, the following props are provided:

| property     | type      | description                                |
| ------------ | --------- | ------------------------------------------ |
| `isSelected` | `boolean` | Whether this trigger is currently selected |
| `value`      | `string`  | The value of the trigger                   |
| `isDisabled` | `boolean` | Whether the trigger is disabled            |

### Tabs.Label

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Text content to be rendered as label               |
| `className`    | `string`          | -       | Additional CSS classes                             |
| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |

### Tabs.Indicator

| prop                    | type                     | default | description                                      |
| ----------------------- | ------------------------ | ------- | ------------------------------------------------ |
| `children`              | `React.ReactNode`        | -       | Custom indicator content                         |
| `className`             | `string`                 | -       | Additional CSS classes                           |
| `animation`             | `TabsIndicatorAnimation` | -       | Animation configuration                          |
| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | All Reanimated Animated.View props are supported |

#### TabsIndicatorAnimation

Animation configuration for Tabs.Indicator component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop            | type                                   | default                                                                      | description                        |
| --------------- | -------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------- |
| `width.type`    | `'spring' \| 'timing'`                 | `'spring'`                                                                   | Type of animation to use           |
| `width.config`  | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration |
| `height.type`   | `'spring' \| 'timing'`                 | `'spring'`                                                                   | Type of animation to use           |
| `height.config` | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration |
| `left.type`     | `'spring' \| 'timing'`                 | `'spring'`                                                                   | Type of animation to use           |
| `left.config`   | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration |

### Tabs.Content

| prop           | type              | default | description                                         |
| -------------- | ----------------- | ------- | --------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Children elements to be rendered inside the content |
| `value`        | `string`          | -       | The value of the tab this content belongs to        |
| `className`    | `string`          | -       | Additional CSS classes                              |
| `...ViewProps` | `ViewProps`       | -       | All standard React Native View props are supported  |

## Hooks

### useTabs

Hook to access tabs root context values within custom components or compound components.

```tsx
import { useTabs } from 'heroui-native';

const CustomComponent = () => {
  const { value, onValueChange, nativeID } = useTabs();
  // ... your implementation
};

```

**Returns:** `UseTabsReturn`

| property        | type                      | description                                |
| --------------- | ------------------------- | ------------------------------------------ |
| `value`         | `string`                  | Currently active tab value                 |
| `onValueChange` | `(value: string) => void` | Callback function to change the active tab |
| `nativeID`      | `string`                  | Unique identifier for the tabs instance    |

**Note:** This hook must be used within a `Tabs` component. It will throw an error if called outside of the tabs context.

### useTabsMeasurements

Hook to access tab measurements context values for managing tab trigger positions and dimensions.

```tsx
import { useTabsMeasurements } from 'heroui-native';

const CustomIndicator = () => {
  const { measurements, variant } = useTabsMeasurements();
  // ... your implementation
};

```

**Returns:** `UseTabsMeasurementsReturn`

| property          | type                                                    | description                                       |
| ----------------- | ------------------------------------------------------- | ------------------------------------------------- |
| `measurements`    | `Record<string, ItemMeasurements>`                      | Record of measurements for each tab trigger       |
| `setMeasurements` | `(key: string, measurements: ItemMeasurements) => void` | Function to update measurements for a tab trigger |
| `variant`         | `'pill' \| 'line'`                                      | Visual variant of the tabs                        |

#### ItemMeasurements

| property | type     | description                         |
| -------- | -------- | ----------------------------------- |
| `width`  | `number` | Width of the tab trigger in pixels  |
| `height` | `number` | Height of the tab trigger in pixels |
| `x`      | `number` | X position of the tab trigger       |

**Note:** This hook must be used within a `Tabs` component. It will throw an error if called outside of the tabs context.

### useTabsTrigger

Hook to access tab trigger context values within custom components or compound components.

```tsx
import { useTabsTrigger } from 'heroui-native';

const CustomLabel = () => {
  const { value, isSelected, nativeID } = useTabsTrigger();
  // ... your implementation
};

```

**Returns:** `UseTabsTriggerReturn`

| property     | type      | description                                |
| ------------ | --------- | ------------------------------------------ |
| `value`      | `string`  | The value of this trigger                  |
| `nativeID`   | `string`  | Unique identifier for this trigger         |
| `isSelected` | `boolean` | Whether this trigger is currently selected |

**Note:** This hook must be used within a `Tabs.Trigger` component. It will throw an error if called outside of the trigger context.

</page>

<page url="/docs/native/components/dialog">
# Dialog

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/dialog
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(overlays)/dialog.mdx
> Displays a modal overlay with animated transitions and gesture-based dismissal.

## Import

```tsx
import { Dialog, useDialog, useDialogAnimation } from 'heroui-native';

```

## Anatomy

```tsx
<Dialog>
  <Dialog.Trigger>...</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay>...</Dialog.Overlay>
    <Dialog.Content>
      <Dialog.Close>...</Dialog.Close>
      <Dialog.Title>...</Dialog.Title>
      <Dialog.Description>...</Dialog.Description>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog>

```

* **Dialog**: Root component that manages open state and provides context to child components.
* **Dialog.Trigger**: Pressable element that opens the dialog when pressed.
* **Dialog.Portal**: Renders dialog content in a portal with centered layout and animation control.
* **Dialog.Overlay**: Background overlay that appears behind the dialog content, typically closes dialog when pressed.
* **Dialog.Content**: Main dialog container with gesture support for drag-to-dismiss.
* **Dialog.Close**: Close button that dismisses the dialog when pressed.
* **Dialog.Title**: Dialog title text with semantic heading role.
* **Dialog.Description**: Dialog description text that provides additional context.

## Usage

### Basic Dialog

Simple dialog with title, description, and close button.

```tsx
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
  <Dialog.Trigger asChild>
    <Button>Open Dialog</Button>
  </Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Close />
      <Dialog.Title>...</Dialog.Title>
      <Dialog.Description>...</Dialog.Description>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog>

```

### Custom Animations

Configure open and close animations with spring or timing. The `closeDelay` should typically match your closing animation duration.

```tsx
<Dialog
  isOpen={isOpen}
  onOpenChange={setIsOpen}
  closeDelay={200} // Match this with closing animation duration
  animation={{
    entering: {
      type: 'spring',
      config: { damping: 130, stiffness: 1100 },
    },
    exiting: {
      type: 'timing',
      config: { duration: 200 }, // Should match closeDelay
    },
  }}
>
  <Dialog.Trigger>...</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>...</Dialog.Content>
  </Dialog.Portal>
</Dialog>

```

### Custom Backdrop

Replace the default overlay with custom content.

```tsx
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
  <Dialog.Trigger>...</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay className="bg-transparent">
      <BlurView style={StyleSheet.absoluteFill} />
    </Dialog.Overlay>
    <Dialog.Content>...</Dialog.Content>
  </Dialog.Portal>
</Dialog>

```

### Scrollable Content

Handle long content with scroll views.

```tsx
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
  <Dialog.Trigger>...</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <Dialog.Content>
      <Dialog.Close />
      <Dialog.Title>...</Dialog.Title>
      <View className="h-[300px]">
        <ScrollView>...</ScrollView>
      </View>
    </Dialog.Content>
  </Dialog.Portal>
</Dialog>

```

### Form Dialog

Dialog with text inputs and keyboard handling.

```tsx
<Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
  <Dialog.Trigger>...</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Overlay />
    <KeyboardAvoidingView behavior="padding">
      <Dialog.Content>
        <Dialog.Close />
        <Dialog.Title>...</Dialog.Title>
        <TextField>...</TextField>
        <Button onPress={handleSubmit}>Submit</Button>
      </Dialog.Content>
    </KeyboardAvoidingView>
  </Dialog.Portal>
</Dialog>

```

## Example

```tsx
import { Button, Dialog } from 'heroui-native';
import { View } from 'react-native';
import { useState } from 'react';

export default function DialogExample() {
  const [isOpen, setIsOpen] = useState(false);

return (
    <Dialog isOpen={isOpen} onOpenChange={setIsOpen}>
      <Dialog.Trigger asChild>
        <Button variant="primary">Open Dialog</Button>
      </Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Overlay />
        <Dialog.Content>
          <Dialog.Close />
          <View className="mb-5 gap-1.5">
            <Dialog.Title>Confirm Action</Dialog.Title>
            <Dialog.Description>
              Are you sure you want to proceed with this action? This cannot be
              undone.
            </Dialog.Description>
          </View>
          <View className="flex-row justify-end gap-3">
            <Dialog.Close asChild>
              <Button variant="ghost" size="sm">
                Cancel
              </Button>
            </Dialog.Close>
            <Button size="sm">Confirm</Button>
          </View>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog>
  );
}

```

## API Reference

### Dialog

| prop                       | type                       | default | description                                                                          |
| -------------------------- | -------------------------- | ------- | ------------------------------------------------------------------------------------ |
| `children`                 | `React.ReactNode`          | -       | Dialog content and trigger elements                                                  |
| `isOpen`                   | `boolean`                  | -       | Controlled open state of the dialog                                                  |
| `isDefaultOpen`            | `boolean`                  | `false` | Initial open state when uncontrolled                                                 |
| `closeDelay`               | `number`                   | `300`   | Delay in milliseconds before dialog closes (should match closing animation duration) |
| `isDismissKeyboardOnClose` | `boolean`                  | `true`  | Whether to dismiss keyboard when dialog closes                                       |
| `animation`                | `DialogRootAnimation`      | -       | Animation configuration                                                              |
| `onOpenChange`             | `(value: boolean) => void` | -       | Callback when open state changes                                                     |
| `...ViewProps`             | `ViewProps`                | -       | All standard React Native View props are supported                                   |

#### DialogRootAnimation

Animation configuration for dialog root component. Can be:

| prop             | type                                             | default                                                                                            | description                         |
| ---------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------- |
| `entering.value` | `SpringAnimationConfig \| TimingAnimationConfig` | `{ type: 'timing',`<br />`config: { duration: 200,`<br />`easing: Easing.out(Easing.ease) } }`     | Animation configuration for opening |
| `exiting.value`  | `SpringAnimationConfig \| TimingAnimationConfig` | `{ type: 'timing',`<br />`config: { duration: 150,`<br />`easing: Easing.bezier(0.4, 0, 1, 1) } }` | Animation configuration for closing |

#### SpringAnimationConfig

#### TimingAnimationConfig

### Dialog.Trigger

| prop                | type              | default | description                                                  |
| ------------------- | ----------------- | ------- | ------------------------------------------------------------ |
| `children`          | `React.ReactNode` | -       | Trigger element content                                      |
| `asChild`           | `boolean`         | -       | Render as child element without wrapper                      |
| `...PressableProps` | `PressableProps`  | -       | All standard React Native PressableProps props are supported |

### Dialog.Portal

| prop         | type                   | default | description                                      |
| ------------ | ---------------------- | ------- | ------------------------------------------------ |
| `children`   | `React.ReactNode`      | -       | Portal content (overlay and dialog)              |
| `className`  | `string`               | -       | Additional CSS classes for portal container      |
| `style`      | `StyleProp<ViewStyle>` | -       | Additional styles for portal container           |
| `hostName`   | `string`               | -       | Optional portal host name for specific container |
| `forceMount` | `boolean`              | -       | Force mount when closed for animation purposes   |

### Dialog.Overlay

| prop                | type                     | default | description                                             |
| ------------------- | ------------------------ | ------- | ------------------------------------------------------- |
| `children`          | `React.ReactNode`        | -       | Custom overlay content                                  |
| `className`         | `string`                 | -       | Additional CSS classes for overlay                      |
| `style`             | `ViewStyle`              | -       | Additional styles for overlay container                 |
| `animation`         | `DialogOverlayAnimation` | -       | Animation configuration                                 |
| `isCloseOnPress`    | `boolean`                | `true`  | Whether pressing overlay closes dialog                  |
| `forceMount`        | `boolean`                | -       | Force mount when closed for animation purposes          |
| `...PressableProps` | `PressableProps`         | -       | All standard React Native Pressable props are supported |

#### DialogOverlayAnimation

Animation configuration for dialog overlay component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

### Dialog.Content

| prop                    | type                                 | default | description                                         |
| ----------------------- | ------------------------------------ | ------- | --------------------------------------------------- |
| `children`              | `React.ReactNode`                    | -       | Dialog content                                      |
| `className`             | `string`                             | -       | Additional CSS classes for content container        |
| `style`                 | `StyleProp<ViewStyle>`               | -       | Additional styles for content container             |
| `onLayout`              | `(event: LayoutChangeEvent) => void` | -       | Layout event handler                                |
| `animation`             | `DialogContentAnimation`             | -       | Animation configuration                             |
| `isSwipeable`           | `boolean`                            | `true`  | Whether the dialog content can be swiped to dismiss |
| `forceMount`            | `boolean`                            | -       | Force mount when closed for animation purposes      |
| `...Animated.ViewProps` | `Animated.ViewProps`                 | -       | All Reanimated Animated.View props are supported    |

#### DialogContentAnimation

Animation configuration for dialog content component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

### Dialog.Close

| prop                       | type                    | default | description                                                    |
| -------------------------- | ----------------------- | ------- | -------------------------------------------------------------- |
| `children`                 | `React.ReactNode`       | -       | Custom close button content                                    |
| `className`                | `string`                | -       | Additional CSS classes for close button                        |
| `iconProps`                | `DialogCloseIconProps`  | -       | Configuration for default close icon                           |
| `hitSlop`                  | `number`                | `12`    | Hit slop area for the close button                             |
| `asChild`                  | `boolean`               | -       | Render as child element without wrapper                        |
| `...TouchableOpacityProps` | `TouchableOpacityProps` | -       | All standard React Native TouchableOpacity props are supported |

#### DialogCloseIconProps

| prop    | type     | description                             |
| ------- | -------- | --------------------------------------- |
| `size`  | `number` | Icon size (default: 18)                 |
| `color` | `string` | Icon color (default: theme color muted) |

### Dialog.Title

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Title content                                      |
| `className`    | `string`          | -       | Additional CSS classes for title                   |
| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |

### Dialog.Description

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Description content                                |
| `className`    | `string`          | -       | Additional CSS classes for description             |
| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |

## Hooks

### useDialog

Hook to access dialog primitive context.

```tsx
const { isOpen, onOpenChange } = useDialog();

```

| property       | type                       | description                   |
| -------------- | -------------------------- | ----------------------------- |
| `isOpen`       | `boolean`                  | Current open state            |
| `onOpenChange` | `(value: boolean) => void` | Function to change open state |

### useDialogAnimation

Hook to access dialog animation context for advanced customization.

```tsx
const { dialogState, progress, isDragging, isGestureReleaseAnimationRunning } =
  useDialogAnimation();

```

| property                           | type                          | description                                  |
| ---------------------------------- | ----------------------------- | -------------------------------------------- |
| `dialogState`                      | `'idle' \| 'open' \| 'close'` | Internal dialog state                        |
| `progress`                         | `SharedValue<number>`         | Animation progress (0=idle, 1=open, 2=close) |
| `isDragging`                       | `SharedValue<boolean>`        | Whether dialog is being dragged              |
| `isGestureReleaseAnimationRunning` | `SharedValue<boolean>`        | Whether gesture release animation is running |

</page>

<page url="/docs/native/components/popover">
# Popover

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/popover
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(overlays)/popover.mdx
> Displays a floating content panel anchored to a trigger element with placement and alignment options.

## Import

```tsx
import { Popover } from 'heroui-native';

```

## Anatomy

```tsx
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content>
      <Popover.Arrow />
      <Popover.Close />
      <Popover.Title>...</Popover.Title>
      <Popover.Description>...</Popover.Description>
    </Popover.Content>
  </Popover.Portal>
</Popover>

```

* **Popover**: Main container that manages open/close state, positioning, and provides context to child components.
* **Popover.Trigger**: Clickable element that toggles popover visibility. Wraps any child element with press handlers.
* **Popover.Portal**: Renders popover content in a portal layer above other content. Ensures proper stacking and positioning.
* **Popover.Overlay**: Optional background overlay. Can be transparent or semi-transparent to capture outside clicks.
* **Popover.Content**: Container for popover content with positioning, styling, and collision detection. Supports both popover and bottom-sheet presentations.
* **Popover.Arrow**: Optional arrow element pointing to the trigger. Automatically positioned based on placement.
* **Popover.Close**: Close button that dismisses the popover when pressed. Renders a default X icon if no children provided.
* **Popover.Title**: Optional title text with pre-styled typography.
* **Popover.Description**: Optional description text with muted styling.

## Usage

### Basic Usage

The Popover component uses compound parts to create floating content panels.

```tsx
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content>...</Popover.Content>
  </Popover.Portal>
</Popover>

```

### With Title and Description

Structure popover content with title and description for better information hierarchy.

```tsx
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content>
      <Popover.Close />
      <Popover.Title>...</Popover.Title>
      <Popover.Description>...</Popover.Description>
    </Popover.Content>
  </Popover.Portal>
</Popover>

```

### With Arrow

Add an arrow pointing to the trigger element for better visual connection.

```tsx
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content placement="top">
      <Popover.Arrow />
      ...
    </Popover.Content>
  </Popover.Portal>
</Popover>

```

### Width Control

Control the width of the popover content using the `width` prop.

```tsx
{
  /* Fixed width in pixels */
}
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content width={320}>...</Popover.Content>
  </Popover.Portal>
</Popover>;

{
  /* Match trigger width */
}
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content width="trigger">...</Popover.Content>
  </Popover.Portal>
</Popover>;

{
  /* Full width (100%) */
}
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content width="full">...</Popover.Content>
  </Popover.Portal>
</Popover>;

{
  /* Auto-size to content (default) */
}
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content width="content-fit">...</Popover.Content>
  </Popover.Portal>
</Popover>;

```

### Bottom Sheet Presentation

Use bottom sheet presentation for mobile-optimized interaction patterns.

```tsx
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content presentation="bottom-sheet">
      <Popover.Title>...</Popover.Title>
      <Popover.Description>...</Popover.Description>
      <Popover.Close asChild>
        <Button>Close</Button>
      </Popover.Close>
    </Popover.Content>
  </Popover.Portal>
</Popover>

```

### Placement Options

Control where the popover appears relative to the trigger element.

```tsx
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Content placement="left">...</Popover.Content>
  </Popover.Portal>
</Popover>

```

### Alignment Options

Fine-tune content alignment along the placement axis.

```tsx
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Content placement="top" align="start">
      ...
    </Popover.Content>
  </Popover.Portal>
</Popover>

```

### Custom Animation

Configure custom animations for open and close transitions using the `animation` prop on `Popover.Root`.

```tsx
<Popover
  animation={{
    entering: {
      type: 'spring',
      config: { damping: 15, stiffness: 300 },
    },
    exiting: {
      type: 'timing',
      config: { duration: 200 },
    },
  }}
>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content>...</Popover.Content>
  </Popover.Portal>
</Popover>

```

### Programmatic control

```tsx
// Open or close popover programmatically using ref
const popoverRef = useRef<PopoverTriggerRef>(null);

// Open programmatically
popoverRef.current?.open();

// Close programmatically
popoverRef.current?.close();

// Full example
<Popover>
  <Popover.Trigger ref={popoverRef} asChild>
    <Button>Trigger</Button>
  </Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content>
      <Text>Content</Text>
      <Button onPress={() => popoverRef.current?.close()}>Close</Button>
    </Popover.Content>
  </Popover.Portal>
</Popover>;

```

## Example

```tsx
import { Ionicons } from '@expo/vector-icons';
import { Button, Popover, useThemeColor } from 'heroui-native';
import { Text, View } from 'react-native';

export default function PopoverExample() {
  const themeColorMuted = useThemeColor('muted');

return (
    <Popover>
      <Popover.Trigger asChild>
        <Button variant="tertiary" size="sm">
          <Button.StartContent>
            <Ionicons
              name="information-circle"
              size={20}
              color={themeColorMuted}
            />
          </Button.StartContent>
          <Button.LabelContent>Show Info</Button.LabelContent>
        </Button>
      </Popover.Trigger>
      <Popover.Portal>
        <Popover.Overlay />
        <Popover.Content width={320} className="gap-1 rounded-xl px-6 py-4">
          <Popover.Close className="absolute top-3 right-3 z-50" />
          <Popover.Title>Information</Popover.Title>
          <Popover.Description>
            This popover includes a title and description to provide more
            structured information to users.
          </Popover.Description>
        </Popover.Content>
      </Popover.Portal>
    </Popover>
  );
}

```

## API Reference

### Popover

| prop            | type                        | default | description                                                               |
| --------------- | --------------------------- | ------- | ------------------------------------------------------------------------- |
| `children`      | `ReactNode`                 | -       | Children elements to be rendered inside the popover                       |
| `isOpen`        | `boolean`                   | -       | Whether the popover is open (controlled mode)                             |
| `isDefaultOpen` | `boolean`                   | -       | The open state of the popover when initially rendered (uncontrolled mode) |
| `onOpenChange`  | `(isOpen: boolean) => void` | -       | Callback when the popover open state changes                              |
| `closeDelay`    | `number`                    | `400`   | Delay in milliseconds before closing the popover                          |
| `animation`     | `PopoverRootAnimation`      | -       | Animation configuration                                                   |
| `asChild`       | `boolean`                   | `false` | Whether to render as a child element                                      |
| `...ViewProps`  | `ViewProps`                 | -       | All standard React Native View props are supported                        |

#### PopoverRootAnimation

Animation configuration for popover root component. Can be:

#### SpringAnimationConfig

#### TimingAnimationConfig

### Popover.Trigger

### Popover.Portal

| prop           | type        | default | description                                        |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `children`     | `ReactNode` | -       | The portal content (required)                      |
| `hostName`     | `string`    | -       | Optional name of the host element for the portal   |
| `forceMount`   | `boolean`   | -       | Whether to force mount the component in the DOM    |
| `className`    | `string`    | -       | Additional CSS classes for the portal container    |
| `...ViewProps` | `ViewProps` | -       | All standard React Native View props are supported |

### Popover.Overlay

| prop                    | type                      | default | description                                          |
| ----------------------- | ------------------------- | ------- | ---------------------------------------------------- |
| `className`             | `string`                  | -       | Additional CSS classes for the overlay               |
| `closeOnPress`          | `boolean`                 | `true`  | Whether to close the popover when overlay is pressed |
| `forceMount`            | `boolean`                 | -       | Whether to force mount the component in the DOM      |
| `animation`             | `PopoverOverlayAnimation` | -       | Animation configuration                              |
| `asChild`               | `boolean`                 | `false` | Whether to render as a child element                 |
| `...Animated.ViewProps` | `Animated.ViewProps`      | -       | All Reanimated Animated.View props are supported     |

#### PopoverOverlayAnimation

Animation configuration for popover overlay component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

### Popover.Content (Popover Presentation)

| prop                      | type                                             | default         | description                                            |
| ------------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------ |
| `children`                | `ReactNode`                                      | -               | The popover content                                    |
| `width`                   | `number \| 'trigger' \| 'content-fit' \| 'full'` | `'content-fit'` | Width sizing strategy for the content                  |
| `placement`               | `'top' \| 'bottom' \| 'left' \| 'right'`         | `'bottom'`      | Placement of the popover relative to trigger           |
| `align`                   | `'start' \| 'center' \| 'end'`                   | `'center'`      | Alignment along the placement axis                     |
| `avoidCollisions`         | `boolean`                                        | `true`          | Whether to flip placement when close to viewport edges |
| `offset`                  | `number`                                         | `8`             | Distance from trigger element in pixels                |
| `alignOffset`             | `number`                                         | `0`             | Offset along the alignment axis in pixels              |
| `disablePositioningStyle` | `boolean`                                        | `false`         | Whether to disable automatic positioning styles        |
| `forceMount`              | `boolean`                                        | -               | Whether to force mount the component in the DOM        |
| `insets`                  | `Insets`                                         | -               | Screen edge insets to respect when positioning         |
| `className`               | `string`                                         | -               | Additional CSS classes for the content container       |
| `presentation`            | `'popover'`                                      | -               | Presentation mode for the popover                      |
| `animation`               | `PopupPopoverContentAnimation`                   | -               | Animation configuration                                |
| `asChild`                 | `boolean`                                        | `false`         | Whether to render as a child element                   |
| `...Animated.ViewProps`   | `Animated.ViewProps`                             | -               | All Reanimated Animated.View props are supported       |

### Popover.Content (Bottom Sheet Presentation)

| prop                       | type                   | default | description                                      |
| -------------------------- | ---------------------- | ------- | ------------------------------------------------ |
| `children`                 | `ReactNode`            | -       | The bottom sheet content                         |
| `presentation`             | `'bottom-sheet'`       | -       | Presentation mode for the popover                |
| `bottomSheetViewClassName` | `string`               | -       | Additional CSS classes for the bottom sheet view |
| `bottomSheetViewProps`     | `BottomSheetViewProps` | -       | Props for the bottom sheet view                  |
| `enablePanDownToClose`     | `boolean`              | `true`  | Whether pan down gesture closes the sheet        |
| `backgroundStyle`          | `ViewStyle`            | -       | Style for the bottom sheet background            |
| `handleIndicatorStyle`     | `ViewStyle`            | -       | Style for the bottom sheet handle indicator      |
| `...BottomSheetProps`      | `BottomSheetProps`     | -       | All @gorhom/bottom-sheet props are supported     |

#### PopupPopoverContentAnimation

Animation configuration for popover content component (popover presentation). Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop                    | type                       | default                                                          | description                            |
| ----------------------- | -------------------------- | ---------------------------------------------------------------- | -------------------------------------- |
| `opacity.value`         | `[number, number, number]` | `[0, 1, 0]`                                                      | Opacity values \[idle, open, close]    |
| `scale.value`           | `[number, number, number]` | `[0.95, 1, 0.95]`                                                | Scale values \[idle, open, close]      |
| `translateX.value`      | `[number, number, number]` | Based on placement<br />`(4, 0, 4)` or `(-4, 0, -4)`             | TranslateX values \[idle, open, close] |
| `translateY.value`      | `[number, number, number]` | Based on placement<br />`(4, 0, 4)` or `(-4, 0, -4)`             | TranslateY values \[idle, open, close] |
| `transformOrigin.value` | `string`                   | Based on placement<br />`'top'`, `'bottom'`, `'left'`, `'right'` | Transform origin value                 |

### Popover.Arrow

| prop                  | type                                     | default | description                                                           |
| --------------------- | ---------------------------------------- | ------- | --------------------------------------------------------------------- |
| `className`           | `string`                                 | -       | Additional CSS classes for the arrow                                  |
| `height`              | `number`                                 | `8`     | Height of the arrow in pixels                                         |
| `width`               | `number`                                 | `16`    | Width of the arrow in pixels                                          |
| `fill`                | `string`                                 | -       | Fill color of the arrow (defaults to content background)              |
| `stroke`              | `string`                                 | -       | Stroke (border) color of the arrow (defaults to content border color) |
| `strokeWidth`         | `number`                                 | `1`     | Stroke width of the arrow border in pixels                            |
| `strokeBaselineInset` | `number`                                 | `1`     | Baseline inset in pixels for stroke alignment                         |
| `placement`           | `'top' \| 'bottom' \| 'left' \| 'right'` | -       | Placement of the popover (inherited from content)                     |
| `children`            | `ReactNode`                              | -       | Custom arrow content (replaces default SVG arrow)                     |
| `style`               | `StyleProp<ViewStyle>`                   | -       | Additional styles for the arrow container                             |
| `...ViewProps`        | `ViewProps`                              | -       | All standard React Native View props are supported                    |

### Popover.Close

| prop                | type                    | default | description                                             |
| ------------------- | ----------------------- | ------- | ------------------------------------------------------- |
| `children`          | `ReactNode`             | -       | The close button content                                |
| `className`         | `string`                | -       | Additional CSS classes for the close button             |
| `iconProps`         | `PopoverCloseIconProps` | -       | Close icon configuration                                |
| `hitSlop`           | `number \| Insets`      | `12`    | Additional touch area around the button                 |
| `asChild`           | `boolean`               | -       | Whether to render as a child element                    |
| `...PressableProps` | `PressableProps`        | -       | All standard React Native Pressable props are supported |

#### PopoverCloseIconProps

| prop    | type     | default          | description       |
| ------- | -------- | ---------------- | ----------------- |
| `size`  | `number` | `18`             | Size of the icon  |
| `color` | `string` | `--colors.muted` | Color of the icon |

### Popover.Title

| prop           | type        | default | description                                        |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `children`     | `ReactNode` | -       | The title text content                             |
| `className`    | `string`    | -       | Additional CSS classes for the title               |
| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |

### Popover.Description

| prop           | type        | default | description                                        |
| -------------- | ----------- | ------- | -------------------------------------------------- |
| `children`     | `ReactNode` | -       | The description text content                       |
| `className`    | `string`    | -       | Additional CSS classes for the description         |
| `...TextProps` | `TextProps` | -       | All standard React Native Text props are supported |

## Hooks

### usePopover

Hook to access popover context values within custom components or compound components.

```tsx
import { usePopover } from 'heroui-native';

const CustomContent = () => {
  const { isOpen, onOpenChange, triggerPosition } = usePopover();
  // ... your implementation
};

```

**Returns:** `UsePopoverReturn`

| property             | type                                                | description                                                       |
| -------------------- | --------------------------------------------------- | ----------------------------------------------------------------- |
| `isOpen`             | `boolean`                                           | Whether the popover is currently open                             |
| `onOpenChange`       | `(open: boolean) => void`                           | Callback function to change the popover open state                |
| `isDefaultOpen`      | `boolean \| undefined`                              | Whether the popover should be open by default (uncontrolled mode) |
| `isDisabled`         | `boolean \| undefined`                              | Whether the popover is disabled                                   |
| `triggerPosition`    | `LayoutPosition \| null`                            | The position of the trigger element relative to the viewport      |
| `setTriggerPosition` | `(triggerPosition: LayoutPosition \| null) => void` | Function to update the trigger element's position                 |
| `contentLayout`      | `LayoutRectangle \| null`                           | The layout measurements of the popover content                    |
| `setContentLayout`   | `(contentLayout: LayoutRectangle \| null) => void`  | Function to update the content layout measurements                |
| `nativeID`           | `string`                                            | Unique identifier for the popover instance                        |
| `closeDelay`         | `number \| undefined`                               | Delay in milliseconds before the popover closes                   |

**Note:** This hook must be used within a `Popover` component. It will throw an error if called outside of the popover context.

### usePopoverAnimation

Hook to access popover animation state values within custom components or compound components.

```tsx
import { usePopoverAnimation } from 'heroui-native';

const CustomContent = () => {
  const { popoverState, progress, isDragging } = usePopoverAnimation();
  // ... your implementation
};

```

**Returns:** `UsePopoverAnimationReturn`

| property       | type                          | description                                                        |
| -------------- | ----------------------------- | ------------------------------------------------------------------ |
| `popoverState` | `'idle' \| 'open' \| 'close'` | Extended internal state for coordinating animations                |
| `progress`     | `SharedValue<number>`         | Progress value for the popover animation (0=idle, 1=open, 2=close) |
| `isDragging`   | `SharedValue<boolean>`        | Dragging state shared value                                        |

**Note:** This hook must be used within a `Popover` component. It will throw an error if called outside of the popover animation context.

</page>

<page url="/docs/native/components/toast">
# Toast

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/toast
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(overlays)/toast.mdx
> Displays temporary notification messages that appear at the top or bottom of the screen.

## Import

```tsx
import { Toast, useToast } from 'heroui-native';

```

## Anatomy

```tsx
<Toast>
  <Toast.Title>...</Toast.Title>
  <Toast.Description>...</Toast.Description>
  <Toast.Action>...</Toast.Action>
  <Toast.Close />
</Toast>

```

* **Toast**: Main container that displays notification messages. Handles positioning, animations, and swipe gestures.
* **Toast.Title**: Title text of the toast notification. Inherits variant styling from parent Toast context.
* **Toast.Description**: Descriptive text content displayed below the title.
* **Toast.Action**: Action button within the toast. Button variant is automatically determined based on toast variant but can be overridden.
* **Toast.Close**: Close button for dismissing the toast. Renders as an icon-only button that calls hide when pressed.

## Usage

### Usage Pattern 1: Simple String

Show a toast with a simple string message.

```tsx
const { toast } = useToast();

toast.show('This is a toast message');

```

### Usage Pattern 2: Config Object

Show a toast with label, description, variant, and action button using a config object.

```tsx
const { toast } = useToast();

toast.show({
  variant: 'success',
  label: 'You have upgraded your plan',
  description: 'You can continue using HeroUI Chat',
  icon: <Icon name="check" />,
  actionLabel: 'Close',
  onActionPress: ({ hide }) => hide(),
});

```

### Usage Pattern 3: Custom Component

Show a toast with a fully custom component for complete control over styling and layout.

```tsx
const { toast } = useToast();

toast.show({
  component: (props) => (
    <Toast variant="accent" placement="top" {...props}>
      <Toast.Title>Custom Toast</Toast.Title>
      <Toast.Description>This is a custom toast component</Toast.Description>
      <Toast.Close />
    </Toast>
  ),
});

```

**Note**: Toast items are memoized for performance. If you need to pass external state (like loading state) to a custom toast component, it will not update automatically. Use shared state techniques instead, such as React Context, state management libraries, or refs to ensure state updates propagate to the toast component.

### Disabling All Animations

Disable all animations including children by using `"disable-all"`. This cascades down to all child components (like Button in Toast.Action).

```tsx
const { toast } = useToast();

toast.show({
  variant: 'success',
  label: 'Operation completed',
  description: 'All animations are disabled',
  animation: 'disable-all',
});

```

Or with a custom component:

```tsx
const { toast } = useToast();

toast.show({
  component: (props) => (
    <Toast variant="accent" animation="disable-all" {...props}>
      <Toast.Title>No animations</Toast.Title>
      <Toast.Description>
        This toast has all animations disabled
      </Toast.Description>
      <Toast.Action>Action</Toast.Action>
    </Toast>
  ),
});

```

## Example

```tsx
import { Button, Toast, useToast, useThemeColor } from 'heroui-native';
import { View } from 'react-native';

export default function ToastExample() {
  const { toast } = useToast();
  const themeColorForeground = useThemeColor('foreground');

return (
    <View className="gap-4 p-4">
      <Button
        onPress={() =>
          toast.show({
            variant: 'success',
            label: 'You have upgraded your plan',
            description: 'You can continue using HeroUI Chat',
            actionLabel: 'Close',
            onActionPress: ({ hide }) => hide(),
          })
        }
      >
        Show Success Toast
      </Button>

<Button
        onPress={() =>
          toast.show({
            component: (props) => (
              <Toast variant="accent" {...props}>
                <Toast.Title>Custom Toast</Toast.Title>
                <Toast.Description>
                  This uses a custom component
                </Toast.Description>
                <Toast.Action onPress={() => props.hide()}>Undo</Toast.Action>
                <Toast.Close className="absolute top-0 right-0" />
              </Toast>
            ),
          })
        }
      >
        Show Custom Toast
      </Button>
    </View>
  );
}

```

## Global Configuration

Configure toast behavior globally using `HeroUINativeProvider` config prop. Global configs serve as defaults for all toasts unless overridden locally.

> **Note**: For complete provider configuration options, see the [Provider documentation](/docs/native/getting-started/handbook/provider#toast-configuration).

### Insets

Insets control the distance of toast sides from screen edges. Insets are added to safe area insets. To set all toasts to have a side distance of 20px from screen edges, configure insets:

```tsx
<HeroUINativeProvider
  config={{
    toast: {
      insets: {
        top: 20,
        bottom: 20,
        left: 20,
        right: 20,
      },
    },
  }}
>
  {children}
</HeroUINativeProvider>

```

### Content Wrapper with KeyboardAvoidingView

Wrap toast content with KeyboardAvoidingView to ensure toasts adjust when the keyboard appears:

```tsx
import {
  KeyboardAvoidingView,
  KeyboardProvider,
} from 'react-native-keyboard-controller';
import { HeroUINativeProvider } from 'heroui-native';
import { useCallback } from 'react';

function AppContent() {
  const contentWrapper = useCallback(
    (children: React.ReactNode) => (
      <KeyboardAvoidingView
        pointerEvents="box-none"
        behavior="padding"
        keyboardVerticalOffset={12}
        className="flex-1"
      >
        {children}
      </KeyboardAvoidingView>
    ),
    []
  );

return (
    <KeyboardProvider>
      <HeroUINativeProvider
        config={{
          toast: {
            contentWrapper,
          },
        }}
      >
        {children}
      </HeroUINativeProvider>
    </KeyboardProvider>
  );
}

```

### Default Props

Set global defaults for variant, placement, animation, and swipe behavior:

```tsx
<HeroUINativeProvider
  config={{
    toast: {
      defaultProps: {
        variant: 'accent',
        placement: 'bottom',
        isSwipeable: false,
      },
    },
  }}
>
  {children}
</HeroUINativeProvider>

```

## API Reference

### Toast

| prop           | type                                                          | default     | description                                                               |
| -------------- | ------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- |
| `variant`      | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Visual variant of the toast                                               |
| `placement`    | `'top' \| 'bottom'`                                           | `'top'`     | Placement of the toast on screen                                          |
| `isSwipeable`  | `boolean`                                                     | `true`      | Whether the toast can be swiped to dismiss and dragged with rubber effect |
| `animation`    | `ToastRootAnimation`                                          | -           | Animation configuration                                                   |
| `className`    | `string`                                                      | -           | Additional CSS class for the toast container                              |
| `...ViewProps` | `ViewProps`                                                   | -           | All standard React Native View props are supported                        |

#### ToastRootAnimation

Animation configuration for Toast component. Can be:

| prop                      | type                    | default                                                                                                                      | description                                                                      |
| ------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `opacity.value`           | `[number, number]`      | `[1, 0]`                                                                                                                     | Opacity interpolation values for fade effect as toasts move beyond visible stack |
| `opacity.timingConfig`    | `WithTimingConfig`      | `{ duration: 300 }`                                                                                                          | Animation timing configuration for opacity transitions                           |
| `translateY.value`        | `[number, number]`      | `[0, 10]`                                                                                                                    | Translate Y interpolation values for peek effect of stacked toasts               |
| `translateY.timingConfig` | `WithTimingConfig`      | `{ duration: 300 }`                                                                                                          | Animation timing configuration for translateY transitions                        |
| `scale.value`             | `[number, number]`      | `[1, 0.97]`                                                                                                                  | Scale interpolation values for depth effect of stacked toasts                    |
| `scale.timingConfig`      | `WithTimingConfig`      | `{ duration: 300 }`                                                                                                          | Animation timing configuration for scale transitions                             |
| `entering.top`            | `EntryOrExitLayoutType` | `FadeInUp`<br />`.springify()`<br />`.withInitialValues({ opacity: 1, transform: [{ translateY: -100 }] })`<br />`.mass(3)`  | Custom entering animation for top placement                                      |
| `entering.bottom`         | `EntryOrExitLayoutType` | `FadeInDown`<br />`.springify()`<br />`.withInitialValues({ opacity: 1, transform: [{ translateY: 100 }] })`<br />`.mass(3)` | Custom entering animation for bottom placement                                   |
| `exiting.top`             | `EntryOrExitLayoutType` | Keyframe animation with<br />`translateY: -100, scale: 0.97, opacity: 0.5`                                                   | Custom exiting animation for top placement                                       |
| `exiting.bottom`          | `EntryOrExitLayoutType` | Keyframe animation with<br />`translateY: 100, scale: 0.97, opacity: 0.5`                                                    | Custom exiting animation for bottom placement                                    |

### Toast.Title

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Content to be rendered as title                    |
| `className`    | `string`          | -       | Additional CSS classes                             |
| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |

### Toast.Description

| prop           | type              | default | description                                        |
| -------------- | ----------------- | ------- | -------------------------------------------------- |
| `children`     | `React.ReactNode` | -       | Content to be rendered as description              |
| `className`    | `string`          | -       | Additional CSS classes                             |
| `...TextProps` | `TextProps`       | -       | All standard React Native Text props are supported |

### Toast.Action

Toast.Action extends all props from [Button](button) component. Button variant is automatically determined based on toast variant but can be overridden.

| prop        | type                   | default | description                                                                  |
| ----------- | ---------------------- | ------- | ---------------------------------------------------------------------------- |
| `children`  | `React.ReactNode`      | -       | Content to be rendered as action button label                                |
| `variant`   | `ButtonVariant`        | -       | Button variant. If not provided, automatically determined from toast variant |
| `size`      | `'sm' \| 'md' \| 'lg'` | `'sm'`  | Size of the action button                                                    |
| `className` | `string`               | -       | Additional CSS classes                                                       |

For inherited props including `onPress`, `isDisabled`, and all Button props, see [Button API Reference](button#api-reference).

### Toast.Close

Toast.Close extends all props from [Button](button) component.

| prop        | type                                | default | description                                    |
| ----------- | ----------------------------------- | ------- | ---------------------------------------------- |
| `children`  | `React.ReactNode`                   | -       | Custom close icon. Defaults to CloseIcon       |
| `iconProps` | `{ size?: number; color?: string }` | -       | Props for the default close icon               |
| `size`      | `'sm' \| 'md' \| 'lg'`              | `'sm'`  | Size of the close button                       |
| `className` | `string`                            | -       | Additional CSS classes                         |
| `onPress`   | `(event: any) => void`              | -       | Custom press handler. Defaults to hiding toast |

For inherited props including `isDisabled` and all Button props, see [Button API Reference](button#api-reference).

### ToastProviderProps

Props for configuring toast behavior globally via `HeroUINativeProvider` config prop.

| prop               | type                                                | default | description                                                      |
| ------------------ | --------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `defaultProps`     | `ToastGlobalConfig`                                 | -       | Global toast configuration used as defaults for all toasts       |
| `insets`           | `ToastInsets`                                       | -       | Insets for spacing from screen edges (added to safe area insets) |
| `maxVisibleToasts` | `number`                                            | `3`     | Maximum number of visible toasts before opacity starts fading    |
| `contentWrapper`   | `(children: React.ReactNode) => React.ReactElement` | -       | Custom wrapper function to wrap toast content                    |
| `children`         | `React.ReactNode`                                   | -       | Children to render                                               |

#### ToastGlobalConfig

Global toast configuration used as defaults for all toasts unless overridden locally.

| prop          | type                                                          | description                                                               |
| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `variant`     | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | Visual variant of the toast                                               |
| `placement`   | `'top' \| 'bottom'`                                           | Placement of the toast on screen                                          |
| `isSwipeable` | `boolean`                                                     | Whether the toast can be swiped to dismiss and dragged with rubber effect |
| `animation`   | `ToastRootAnimation`                                          | Animation configuration for toast                                         |

#### ToastInsets

Insets for spacing from screen edges. Values are added to safe area insets.

| prop     | type     | default | description                                                                                               |
| -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `top`    | `number` | -       | Inset from the top edge in pixels (added to safe area inset). Platform-specific: iOS = 0, Android = 12    |
| `bottom` | `number` | -       | Inset from the bottom edge in pixels (added to safe area inset). Platform-specific: iOS = 6, Android = 12 |
| `left`   | `number` | -       | Inset from the left edge in pixels (added to safe area inset). Default: 12                                |
| `right`  | `number` | -       | Inset from the right edge in pixels (added to safe area inset). Default: 12                               |

## Hooks

### useToast

Hook to access toast functionality. Must be used within a `ToastProvider` (provided by `HeroUINativeProvider`).

| return value     | type           | description                              |
| ---------------- | -------------- | ---------------------------------------- |
| `toast`          | `ToastManager` | Toast manager with show and hide methods |
| `isToastVisible` | `boolean`      | Whether any toast is currently visible   |

#### ToastManager

| method | type                                              | description                                                                                                                          |
| ------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `show` | `(options: string \| ToastShowOptions) => string` | Show a toast. Returns the ID of the shown toast. Supports three usage patterns: simple string, config object, or custom component    |
| `hide` | `(ids?: string \| string[] \| 'all') => void`     | Hide one or more toasts. No argument hides the last toast, 'all' hides all toasts, single ID or array of IDs hides specific toast(s) |

#### ToastShowOptions

Options for showing a toast. Can be either a config object with default styling or a custom component.

**When using config object (without component):**

| prop            | type                                                                                                                              | default | description                                                                         |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `variant`       | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'`                                                                     | -       | Visual variant of the toast                                                         |
| `placement`     | `'top' \| 'bottom'`                                                                                                               | -       | Placement of the toast on screen                                                    |
| `isSwipeable`   | `boolean`                                                                                                                         | -       | Whether the toast can be swiped to dismiss                                          |
| `animation`     | `ToastRootAnimation \| false \| "disabled" \| "disable-all"`                                                                      | -       | Animation configuration for toast                                                   |
| `duration`      | `number \| 'persistent'`                                                                                                          | `4000`  | Duration in milliseconds before auto-hide. Set to 'persistent' to prevent auto-hide |
| `id`            | `string`                                                                                                                          | -       | Optional ID for the toast. If not provided, one will be generated                   |
| `label`         | `string`                                                                                                                          | -       | Label text for the toast                                                            |
| `description`   | `string`                                                                                                                          | -       | Description text for the toast                                                      |
| `actionLabel`   | `string`                                                                                                                          | -       | Action button label text                                                            |
| `onActionPress` | `(helpers: { show: (options: string \| ToastShowOptions) => string; hide: (ids?: string \| string[] \| 'all') => void }) => void` | -       | Callback function called when the action button is pressed                          |
| `icon`          | `React.ReactNode`                                                                                                                 | -       | Icon element to display in the toast                                                |
| `onShow`        | `() => void`                                                                                                                      | -       | Callback function called when the toast is shown                                    |
| `onHide`        | `() => void`                                                                                                                      | -       | Callback function called when the toast is hidden                                   |

**When using custom component:**

| prop        | type                                                 | default | description                                                                         |
| ----------- | ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
| `id`        | `string`                                             | -       | Optional ID for the toast. If not provided, one will be generated                   |
| `component` | `(props: ToastComponentProps) => React.ReactElement` | -       | A function that receives toast props and returns a React element                    |
| `duration`  | `number \| 'persistent'`                             | `4000`  | Duration in milliseconds before auto-hide. Set to 'persistent' to prevent auto-hide |
| `onShow`    | `() => void`                                         | -       | Callback function called when the toast is shown                                    |
| `onHide`    | `() => void`                                         | -       | Callback function called when the toast is hidden                                   |

## Special Notes

### Styling Notes

#### Border as Padding

Toast uses `border-[16px]` class which serves as padding. This is intentional because when visible toasts have different heights, the toast adapts to the last visible toast height. In cases where a toast originally has one height and gets smaller when a new toast comes to stack, content might be visible behind the last toast without proper padding. The border ensures consistent spacing regardless of toast height changes.

For padding, use `border` classes. For actual borders, use `outline` classes.

</page>

<page url="/docs/native/components/pressable-feedback">
# PressableFeedback

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/pressable-feedback
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(utilities)/pressable-feedback.mdx
> Container component that provides visual feedback for press interactions with automatic scale animation.

## Import

```tsx
import { PressableFeedback } from 'heroui-native';

```

## Usage

### Basic Usage

The PressableFeedback component wraps content to provide press feedback effects. By default, it applies a subtle scale animation when pressed.

```tsx
<PressableFeedback>...</PressableFeedback>

```

### Highlight Variant

Default iOS-style highlight feedback effect with automatic scale animation.

```tsx
<PressableFeedback feedbackVariant="highlight">...</PressableFeedback>

```

### Ripple Variant

Android-style ripple feedback effect that emanates from the press point, combined with scale animation.

```tsx
<PressableFeedback feedbackVariant="ripple">...</PressableFeedback>

```

### Custom Highlight Animation

Configure highlight overlay opacity and background color while maintaining the default scale effect.

```tsx
<PressableFeedback
  feedbackVariant="highlight"
  animation={{
    highlight: {
      opacity: { value: [0, 0.2] },
      backgroundColor: { value: '#3b82f6' },
    },
  }}
>
  ...
</PressableFeedback>

```

### Custom Ripple Animation

Configure ripple effect color, opacity, and duration along with scale animation.

```tsx
<PressableFeedback
  feedbackVariant="ripple"
  animation={{
    ripple: {
      backgroundColor: { value: '#ec4899' },
      opacity: { value: [0, 0.3, 0] },
      progress: { baseDuration: 600 },
    },
  }}
>
  ...
</PressableFeedback>

```

### Feedback Position

Control whether the feedback effect renders above or below content.

```tsx
<PressableFeedback feedbackPosition="behind">
  ...
</PressableFeedback>

```

### Custom Scale Animation

Customize or disable the default scale animation on press.

```tsx
<PressableFeedback
  animation={{
    scale: {
      value: 0.98,
      timingConfig: { duration: 150 }
    }
  }}
>
  ...
</PressableFeedback>

```

### Disabled State

Disable press interactions and all feedback animations.

```tsx
<PressableFeedback animation="disabled">...</PressableFeedback>

```

## Example

```tsx
import { PressableFeedback, Card } from 'heroui-native';
import { View, Text, Image } from 'react-native';

export default function PressableFeedbackExample() {
  return (
    <View className="flex-1 items-center justify-center px-5">
      <View className="flex-row gap-4">
        <PressableFeedback
          feedbackVariant="ripple"
          className="flex-1 aspect-[1/1.3] rounded-3xl"
          animation={{
            ripple: {
              backgroundColor: { value: '#fecdd3' },
              opacity: { value: [0, 0.2, 0] },
            },
          }}
        >
          <Card className="flex-1">
            <View className="flex-1 gap-4">
              <Card.Header>
                <Image
                  source={{
                    uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg',
                  }}
                  style={{
                    height: 60,
                    aspectRatio: 1,
                    borderRadius: 14,
                  }}
                />
              </Card.Header>
              <Card.Body className="flex-1">
                <Card.Title>Indie Hackers</Card.Title>
                <Card.Description className="text-sm">
                  148 members
                </Card.Description>
              </Card.Body>
              <Card.Footer className="flex-row items-center gap-2">
                <View className="size-3 rounded-full bg-rose-400" />
                <Text className="text-sm font-medium text-foreground">
                  @indiehackers
                </Text>
              </Card.Footer>
            </View>
          </Card>
        </PressableFeedback>
        <PressableFeedback
          feedbackVariant="ripple"
          className="flex-1 aspect-[1/1.3] rounded-3xl"
          animation={{
            ripple: {
              backgroundColor: { value: '#67e8f9' },
            },
          }}
        >
          <Card className="flex-1">
            <View className="flex-1 gap-4">
              <Card.Header>
                <Image
                  source={{
                    uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg',
                  }}
                  style={{
                    height: 60,
                    aspectRatio: 1,
                    borderRadius: 14,
                  }}
                />
              </Card.Header>
              <Card.Body className="flex-1">
                <Card.Title>AI Builders</Card.Title>
                <Card.Description className="text-sm">
                  362 members
                </Card.Description>
              </Card.Body>
              <Card.Footer className="flex-row items-center gap-2">
                <View className="size-3 rounded-full bg-emerald-400" />
                <Text className="text-sm font-medium text-foreground">
                  @aibuilders
                </Text>
              </Card.Footer>
            </View>
          </Card>
        </PressableFeedback>
      </View>
    </View>
  );
}

```

## API Reference

### PressableFeedback

| prop               | type                                                                              | default       | description                                                          |
| ------------------ | --------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------- |
| `children`         | `React.ReactNode`                                                                 | -             | Content to be wrapped with press feedback                            |
| `feedbackVariant`  | `'highlight' \| 'ripple'`                                                         | `'highlight'` | Type of feedback effect to display                                   |
| `feedbackPosition` | `'behind' \| 'top'`                                                               | `'top'`       | Controls z-index positioning of feedback effect relative to children |
| `isDisabled`       | `boolean`                                                                         | `false`       | Whether the pressable component is disabled                          |
| `className`        | `string`                                                                          | -             | Additional CSS classes                                               |
| `animation`        | `PressableFeedbackHighlightRootAnimation \| PressableFeedbackRippleRootAnimation` | -             | Animation configuration                                              |
| `...AnimatedProps` | `AnimatedProps<PressableProps>`                                                   | -             | All Reanimated Animated Pressable props are supported                |

#### PressableFeedbackHighlightRootAnimation

Animation configuration for PressableFeedback component with highlight variant. Can be:

| prop                                              | type               | default                                              | description                                                                |
| ------------------------------------------------- | ------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------- |
| `scale`<br />`.value`                             | `number`           | `0.985`                                              | Scale value when pressed (automatically adjusted based on container width) |
| `scale`<br />`.timingConfig`                      | `WithTimingConfig` | `{ duration: 300, easing: Easing.out(Easing.ease) }` | Animation timing configuration                                             |
| `scale`<br />`.ignoreScaleCoefficient`            | `boolean`          | `false`                                              | Ignore automatic scale coefficient and use the scale value directly        |
| `highlight`<br />`.opacity`<br />`.value`         | `[number, number]` | `[0, 0.1]`                                           | Opacity values \[unpressed, pressed]                                       |
| `highlight`<br />`.opacity`<br />`.timingConfig`  | `WithTimingConfig` | `{ duration: 200 }`                                  | Animation timing configuration                                             |
| `highlight`<br />`.backgroundColor`<br />`.value` | `string`           | Computed based on theme                              | Background color of highlight overlay                                      |

#### PressableFeedbackRippleRootAnimation

Animation configuration for PressableFeedback component with ripple variant. Can be:

| prop                                                        | type                       | default                                              | description                                                                  |
| ----------------------------------------------------------- | -------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------- |
| `scale`<br />`.value`                                       | `number`                   | `0.985`                                              | Scale value when pressed (automatically adjusted based on container width)   |
| `scale`<br />`.timingConfig`                                | `WithTimingConfig`         | `{ duration: 300, easing: Easing.out(Easing.ease) }` | Animation timing configuration                                               |
| `scale`<br />`.ignoreScaleCoefficient`                      | `boolean`                  | `false`                                              | Ignore automatic scale coefficient and use the scale value directly          |
| `ripple`<br />`.backgroundColor`<br />`.value`              | `string`                   | Computed based on theme                              | Background color of ripple effect                                            |
| `ripple`<br />`.progress`<br />`.baseDuration`              | `number`                   | `1000`                                               | Base duration for ripple progress (automatically adjusted based on diagonal) |
| `ripple`<br />`.progress`<br />`.minBaseDuration`           | `number`                   | -                                                    | Minimum base duration for the ripple progress animation                      |
| `ripple`<br />`.progress`<br />`.ignoreDurationCoefficient` | `boolean`                  | `false`                                              | Ignore automatic duration coefficient and use base duration directly         |
| `ripple`<br />`.opacity`<br />`.value`                      | `[number, number, number]` | `[0, 0.1, 0]`                                        | Opacity values \[start, peak, end] for ripple animation                      |
| `ripple`<br />`.opacity`<br />`.timingConfig`               | `WithTimingConfig`         | `{ duration: 30 }`                                   | Animation timing configuration                                               |
| `ripple`<br />`.scale`<br />`.value`                        | `[number, number, number]` | `[0, 1, 1]`                                          | Scale values \[start, peak, end] for ripple animation                        |
| `ripple`<br />`.scale`<br />`.timingConfig`                 | `WithTimingConfig`         | `{ duration: 30 }`                                   | Animation timing configuration                                               |

</page>

<page url="/docs/native/components/scroll-shadow">
# ScrollShadow

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/scroll-shadow
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(utilities)/scroll-shadow.mdx
> Adds dynamic gradient shadows to scrollable content based on scroll position and overflow.

## Import

```tsx
import { ScrollShadow } from 'heroui-native';

```

## Anatomy

```tsx
<ScrollShadow LinearGradientComponent={LinearGradient}>
  <ScrollView>...</ScrollView>
</ScrollShadow>

```

* **ScrollShadow**: Main container that wraps scrollable components and adds dynamic gradient shadows at the edges based on scroll position and content overflow. Automatically detects scroll orientation (horizontal/vertical) and manages shadow visibility.
* **LinearGradientComponent**: Required prop that accepts a LinearGradient component from compatible libraries (expo-linear-gradient, react-native-linear-gradient, etc.) to render the gradient shadows.

## Usage

### Basic Usage

Wrap any scrollable component to automatically add edge shadows.

```tsx
<ScrollShadow LinearGradientComponent={LinearGradient}>
  <ScrollView>...</ScrollView>
</ScrollShadow>

```

### Horizontal Scrolling

The component auto-detects horizontal scrolling from the child's `horizontal` prop.

```tsx
<ScrollShadow LinearGradientComponent={LinearGradient}>
  <FlatList horizontal data={data} renderItem={...} />
</ScrollShadow>

```

### Custom Shadow Size

Control the gradient shadow height/width with the `size` prop.

```tsx
<ScrollShadow size={100} LinearGradientComponent={LinearGradient}>
  <ScrollView>...</ScrollView>
</ScrollShadow>

```

### Visibility Control

Specify which shadows to display using the `visibility` prop.

```tsx
<ScrollShadow visibility="top" LinearGradientComponent={LinearGradient}>
  <ScrollView>...</ScrollView>
</ScrollShadow>

```

### Custom Shadow Color

Override the default shadow color which uses the theme's background.

```tsx
<ScrollShadow color="#ffffff" LinearGradientComponent={LinearGradient}>
  <ScrollView>...</ScrollView>
</ScrollShadow>

```

### With Custom Scroll Handler

**Important:** ScrollShadow internally converts the child to a Reanimated animated component. If you need to use the `onScroll` prop, you must use `useAnimatedScrollHandler` from react-native-reanimated.

```tsx
import { LinearGradient } from 'expo-linear-gradient';
import Animated, { useAnimatedScrollHandler } from 'react-native-reanimated';

const scrollHandler = useAnimatedScrollHandler({
  onScroll: (event) => {
    console.log(event.contentOffset.y);
  },
});

<ScrollShadow LinearGradientComponent={LinearGradient}>
  <Animated.ScrollView onScroll={scrollHandler}>...</Animated.ScrollView>
</ScrollShadow>;

```

## Example

```tsx
import { ScrollShadow, Surface } from 'heroui-native';
import { LinearGradient } from 'expo-linear-gradient';
import { FlatList, ScrollView, Text, View } from 'react-native';

export default function ScrollShadowExample() {
  const horizontalData = Array.from({ length: 10 }, (_, i) => ({
    id: i,
    title: `Card ${i + 1}`,
  }));

return (
    <View className="flex-1 bg-background">
      <Text className="px-5 py-3 text-lg font-semibold">Horizontal List</Text>
      <ScrollShadow LinearGradientComponent={LinearGradient}>
        <FlatList
          data={horizontalData}
          horizontal
          renderItem={({ item }) => (
            <Surface variant="2" className="w-32 h-24 justify-center px-4">
              <Text>{item.title}</Text>
            </Surface>
          )}
          showsHorizontalScrollIndicator={false}
          contentContainerClassName="p-5 gap-4"
        />
      </ScrollShadow>

<Text className="px-5 py-3 text-lg font-semibold">Vertical Content</Text>
      <ScrollShadow
        size={80}
        className="h-48"
        LinearGradientComponent={LinearGradient}
      >
        <ScrollView
          contentContainerClassName="p-5"
          showsVerticalScrollIndicator={false}
        >
          <Text className="mb-4 text-2xl font-bold">Long Content</Text>
          <Text className="mb-4 text-base leading-6">
            Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
            eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim
            ad minim veniam, quis nostrud exercitation ullamco laboris.
          </Text>
          <Text className="mb-4 text-base leading-6">
            Sed ut perspiciatis unde omnis iste natus error sit voluptatem
            accusantium doloremque laudantium, totam rem aperiam, eaque ipsa
            quae ab illo inventore veritatis et quasi architecto beatae vitae.
          </Text>
        </ScrollView>
      </ScrollShadow>
    </View>
  );
}

```

## API Reference

### ScrollShadow

| prop                      | type                                                                   | default      | description                                                                                                     |
| ------------------------- | ---------------------------------------------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------- |
| `children`                | `React.ReactElement`                                                   | -            | The scrollable component to enhance with shadows. Must be a single React element (ScrollView, FlatList, etc.)   |
| `LinearGradientComponent` | `ComponentType<`<br />`LinearGradientProps>`                           | **required** | LinearGradient component from any compatible library (expo-linear-gradient, react-native-linear-gradient, etc.) |
| `size`                    | `number`                                                               | `50`         | Size (height/width) of the gradient shadow in pixels                                                            |
| `orientation`             | `'horizontal' \| 'vertical'`                                           | auto-detect  | Orientation of the scroll shadow. If not provided, will auto-detect from child's `horizontal` prop              |
| `visibility`              | `'auto' \| 'top' \| 'bottom' \| 'left' \| 'right' \| 'both' \| 'none'` | `'auto'`     | Visibility mode for the shadows. 'auto' shows shadows based on scroll position and content overflow             |
| `color`                   | `string`                                                               | theme color  | Custom color for the gradient shadow. If not provided, uses the theme's background color                        |
| `isEnabled`               | `boolean`                                                              | `true`       | Whether the shadow effect is enabled                                                                            |
| `animation`               | `ScrollShadowRootAnimation`                                            | -            | Animation configuration                                                                                         |
| `className`               | `string`                                                               | -            | Additional CSS classes to apply to the container                                                                |
| `...ViewProps`            | `ViewProps`                                                            | -            | All standard React Native View props are supported                                                              |

#### ScrollShadowRootAnimation

Animation configuration for ScrollShadow component. Can be:

| prop            | type               | default  | description                                                                          |
| --------------- | ------------------ | -------- | ------------------------------------------------------------------------------------ |
| `opacity.value` | `[number, number]` | `[0, 1]` | `Opacity values [initial, active].`<br />`For bottom/right shadow, this is reversed` |

### LinearGradientProps

The `LinearGradientComponent` prop expects a component that accepts these props:

| prop        | type                              | description                                                        |
| ----------- | --------------------------------- | ------------------------------------------------------------------ |
| `colors`    | `any`                             | Array of colors for the gradient                                   |
| `locations` | `any` (optional)                  | Array of numbers defining the location of each gradient color stop |
| `start`     | `any` (optional)                  | Start point of the gradient (e.g., `{ x: 0, y: 0 }`)               |
| `end`       | `any` (optional)                  | End point of the gradient (e.g., `{ x: 1, y: 0 }`)                 |
| `style`     | `StyleProp<ViewStyle>` (optional) | Style to apply to the gradient view                                |

## Special Notes

**Important:** ScrollShadow internally converts the child to a Reanimated animated component. If you need to use the `onScroll` prop on your scrollable component, you must use `useAnimatedScrollHandler` from react-native-reanimated instead of the standard `onScroll` prop.

</page>

<page url="/docs/react/components/button-group">
# ButtonGroup

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/button-group
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(buttons)/button-group.mdx
> Group related buttons together with consistent styling and spacing

## Import

```tsx
import { ButtonGroup } from '@heroui/react';

```

### Usage

```

### Anatomy

```tsx
import { ButtonGroup, Button } from '@heroui/react';

export default () => (
  <ButtonGroup>
    <Button>First</Button>
    <Button>Second</Button>
    <Button>Third</Button>
  </ButtonGroup>
)

```

> **ButtonGroup** wraps multiple Button components together, applying consistent styling, spacing, and automatic border radius handling. It uses React Context to pass `size`, `variant`, and `isDisabled` props to all child buttons.

### Variants

```tsx
import {Button, ButtonGroup} from "@heroui/react";

export function Variants() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex flex-col gap-2">
        <p className="text-sm text-muted">Primary</p>
        <ButtonGroup variant="primary">
          <Button>First</Button>
          <Button>Second</Button>
          <Button>Third</Button>
        </ButtonGroup>
      </div>
      <div className="flex flex-col gap-2">
        <p className="text-sm text-muted">Secondary</p>
        <ButtonGroup variant="secondary">
          <Button>First</Button>
          <Button>Second</Button>
          <Button>Third</Button>
        </ButtonGroup>
      </div>
      <div className="flex flex-col gap-2">
        <p className="text-sm text-muted">Tertiary</p>
        <ButtonGroup variant="tertiary">
          <Button>First</Button>
          <Button>Second</Button>
          <Button>Third</Button>
        </ButtonGroup>
      </div>
      <div className="flex flex-col gap-2">
        <p className="text-sm text-muted">Ghost</p>
        <ButtonGroup variant="ghost">
          <Button>First</Button>
          <Button>Second</Button>
          <Button>Third</Button>
        </ButtonGroup>
      </div>
      <div className="flex flex-col gap-2">
        <p className="text-sm text-muted">Danger</p>
        <ButtonGroup variant="danger">
          <Button>First</Button>
          <Button>Second</Button>
          <Button>Third</Button>
        </ButtonGroup>
      </div>
    </div>
  );
}

```

### Sizes

```tsx
import {Button, ButtonGroup} from "@heroui/react";

export function Sizes() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex flex-col items-start gap-2">
        <p className="text-sm text-muted">Small</p>
        <ButtonGroup size="sm" variant="secondary">
          <Button>First</Button>
          <Button>Second</Button>
          <Button>Third</Button>
        </ButtonGroup>
      </div>
      <div className="flex flex-col items-start gap-2">
        <p className="text-sm text-muted">Medium (default)</p>
        <ButtonGroup size="md" variant="secondary">
          <Button>First</Button>
          <Button>Second</Button>
          <Button>Third</Button>
        </ButtonGroup>
      </div>
      <div className="flex flex-col items-start gap-2">
        <p className="text-sm text-muted">Large</p>
        <ButtonGroup size="lg" variant="secondary">
          <Button>First</Button>
          <Button>Second</Button>
          <Button>Third</Button>
        </ButtonGroup>
      </div>
    </div>
  );
}

```

### With Icons

```tsx
import {Globe, Plus, TrashBin} from "@gravity-ui/icons";
import {Button, ButtonGroup} from "@heroui/react";

export function WithIcons() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex flex-col items-start gap-2">
        <p className="text-sm text-muted">With icons</p>
        <ButtonGroup variant="secondary">
          <Button>
            <Globe />
            Search
          </Button>
          <Button>
            <Plus />
            Add
          </Button>
          <Button>
            <TrashBin />
            Delete
          </Button>
        </ButtonGroup>
      </div>
      <div className="flex flex-col items-start gap-2">
        <p className="text-sm text-muted">Icon only buttons</p>
        <ButtonGroup variant="tertiary">
          <Button isIconOnly>
            <Globe />
          </Button>
          <Button isIconOnly>
            <Plus />
          </Button>
          <Button isIconOnly>
            <TrashBin />
          </Button>
        </ButtonGroup>
      </div>
    </div>
  );
}

```

### Full Width

```tsx
import {TextAlignCenter, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons";
import {Button, ButtonGroup} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-3">
      <ButtonGroup fullWidth>
        <Button>First</Button>
        <Button>Second</Button>
        <Button>Third</Button>
      </ButtonGroup>
      <ButtonGroup fullWidth>
        <Button isIconOnly>
          <TextAlignLeft />
        </Button>
        <Button isIconOnly>
          <TextAlignCenter />
        </Button>
        <Button isIconOnly>
          <TextAlignRight />
        </Button>
      </ButtonGroup>
    </div>
  );
}

```

### Disabled State

```tsx
import {Button, ButtonGroup} from "@heroui/react";

export function Disabled() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex flex-col items-start gap-2">
        <p className="text-sm text-muted">All buttons disabled</p>
        <ButtonGroup isDisabled>
          <Button>First</Button>
          <Button>Second</Button>
          <Button>Third</Button>
        </ButtonGroup>
      </div>
      <div className="flex flex-col items-start gap-2">
        <p className="text-sm text-muted">Group disabled, but one button overrides</p>
        <ButtonGroup isDisabled>
          <Button>First</Button>
          <Button>Second</Button>
          <Button isDisabled={false}>Third (enabled)</Button>
        </ButtonGroup>
      </div>
    </div>
  );
}

```

### Without Separator

```tsx
import {Button, ButtonGroup} from "@heroui/react";

export function WithoutSeparator() {
  return (
    <ButtonGroup hideSeparator>
      <Button>First</Button>
      <Button>Second</Button>
      <Button>Third</Button>
    </ButtonGroup>
  );
}

```

## Related Components

* **Button**: Allows a user to perform an action
* **Dropdown**: Context menu with actions and options
* **Chip**: Compact elements for tags and filters

## Styling

### Passing Tailwind CSS classes

```tsx
import { ButtonGroup } from '@heroui/react';

function CustomButtonGroup() {
  return (
    <ButtonGroup className="gap-2">
      <Button>First</Button>
      <Button>Second</Button>
      <Button>Third</Button>
    </ButtonGroup>
  );
}

```

### Customizing the component classes

To customize the ButtonGroup component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .button-group {
    @apply gap-2 rounded-lg;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The ButtonGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)):

#### Base Classes

* `.button-group` - Base button group container

The ButtonGroup component automatically applies border radius to buttons:

* First button gets rounded left/start edge
* Last button gets rounded right/end edge
* Middle buttons have no border radius
* Single button gets full border radius on all edges

Separators are automatically added between buttons using a pseudo-element (`:before`) on buttons that are not the first child.

## API Reference

### ButtonGroup Props

| Prop            | Type                                                            | Default | Description                                                                             |
| --------------- | --------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------- |
| `variant`       | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'` | -       | Visual style variant applied to all buttons in the group                                |
| `size`          | `'sm' \| 'md' \| 'lg'`                                          | -       | Size applied to all buttons in the group                                                |
| `fullWidth`     | `boolean`                                                       | `false` | Whether the button group should take full width of its container                        |
| `isDisabled`    | `boolean`                                                       | `false` | Whether all buttons in the group are disabled (can be overridden on individual buttons) |
| `hideSeparator` | `boolean`                                                       | `false` | Hide separator lines between buttons                                                    |
| `className`     | `string`                                                        | -       | Additional CSS classes                                                                  |
| `children`      | `React.ReactNode`                                               | -       | Button components to group together                                                     |

### Notes

* ButtonGroup uses React Context to pass `size`, `variant`, and `isDisabled` props to all child Button components
* Individual Button components can override the group's `isDisabled` prop by setting `isDisabled={false}`
* The component automatically handles border radius and separators between buttons
* Buttons in a group have their active/pressed scale transform removed for a more cohesive appearance

</page>

<page url="/docs/react/components/button">
# Button

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/button
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(buttons)/button.mdx
> A clickable button component with multiple variants and states

## Import

```tsx
import { Button } from '@heroui/react';

```

### Usage

```tsx
"use client";

import {Button} from "@heroui/react";

export function Basic() {
  return <Button onPress={() => console.log("Button pressed")}>Click me</Button>;
}

```

### Variants

```tsx
import {Button} from "@heroui/react";

export function Variants() {
  return (
    <div className="flex flex-wrap gap-3">
      <Button>Primary</Button>
      <Button variant="secondary">Secondary</Button>
      <Button variant="tertiary">Tertiary</Button>
      <Button variant="ghost">Ghost</Button>
      <Button variant="danger">Danger</Button>
      <Button variant="danger-soft">Danger Soft</Button>
    </div>
  );
}

```

### With Icons

```tsx
import {Envelope, Globe, Plus, TrashBin} from "@gravity-ui/icons";
import {Button} from "@heroui/react";

export function WithIcons() {
  return (
    <div className="flex flex-wrap gap-3">
      <Button>
        <Globe />
        Search
      </Button>
      <Button variant="secondary">
        <Plus />
        Add Member
      </Button>
      <Button variant="tertiary">
        <Envelope />
        Email
      </Button>
      <Button variant="danger">
        <TrashBin />
        Delete
      </Button>
    </div>
  );
}

```

### Icon Only

```tsx
import {Ellipsis, Gear, TrashBin} from "@gravity-ui/icons";
import {Button} from "@heroui/react";

export function IconOnly() {
  return (
    <div className="flex gap-3">
      <Button isIconOnly variant="tertiary">
        <Ellipsis />
      </Button>
      <Button isIconOnly variant="secondary">
        <Gear />
      </Button>
      <Button isIconOnly variant="danger">
        <TrashBin />
      </Button>
    </div>
  );
}

```

### Loading

```tsx
"use client";

import {Button, Spinner} from "@heroui/react";
import React from "react";

export function Loading() {
  return (
    <Button isPending>
      {({isPending}) => (
        <>
          {isPending ? <Spinner color="current" size="sm" /> : null}
          Uploading...
        </>
      )}
    </Button>
  );
}

```

### Loading State

```tsx
"use client";

import {Paperclip} from "@gravity-ui/icons";
import {Button, Spinner} from "@heroui/react";
import React, {useState} from "react";

export function LoadingState() {
  const [isLoading, setLoading] = useState(false);

const handlePress = () => {
    setLoading(true);
    setTimeout(() => setLoading(false), 2000);
  };

return (
    <Button isPending={isLoading} onPress={handlePress}>
      {({isPending}) => (
        <>
          {isPending ? <Spinner color="current" size="sm" /> : <Paperclip />}
          {isPending ? "Uploading..." : "Upload File"}
        </>
      )}
    </Button>
  );
}

```

### Sizes

```tsx
import {Button} from "@heroui/react";

export function Sizes() {
  return (
    <div className="flex items-center gap-3">
      <Button size="sm">Small</Button>
      <Button size="md">Medium</Button>
      <Button size="lg">Large</Button>
    </div>
  );
}

```

### Full Width

```tsx
import {Plus} from "@gravity-ui/icons";
import {Button} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-3">
      <Button fullWidth>Primary Button</Button>
      <Button fullWidth>
        <Plus />
        With Icon
      </Button>
    </div>
  );
}

```

### Disabled State

```tsx
import {Button} from "@heroui/react";

export function Disabled() {
  return (
    <div className="flex flex-wrap gap-3">
      <Button isDisabled>Primary</Button>
      <Button isDisabled variant="secondary">
        Secondary
      </Button>
      <Button isDisabled variant="tertiary">
        Tertiary
      </Button>
      <Button isDisabled variant="ghost">
        Ghost
      </Button>
      <Button isDisabled variant="danger">
        Danger
      </Button>
    </div>
  );
}

```

### Social Buttons

```tsx
import {Button} from "@heroui/react";
import {Icon} from "@iconify/react";

export function Social() {
  return (
    <div className="flex w-full max-w-xs flex-col gap-3">
      <Button className="w-full" variant="tertiary">
        <Icon icon="devicon:google" />
        Sign in with Google
      </Button>
      <Button className="w-full" variant="tertiary">
        <Icon icon="mdi:github" />
        Sign in with GitHub
      </Button>
      <Button className="w-full" variant="tertiary">
        <Icon icon="ion:logo-apple" />
        Sign in with Apple
      </Button>
    </div>
  );
}

```

## Related Components

* **Popover**: Displays content in context with a trigger
* **Tooltip**: Contextual information on hover or focus
* **Form**: Form validation and submission handling

## Styling

### Passing Tailwind CSS classes

```tsx
import { Button } from '@heroui/react';

function CustomButton() {
  return (
    <Button className="bg-purple-500 text-white hover:bg-purple-600">
      Purple Button
    </Button>
  );
}

```

### Customizing the component classes

To customize the Button component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .button {
    @apply bg-purple-500 text-white hover:bg-purple-600;
  }

.button--icon-only {
    @apply rounded-lg bg-blue-500;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### Adding custom variants

You can extend HeroUI components by wrapping them and adding your own custom variants.

```tsx
import type {ButtonProps} from "@heroui/react";
import type {VariantProps} from "tailwind-variants";

import {Button, buttonVariants} from "@heroui/react";
import {tv} from "tailwind-variants";

const myButtonVariants = tv({
  base: "text-md font-semibold shadow-md text-shadow-lg data-[pending=true]:opacity-40",
  defaultVariants: {
    radius: "full",
    variant: "primary",
  },
  extend: buttonVariants,
  variants: {
    radius: {
      full: "rounded-full",
      lg: "rounded-lg",
      md: "rounded-md",
      sm: "rounded-sm",
    },
    size: {
      lg: "h-12 px-8",
      md: "h-11 px-6",
      sm: "h-10 px-4",
      xl: "h-13 px-10",
    },
    variant: {
      primary: "text-white dark:bg-white/10 dark:text-white dark:hover:bg-white/15",
    },
  },
});

type MyButtonVariants = VariantProps<typeof myButtonVariants>;
export type MyButtonProps = Omit<ButtonProps, "className"> &
  MyButtonVariants & {className?: string};

function CustomButton({className, radius, variant, ...props}: MyButtonProps) {
  return <Button className={myButtonVariants({className, radius, variant})} {...props} />;
}

export function CustomVariants() {
  return <CustomButton>Custom Button</CustomButton>;
}

```

### CSS Classes

The Button component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button.css)):

#### Base & Size Classes

* `.button` - Base button styles
* `.button--sm` - Small size variant
* `.button--md` - Medium size variant
* `.button--lg` - Large size variant

#### Variant Classes

* `.button--primary`
* `.button--secondary`
* `.button--tertiary`
* `.button--ghost`
* `.button--danger`

#### Modifier Classes

* `.button--icon-only`
* `.button--icon-only.button--sm`
* `.button--icon-only.button--lg`

### Interactive States

The button supports both CSS pseudo-classes and data attributes for flexibility:

* **Hover**: `:hover` or `[data-hovered="true"]`
* **Active/Pressed**: `:active` or `[data-pressed="true"]` (includes scale transform)
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
* **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)
* **Pending**: `[data-pending]` (no pointer events during loading)

## API Reference

### Button Props

| Prop         | Type                                                                | Default     | Description                                                |
| ------------ | ------------------------------------------------------------------- | ----------- | ---------------------------------------------------------- |
| `variant`    | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'`     | `'primary'` | Visual style variant                                       |
| `size`       | `'sm' \| 'md' \| 'lg'`                                              | `'md'`      | Size of the button                                         |
| `fullWidth`  | `boolean`                                                           | `false`     | Whether the button should take full width of its container |
| `isDisabled` | `boolean`                                                           | `false`     | Whether the button is disabled                             |
| `isPending`  | `boolean`                                                           | `false`     | Whether the button is in a loading state                   |
| `isIconOnly` | `boolean`                                                           | `false`     | Whether the button contains only an icon                   |
| `onPress`    | `(e: PressEvent) => void`                                           | -           | Handler called when the button is pressed                  |
| `children`   | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | -           | Button content or render prop                              |

### ButtonRenderProps

When using the render prop pattern, these values are provided:

| Prop             | Type      | Description                                    |
| ---------------- | --------- | ---------------------------------------------- |
| `isPending`      | `boolean` | Whether the button is in a loading state       |
| `isPressed`      | `boolean` | Whether the button is currently pressed        |
| `isHovered`      | `boolean` | Whether the button is hovered                  |
| `isFocused`      | `boolean` | Whether the button is focused                  |
| `isFocusVisible` | `boolean` | Whether the button should show focus indicator |
| `isDisabled`     | `boolean` | Whether the button is disabled                 |

</page>

<page url="/docs/react/components/close-button">
# CloseButton

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/close-button
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(buttons)/close-button.mdx
> Button component for closing dialogs, modals, or dismissing content

## Import

```tsx
import {CloseButton} from "@heroui/react";

```

### Usage

```tsx
import {CloseButton} from "@heroui/react";

export function Default() {
  return <CloseButton />;
}

```

### With Custom Icon

```tsx
import {CircleXmark, Xmark} from "@gravity-ui/icons";
import {CloseButton} from "@heroui/react";

export function WithCustomIcon() {
  return (
    <div className="flex items-center gap-4">
      <div className="flex flex-col items-center gap-2">
        <CloseButton>
          <CircleXmark />
        </CloseButton>
        <span className="text-xs text-muted">Custom Icon</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <CloseButton>
          <Xmark />
        </CloseButton>
        <span className="text-xs text-muted">Alternative Icon</span>
      </div>
    </div>
  );
}

```

### Interactive

```tsx
"use client";

import {CloseButton} from "@heroui/react";
import {useState} from "react";

export function Interactive() {
  const [count, setCount] = useState(0);

return (
    <div className="flex flex-col items-center justify-center gap-4">
      <CloseButton
        aria-label={`Close (clicked ${count} times)`}
        onPress={() => setCount(count + 1)}
      />
      <span className="text-sm text-muted">Clicked: {count} times</span>
    </div>
  );
}

```

## Related Components

* **Alert**: Display important messages and notifications
* **AlertDialog**: Critical confirmations requiring user attention
* **Chip**: Compact elements for tags and filters

## Styling

### Passing Tailwind CSS classes

```tsx
import {CloseButton} from "@heroui/react";

function CustomCloseButton() {
  return <CloseButton className="text-red-600 hover:bg-red-100">Close</CloseButton>;
}

```

### Customizing the component classes

To customize the CloseButton component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .close-button {
    @apply bg-red-100 text-red-800 hover:bg-red-200;
  }

.close-button--custom {
    @apply rounded-full border-2 border-red-300;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The CloseButton component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/close-button.css)):

#### Base Classes

* `.close-button` - Base component styles

#### Variant Classes

* `.close-button--default` - Default variant

### Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

* **Hover**: `:hover` or `[data-hovered="true"]`
* **Active/Pressed**: `:active` or `[data-pressed="true"]`
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
* **Disabled**: `:disabled` or `[aria-disabled="true"]`

## API Reference

### CloseButton Props

| Prop         | Type                    | Default         | Description                                 |
| ------------ | ----------------------- | --------------- | ------------------------------------------- |
| `variant`    | `"default"`             | `"default"`     | Visual variant of the button                |
| `children`   | `ReactNode \| function` | `<CloseIcon />` | Content to display (defaults to close icon) |
| `onPress`    | `() => void`            | -               | Handler called when the button is pressed   |
| `isDisabled` | `boolean`               | `false`         | Whether the button is disabled              |

### React Aria Button Props

CloseButton extends all React Aria Button props. Common props include:

| Prop               | Type     | Description                             |
| ------------------ | -------- | --------------------------------------- |
| `aria-label`       | `string` | Accessible label for screen readers     |
| `aria-labelledby`  | `string` | ID of element that labels the button    |
| `aria-describedby` | `string` | ID of element that describes the button |

### RenderProps

When using the render prop pattern, these values are provided:

| Prop         | Type      | Description                    |
| ------------ | --------- | ------------------------------ |
| `isHovered`  | `boolean` | Whether the button is hovered  |
| `isPressed`  | `boolean` | Whether the button is pressed  |
| `isFocused`  | `boolean` | Whether the button is focused  |
| `isDisabled` | `boolean` | Whether the button is disabled |

</page>

<page url="/docs/react/components/dropdown">
# Dropdown

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/dropdown
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(collections)/dropdown.mdx
> A dropdown displays a list of actions or options that a user can choose

## Import

```tsx
import { Dropdown } from '@heroui/react';

```

### Usage

```tsx
"use client";

import {Button, Dropdown, Label} from "@heroui/react";

```

### Anatomy

Import the Dropdown component and access all parts using dot notation.

```tsx
import { Dropdown, Button, Label, Description, Header, Kbd, Separator } from '@heroui/react';

export default () => (
  <Dropdown>
    <Dropdown.Trigger>
      <Button />
    </Dropdown.Trigger>
    <Dropdown.Popover>
      <Dropdown.Menu>
        <Dropdown.Item>
          <Label />
          <Description />
          <Kbd slot="keyboard" />
          <Dropdown.ItemIndicator />
        </Dropdown.Item>
        <Separator />
        <Dropdown.Section>
          <Header />
          <Dropdown.Item />
        </Dropdown.Section>
        <Dropdown.SubmenuTrigger>
          <Dropdown.Item>
            <Label />
            <Dropdown.SubmenuIndicator />
          </Dropdown.Item>
          <Dropdown.Popover>
            <Dropdown.Menu>
              <Dropdown.Item />
            </Dropdown.Menu>
          </Dropdown.Popover>
        </Dropdown.SubmenuTrigger>
      </Dropdown.Menu>
    </Dropdown.Popover>
  </Dropdown>
)

```

### With Single Selection

```tsx
"use client";

import type {Selection} from "@heroui/react";

import {Button, Dropdown, Header, Label} from "@heroui/react";
import {useState} from "react";

export function WithSingleSelection() {
  const [selected, setSelected] = useState<Selection>(new Set(["apple"]));

return (
    <Dropdown>
      <Button aria-label="Menu" variant="secondary">
        Fruit
      </Button>
      <Dropdown.Popover className="min-w-[256px]">
        <Dropdown.Menu
          selectedKeys={selected}
          selectionMode="single"
          onSelectionChange={setSelected}
        >
          <Dropdown.Section>
            <Header>Select a fruit</Header>
            <Dropdown.Item id="apple" textValue="Apple">
              <Dropdown.ItemIndicator />
              <Label>Apple</Label>
            </Dropdown.Item>
            <Dropdown.Item id="banana" textValue="Banana">
              <Dropdown.ItemIndicator />
              <Label>Banana</Label>
            </Dropdown.Item>
            <Dropdown.Item id="cherry" textValue="Cherry">
              <Dropdown.ItemIndicator />
              <Label>Cherry</Label>
            </Dropdown.Item>
          </Dropdown.Section>
          <Dropdown.Item id="orange" textValue="Orange">
            <Dropdown.ItemIndicator />
            <Label>Orange</Label>
          </Dropdown.Item>
          <Dropdown.Item id="pear" textValue="Pear">
            <Dropdown.ItemIndicator />
            <Label>Pear</Label>
          </Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### Single With Custom Indicator

```tsx
"use client";

import type {Selection} from "@heroui/react";

import {Button, Dropdown, Header, Label} from "@heroui/react";
import {useState} from "react";

export function SingleWithCustomIndicator() {
  const [selected, setSelected] = useState<Selection>(new Set(["apple"]));

const CustomCheckmarkIcon = (
    <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
      <path
        className="text-accent"
        clipRule="evenodd"
        d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14m3.1-8.55a.75.75 0 1 0-1.2-.9L7.419 8.858L6.03 7.47a.75.75 0 0 0-1.06 1.06l2 2a.75.75 0 0 0 1.13-.08z"
        fill="currentColor"
        fillRule="evenodd"
      />
    </svg>
  );

return (
    <Dropdown>
      <Button aria-label="Menu" variant="secondary">
        Fruits
      </Button>
      <Dropdown.Popover className="min-w-[256px]">
        <Dropdown.Menu
          selectedKeys={selected}
          selectionMode="single"
          onSelectionChange={setSelected}
        >
          <Dropdown.Section>
            <Header>Select a fruit</Header>
            <Dropdown.Item id="apple" textValue="Apple">
              <Dropdown.ItemIndicator>
                {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
              </Dropdown.ItemIndicator>
              <Label>Apple</Label>
            </Dropdown.Item>
            <Dropdown.Item id="banana" textValue="Banana">
              <Dropdown.ItemIndicator>
                {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
              </Dropdown.ItemIndicator>
              <Label>Banana</Label>
            </Dropdown.Item>
            <Dropdown.Item id="cherry" textValue="Cherry">
              <Dropdown.ItemIndicator>
                {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
              </Dropdown.ItemIndicator>
              <Label>Cherry</Label>
            </Dropdown.Item>
          </Dropdown.Section>
          <Dropdown.Item id="orange" textValue="Orange">
            <Dropdown.ItemIndicator>
              {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
            </Dropdown.ItemIndicator>
            <Label>Orange</Label>
          </Dropdown.Item>
          <Dropdown.Item id="pear" textValue="Pear">
            <Dropdown.ItemIndicator>
              {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)}
            </Dropdown.ItemIndicator>
            <Label>Pear</Label>
          </Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### With Multiple Selection

```tsx
"use client";

import type {Selection} from "@heroui/react";

import {Button, Dropdown, Header, Label} from "@heroui/react";
import {useState} from "react";

export function WithMultipleSelection() {
  const [selected, setSelected] = useState<Selection>(new Set(["apple"]));

return (
    <Dropdown>
      <Button aria-label="Menu" variant="secondary">
        Preferred Fruits
      </Button>
      <Dropdown.Popover className="min-w-[256px]">
        <Dropdown.Menu
          selectedKeys={selected}
          selectionMode="multiple"
          onSelectionChange={setSelected}
        >
          <Dropdown.Section>
            <Header>Select a fruit</Header>
            <Dropdown.Item id="apple" textValue="Apple">
              <Dropdown.ItemIndicator />
              <Label>Apple</Label>
            </Dropdown.Item>
            <Dropdown.Item id="banana" textValue="Banana">
              <Dropdown.ItemIndicator />
              <Label>Banana</Label>
            </Dropdown.Item>
            <Dropdown.Item id="cherry" textValue="Cherry">
              <Dropdown.ItemIndicator />
              <Label>Cherry</Label>
            </Dropdown.Item>
          </Dropdown.Section>
          <Dropdown.Item id="orange" textValue="Orange">
            <Dropdown.ItemIndicator />
            <Label>Orange</Label>
          </Dropdown.Item>
          <Dropdown.Item id="pear" textValue="Pear">
            <Dropdown.ItemIndicator />
            <Label>Pear</Label>
          </Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### With Section Level Selection

```tsx
"use client";

import type {Selection} from "@heroui/react";

import {Button, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react";
import {useState} from "react";

export function WithSectionLevelSelection() {
  const [textStyles, setTextStyles] = useState<Selection>(new Set(["bold", "italic"]));
  const [textAlignment, setTextAlignment] = useState<Selection>(new Set(["left"]));

return (
    <Dropdown>
      <Button aria-label="Menu" variant="secondary">
        Styles
      </Button>
      <Dropdown.Popover className="min-w-[256px]">
        <Dropdown.Menu>
          <Dropdown.Section>
            <Header>Actions</Header>
            <Dropdown.Item id="cut" textValue="Cut">
              <Label>Cut</Label>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Content>X</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
            <Dropdown.Item id="copy" textValue="Copy">
              <Label>Copy</Label>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Content>C</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
            <Dropdown.Item id="paste" textValue="Paste">
              <Label>Paste</Label>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Content>U</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
          </Dropdown.Section>
          <Separator />
          <Dropdown.Section
            selectedKeys={textStyles}
            selectionMode="multiple"
            onSelectionChange={setTextStyles}
          >
            <Header>Text Style</Header>
            <Dropdown.Item id="bold" textValue="Bold">
              <Dropdown.ItemIndicator />
              <Label>Bold</Label>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Content>B</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
            <Dropdown.Item id="italic" textValue="Italic">
              <Dropdown.ItemIndicator />
              <Label>Italic</Label>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Content>I</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
            <Dropdown.Item id="underline" textValue="Underline">
              <Dropdown.ItemIndicator />
              <Label>Underline</Label>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Content>U</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
          </Dropdown.Section>
          <Separator />
          <Dropdown.Section
            selectedKeys={textAlignment}
            selectionMode="single"
            onSelectionChange={setTextAlignment}
          >
            <Header>Text Alignment</Header>
            <Dropdown.Item id="left" textValue="Left">
              <Dropdown.ItemIndicator type="dot" />
              <Label>Left</Label>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="alt" />
                <Kbd.Content>A</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
            <Dropdown.Item id="center" textValue="Center">
              <Dropdown.ItemIndicator type="dot" />
              <Label>Center</Label>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="alt" />
                <Kbd.Content>H</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
            <Dropdown.Item id="right" textValue="Right">
              <Dropdown.ItemIndicator type="dot" />
              <Label>Right</Label>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="alt" />
                <Kbd.Content>D</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
          </Dropdown.Section>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### With Keyboard Shortcuts

```tsx
"use client";

import {Button, Dropdown, Kbd, Label} from "@heroui/react";

export function WithKeyboardShortcuts() {
  return (
    <Dropdown>
      <Button aria-label="Menu" variant="secondary">
        Actions
      </Button>
      <Dropdown.Popover>
        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
          <Dropdown.Item id="new" textValue="New">
            <Label>New</Label>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>N</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
          <Dropdown.Item id="open" textValue="Open">
            <Label>Open</Label>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>O</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
          <Dropdown.Item id="save" textValue="Save">
            <Label>Save</Label>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>S</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
          <Dropdown.Item id="delete" textValue="Delete" variant="danger">
            <Label>Delete</Label>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Abbr keyValue="shift" />
              <Kbd.Content>D</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### With Icons

```tsx
"use client";

import {FloppyDisk, FolderOpen, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Button, Dropdown, Kbd, Label} from "@heroui/react";

export function WithIcons() {
  return (
    <Dropdown>
      <Button aria-label="Menu" variant="secondary">
        Actions
      </Button>
      <Dropdown.Popover>
        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
          <Dropdown.Item id="new-file" textValue="New file">
            <SquarePlus className="size-4 shrink-0 text-muted" />
            <Label>New file</Label>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>N</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
          <Dropdown.Item id="open-file" textValue="Open file">
            <FolderOpen className="size-4 shrink-0 text-muted" />
            <Label>Open file</Label>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>O</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
          <Dropdown.Item id="save-file" textValue="Save file">
            <FloppyDisk className="size-4 shrink-0 text-muted" />
            <Label>Save file</Label>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>S</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
          <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
            <TrashBin className="size-4 shrink-0 text-danger" />
            <Label>Delete file</Label>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Abbr keyValue="shift" />
              <Kbd.Content>D</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### Long Press Trigger

```tsx
import {Button, Dropdown, Label} from "@heroui/react";

export function LongPressTrigger() {
  return (
    <Dropdown trigger="longPress">
      <Button aria-label="Menu" variant="secondary">
        Long Press
      </Button>
      <Dropdown.Popover>
        <Dropdown.Menu>
          <Dropdown.Item id="new-file" textValue="New file">
            <Label>New file</Label>
          </Dropdown.Item>
          <Dropdown.Item id="open-file" textValue="Open file">
            <Label>Open file</Label>
          </Dropdown.Item>
          <Dropdown.Item id="save-file" textValue="Save file">
            <Label>Save file</Label>
          </Dropdown.Item>
          <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
            <Label>Delete file</Label>
          </Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### With Descriptions

```tsx
"use client";

import {FloppyDisk, FolderOpen, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Button, Description, Dropdown, Kbd, Label} from "@heroui/react";

export function WithDescriptions() {
  return (
    <Dropdown>
      <Button aria-label="Menu" variant="secondary">
        Actions
      </Button>
      <Dropdown.Popover>
        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
          <Dropdown.Item id="new-file" textValue="New file">
            <div className="flex h-8 items-start justify-center pt-px">
              <SquarePlus className="size-4 shrink-0 text-muted" />
            </div>
            <div className="flex flex-col">
              <Label>New file</Label>
              <Description>Create a new file</Description>
            </div>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>N</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
          <Dropdown.Item id="open-file" textValue="Open file">
            <div className="flex h-8 items-start justify-center pt-px">
              <FolderOpen className="size-4 shrink-0 text-muted" />
            </div>
            <div className="flex flex-col">
              <Label>Open file</Label>
              <Description>Open an existing file</Description>
            </div>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>O</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
          <Dropdown.Item id="save-file" textValue="Save file">
            <div className="flex h-8 items-start justify-center pt-px">
              <FloppyDisk className="size-4 shrink-0 text-muted" />
            </div>
            <div className="flex flex-col">
              <Label>Save file</Label>
              <Description>Save the current file</Description>
            </div>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>S</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
          <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
            <div className="flex h-8 items-start justify-center pt-px">
              <TrashBin className="size-4 shrink-0 text-danger" />
            </div>
            <div className="flex flex-col">
              <Label>Delete file</Label>
              <Description>Move to trash</Description>
            </div>
            <Kbd className="ms-auto" slot="keyboard" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Abbr keyValue="shift" />
              <Kbd.Content>D</Kbd.Content>
            </Kbd>
          </Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### With Sections

```tsx
"use client";

import {EllipsisVertical, Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Description, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react";

export function WithSections() {
  return (
    <Dropdown>
      <Dropdown.Trigger
        aria-label="Menu"
        className="button button-md button--secondary button--icon-only data-[focus-visible=true]:status-focused"
      >
        <EllipsisVertical className="outline-none" />
      </Dropdown.Trigger>
      <Dropdown.Popover>
        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
          <Dropdown.Section>
            <Header>Actions</Header>
            <Dropdown.Item id="new-file" textValue="New file">
              <div className="flex h-8 items-start justify-center pt-px">
                <SquarePlus className="size-4 shrink-0 text-muted" />
              </div>
              <div className="flex flex-col">
                <Label>New file</Label>
                <Description>Create a new file</Description>
              </div>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Content>N</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
            <Dropdown.Item id="edit-file" textValue="Edit file">
              <div className="flex h-8 items-start justify-center pt-px">
                <Pencil className="size-4 shrink-0 text-muted" />
              </div>
              <div className="flex flex-col">
                <Label>Edit file</Label>
                <Description>Make changes</Description>
              </div>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Content>E</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
          </Dropdown.Section>
          <Separator />
          <Dropdown.Section>
            <Header>Danger zone</Header>
            <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
              <div className="flex h-8 items-start justify-center pt-px">
                <TrashBin className="size-4 shrink-0 text-danger" />
              </div>
              <div className="flex flex-col">
                <Label>Delete file</Label>
                <Description>Move to trash</Description>
              </div>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Abbr keyValue="shift" />
                <Kbd.Content>D</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
          </Dropdown.Section>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### With Disabled Items

```tsx
"use client";

import {Bars, Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Button, Description, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react";

export function WithDisabledItems() {
  return (
    <Dropdown>
      <Button isIconOnly aria-label="Menu" variant="secondary">
        <Bars className="outline-none" />
      </Button>
      <Dropdown.Popover className="min-w-[220px]">
        <Dropdown.Menu
          disabledKeys={["delete-file"]}
          onAction={(key) => console.log(`Selected: ${key}`)}
        >
          <Dropdown.Section>
            <Header>Actions</Header>
            <Dropdown.Item id="new-file" textValue="New file">
              <div className="flex h-8 items-start justify-center pt-px">
                <SquarePlus className="size-4 shrink-0 text-muted" />
              </div>
              <div className="flex flex-col">
                <Label>New file</Label>
                <Description>Create a new file</Description>
              </div>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Content>N</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
            <Dropdown.Item id="edit-file" textValue="Edit file">
              <div className="flex h-8 items-start justify-center pt-px">
                <Pencil className="size-4 shrink-0 text-muted" />
              </div>
              <div className="flex flex-col">
                <Label>Edit file</Label>
                <Description>Make changes</Description>
              </div>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Content>E</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
          </Dropdown.Section>
          <Separator />
          <Dropdown.Section>
            <Header>Danger zone</Header>
            <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
              <div className="flex h-8 items-start justify-center pt-px">
                <TrashBin className="size-4 shrink-0 text-danger" />
              </div>
              <div className="flex flex-col">
                <Label>Delete file</Label>
                <Description>Move to trash</Description>
              </div>
              <Kbd className="ms-auto" slot="keyboard" variant="light">
                <Kbd.Abbr keyValue="command" />
                <Kbd.Abbr keyValue="shift" />
                <Kbd.Content>D</Kbd.Content>
              </Kbd>
            </Dropdown.Item>
          </Dropdown.Section>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### With Submenus

```tsx
"use client";

import {Button, Dropdown, Label} from "@heroui/react";

export function WithSubmenus() {
  return (
    <Dropdown>
      <Button aria-label="Menu" variant="secondary">
        Share
      </Button>
      <Dropdown.Popover>
        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
          <Dropdown.Item id="copy-link" textValue="Copy Link">
            <Label>Copy Link</Label>
          </Dropdown.Item>
          <Dropdown.Item id="facebook" textValue="Facebook">
            <Label>Facebook</Label>
          </Dropdown.Item>
          <Dropdown.Item id="twitter" textValue="Twitter">
            <Label>X / Twitter</Label>
          </Dropdown.Item>
          <Dropdown.SubmenuTrigger>
            <Dropdown.Item id="share" textValue="Share">
              <Label>Other</Label>
              <Dropdown.SubmenuIndicator />
            </Dropdown.Item>
            <Dropdown.Popover>
              <Dropdown.Menu>
                <Dropdown.Item id="whatsapp" textValue="WhatsApp">
                  <Label>WhatsApp</Label>
                </Dropdown.Item>
                <Dropdown.Item id="telegram" textValue="Telegram">
                  <Label>Telegram</Label>
                </Dropdown.Item>
                <Dropdown.Item id="discord" textValue="Discord">
                  <Label>Discord</Label>
                </Dropdown.Item>
                <Dropdown.SubmenuTrigger>
                  <Dropdown.Item id="email" textValue="Email">
                    <Label>Email</Label>
                    <Dropdown.SubmenuIndicator />
                  </Dropdown.Item>
                  <Dropdown.Popover>
                    <Dropdown.Menu>
                      <Dropdown.Item id="work" textValue="Work email">
                        <Label>Work email</Label>
                      </Dropdown.Item>
                      <Dropdown.Item id="personal" textValue="Personal email">
                        <Label>Personal email</Label>
                      </Dropdown.Item>
                    </Dropdown.Menu>
                  </Dropdown.Popover>
                </Dropdown.SubmenuTrigger>
              </Dropdown.Menu>
            </Dropdown.Popover>
          </Dropdown.SubmenuTrigger>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### With Custom Submenu Indicator

```tsx
"use client";

import {ArrowRight} from "@gravity-ui/icons";
import {Button, Dropdown, Label} from "@heroui/react";

export function WithCustomSubmenuIndicator() {
  return (
    <Dropdown>
      <Button aria-label="Menu" variant="secondary">
        Share
      </Button>
      <Dropdown.Popover>
        <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}>
          <Dropdown.Item id="copy-link" textValue="Copy Link">
            <Label>Copy Link</Label>
          </Dropdown.Item>
          <Dropdown.Item id="facebook" textValue="Facebook">
            <Label>Facebook</Label>
          </Dropdown.Item>
          <Dropdown.SubmenuTrigger>
            <Dropdown.Item id="share" textValue="Share">
              <Label>More options</Label>
              <Dropdown.SubmenuIndicator>
                <ArrowRight className="size-3.5 text-muted" />
              </Dropdown.SubmenuIndicator>
            </Dropdown.Item>
            <Dropdown.Popover>
              <Dropdown.Menu>
                <Dropdown.Item id="whatsapp" textValue="WhatsApp">
                  <Label>WhatsApp</Label>
                </Dropdown.Item>
                <Dropdown.Item id="telegram" textValue="Telegram">
                  <Label>Telegram</Label>
                </Dropdown.Item>
                <Dropdown.SubmenuTrigger>
                  <Dropdown.Item id="email" textValue="Email">
                    <Label>Email</Label>
                    <Dropdown.SubmenuIndicator>
                      <svg
                        className="size-3.5 text-muted"
                        fill="none"
                        stroke="currentColor"
                        strokeLinecap="round"
                        strokeLinejoin="round"
                        strokeWidth="2"
                        viewBox="0 0 24 24"
                      >
                        <path d="M9 18l6-6-6-6" />
                      </svg>
                    </Dropdown.SubmenuIndicator>
                  </Dropdown.Item>
                  <Dropdown.Popover>
                    <Dropdown.Menu>
                      <Dropdown.Item id="work" textValue="Work email">
                        <Label>Work email</Label>
                      </Dropdown.Item>
                      <Dropdown.Item id="personal" textValue="Personal email">
                        <Label>Personal email</Label>
                      </Dropdown.Item>
                    </Dropdown.Menu>
                  </Dropdown.Popover>
                </Dropdown.SubmenuTrigger>
                <Dropdown.Item id="discord" textValue="Discord">
                  <Label>Discord</Label>
                </Dropdown.Item>
              </Dropdown.Menu>
            </Dropdown.Popover>
          </Dropdown.SubmenuTrigger>
          <Dropdown.SubmenuTrigger>
            <Dropdown.Item id="other" textValue="Other">
              <Label>Other (default indicator)</Label>
              <Dropdown.SubmenuIndicator />
            </Dropdown.Item>
            <Dropdown.Popover>
              <Dropdown.Menu>
                <Dropdown.Item id="sms" textValue="SMS">
                  <Label>SMS</Label>
                </Dropdown.Item>
              </Dropdown.Menu>
            </Dropdown.Popover>
          </Dropdown.SubmenuTrigger>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### Controlled

```tsx
"use client";

import type {Selection} from "@heroui/react";

import {Button, Dropdown, Label} from "@heroui/react";
import {useState} from "react";

export function Controlled() {
  const [selected, setSelected] = useState<Selection>(new Set(["bold"]));

const selectedItems = Array.from(selected);

return (
    <div className="flex min-w-sm flex-col items-center justify-center gap-4">
      <p className="text-sm text-muted">
        Selected: {selectedItems.length > 0 ? selectedItems.join(", ") : "None"}
      </p>
      <Dropdown>
        <Button aria-label="Menu" variant="secondary">
          Actions
        </Button>
        <Dropdown.Popover>
          <Dropdown.Menu
            selectedKeys={selected}
            selectionMode="multiple"
            onSelectionChange={setSelected}
          >
            <Dropdown.Item id="bold" textValue="Bold">
              <Label>Bold</Label>
              <Dropdown.ItemIndicator />
            </Dropdown.Item>
            <Dropdown.Item id="italic" textValue="Italic">
              <Label>Italic</Label>
              <Dropdown.ItemIndicator />
            </Dropdown.Item>
            <Dropdown.Item id="underline" textValue="Underline">
              <Label>Underline</Label>
              <Dropdown.ItemIndicator />
            </Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown.Popover>
      </Dropdown>
    </div>
  );
}

```

### Controlled Open State

```tsx
"use client";

import {Button, Dropdown, Label} from "@heroui/react";
import {useState} from "react";

export function ControlledOpenState() {
  const [open, setOpen] = useState(false);

return (
    <div className="flex min-w-sm flex-col items-center justify-center gap-4">
      <p className="text-sm text-muted">
        Dropdown is: <strong>{open ? "open" : "closed"}</strong>
      </p>
      <Dropdown isOpen={open} onOpenChange={setOpen}>
        <Button aria-label="Menu" variant="secondary">
          Actions
        </Button>
        <Dropdown.Popover>
          <Dropdown.Menu>
            <Dropdown.Item id="new-file" textValue="New file">
              <Label>New file</Label>
            </Dropdown.Item>
            <Dropdown.Item id="open-file" textValue="Open file">
              <Label>Open file</Label>
            </Dropdown.Item>
            <Dropdown.Item id="save-file" textValue="Save file">
              <Label>Save file</Label>
            </Dropdown.Item>
            <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
              <Label>Delete file</Label>
            </Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown.Popover>
      </Dropdown>
    </div>
  );
}

```

### Custom Trigger

```tsx
import {ArrowRightFromSquare, Gear, Persons} from "@gravity-ui/icons";
import {Avatar, Dropdown, Label} from "@heroui/react";

export function CustomTrigger() {
  return (
    <Dropdown>
      <Dropdown.Trigger className="rounded-full">
        <Avatar>
          <Avatar.Image
            alt="Junior Garcia"
            src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"
          />
          <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
        </Avatar>
      </Dropdown.Trigger>
      <Dropdown.Popover>
        <div className="px-3 pt-3 pb-1">
          <div className="flex items-center gap-2">
            <Avatar size="sm">
              <Avatar.Image
                alt="Jane"
                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"
              />
              <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback>
            </Avatar>
            <div className="flex flex-col gap-0">
              <p className="text-sm leading-5 font-medium">Jane Doe</p>
              <p className="text-xs leading-none text-muted">jane@example.com</p>
            </div>
          </div>
        </div>
        <Dropdown.Menu>
          <Dropdown.Item id="dashboard" textValue="Dashboard">
            <Label>Dashboard</Label>
          </Dropdown.Item>
          <Dropdown.Item id="profile" textValue="Profile">
            <Label>Profile</Label>
          </Dropdown.Item>
          <Dropdown.Item id="settings" textValue="Settings">
            <div className="flex w-full items-center justify-between gap-2">
              <Label>Settings</Label>
              <Gear className="size-3.5 text-muted" />
            </div>
          </Dropdown.Item>
          <Dropdown.Item id="new-project" textValue="New project">
            <div className="flex w-full items-center justify-between gap-2">
              <Label>Create Team</Label>
              <Persons className="size-3.5 text-muted" />
            </div>
          </Dropdown.Item>
          <Dropdown.Item id="logout" textValue="Logout" variant="danger">
            <div className="flex w-full items-center justify-between gap-2">
              <Label>Log Out</Label>
              <ArrowRightFromSquare className="size-3.5 text-danger" />
            </div>
          </Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

## Related Components

* **Button**: Allows a user to perform an action
* **Popover**: Displays content in context with a trigger
* **Separator**: Visual divider between content

## Styling

### Passing Tailwind CSS classes

```tsx
import { Dropdown, Button } from '@heroui/react';

function CustomDropdown() {
  return (
    <Dropdown>
      <Dropdown.Trigger className="rounded-lg border p-2 bg-surface">
        <Button>Actions</Button>
      </Dropdown.Trigger>
      <Dropdown.Popover className="min-w-[200px]">
        <Dropdown.Menu>
          <Dropdown.Item id="item-1" textValue="Item 1" className="hover:bg-surface-secondary">
            Item 1
          </Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### Customizing the component classes

To customize the Dropdown component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .dropdown {
    @apply flex flex-col gap-1;
  }

.dropdown__trigger {
    @apply outline-none;
  }

.dropdown__popover {
    @apply rounded-lg border border-border bg-overlay p-2;
  }

.dropdown__menu {
    @apply flex flex-col gap-1;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The Dropdown component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/dropdown.css)):

#### Base Classes

* `.dropdown` - Base dropdown container
* `.dropdown__trigger` - The button or element that triggers the dropdown
* `.dropdown__popover` - The popover container
* `.dropdown__menu` - The menu container inside the popover

#### State Classes

* `.dropdown__trigger[data-focus-visible="true"]` - Focused trigger state
* `.dropdown__trigger[data-disabled="true"]` - Disabled trigger state
* `.dropdown__trigger[data-pressed="true"]` - Pressed trigger state
* `.dropdown__popover[data-entering]` - Entering animation state
* `.dropdown__popover[data-exiting]` - Exiting animation state
* `.dropdown__menu[data-selection-mode="single"]` - Single selection mode
* `.dropdown__menu[data-selection-mode="multiple"]` - Multiple selection mode

### Menu Component Classes

The Dropdown component uses Menu, MenuItem, and MenuSection as base components. These classes are also available for customization:

#### Menu Classes

* `.menu` - Base menu container ([menu.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu.css))
  * `[data-slot="separator"]` - Separator elements within the menu

#### MenuItem Classes

* `.menu-item` - Base menu item container ([menu-item.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-item.css))
* `.menu-item__indicator` - Selection indicator (checkmark or dot)
  * `[data-slot="menu-item-indicator--checkmark"]` - Checkmark indicator SVG
  * `[data-slot="menu-item-indicator--dot"]` - Dot indicator SVG
* `.menu-item__indicator--submenu` - Submenu indicator (chevron)
* `.menu-item--default` - Default variant styling
* `.menu-item--danger` - Danger variant styling

#### MenuItem State Classes

* `.menu-item[data-focus-visible="true"]` - Focused item state (keyboard focus)
* `.menu-item[data-focus="true"]` - Focused item state
* `.menu-item[data-pressed]` - Pressed item state
* `.menu-item[data-hovered]` - Hovered item state
* `.menu-item[data-selected="true"]` - Selected item state
* `.menu-item[data-disabled]` - Disabled item state
* `.menu-item[data-has-submenu="true"]` - Item with submenu
* `.menu-item[data-selection-mode="single"]` - Single selection mode
* `.menu-item[data-selection-mode="multiple"]` - Multiple selection mode
* `.menu-item[aria-checked="true"]` - Checked item (ARIA)
* `.menu-item[aria-selected="true"]` - Selected item (ARIA)

#### MenuSection Classes

* `.menu-section` - Base menu section container ([menu-section.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-section.css))

### Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

* **Hover**: `:hover` or `[data-hovered="true"]` on trigger and items
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger and items
* **Disabled**: `:disabled` or `[data-disabled="true"]` on trigger and items
* **Pressed**: `:active` or `[data-pressed="true"]` on trigger and items
* **Selected**: `[data-selected="true"]` or `[aria-selected="true"]` on items

## API Reference

### Dropdown Props

| Prop           | Type                        | Default   | Description                                            |
| -------------- | --------------------------- | --------- | ------------------------------------------------------ |
| `isOpen`       | `boolean`                   | -         | Sets the open state of the menu (controlled)           |
| `defaultOpen`  | `boolean`                   | -         | Sets the default open state of the menu (uncontrolled) |
| `onOpenChange` | `(isOpen: boolean) => void` | -         | Handler called when the open state changes             |
| `trigger`      | `"press" \| "longPress"`    | `"press"` | The type of interaction that triggers the menu         |
| `className`    | `string`                    | -         | Additional CSS classes                                 |
| `children`     | `ReactNode`                 | -         | Dropdown content                                       |

### Dropdown.Trigger Props

| Prop        | Type                          | Default | Description                        |
| ----------- | ----------------------------- | ------- | ---------------------------------- |
| `className` | `string`                      | -       | Additional CSS classes             |
| `children`  | `ReactNode \| RenderFunction` | -       | Trigger content or render function |

All [Button](https://react-spectrum.adobe.com/react-aria/Button.html) props are also supported when using a Button as the trigger.

### Dropdown.Popover Props

| Prop        | Type                                                                                                                                                                                                                                                                                                                     | Default    | Description                                      |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------------------------------------ |
| `placement` | `"bottom" \| "bottom left" \| "bottom right" \| "bottom start" \| "bottom end" \| "top" \| "top left" \| "top right" \| "top start" \| "top end" \| "left" \| "left top" \| "left bottom" \| "start" \| "start top" \| "start bottom" \| "right" \| "right top" \| "right bottom" \| "end" \| "end top" \| "end bottom"` | `"bottom"` | Placement of the popover relative to the trigger |
| `className` | `string`                                                                                                                                                                                                                                                                                                                 | -          | Additional CSS classes                           |
| `children`  | `ReactNode`                                                                                                                                                                                                                                                                                                              | -          | Content children                                 |

All [Popover](https://react-spectrum.adobe.com/react-aria/Popover.html) props are also supported.

### Dropdown.Menu Props

| Prop                  | Type                               | Default  | Description                                     |
| --------------------- | ---------------------------------- | -------- | ----------------------------------------------- |
| `selectionMode`       | `"single" \| "multiple" \| "none"` | `"none"` | Whether single or multiple selection is enabled |
| `selectedKeys`        | `Iterable<Key>`                    | -        | The currently selected keys (controlled)        |
| `defaultSelectedKeys` | `Iterable<Key>`                    | -        | The initial selected keys (uncontrolled)        |
| `onSelectionChange`   | `(keys: Selection) => void`        | -        | Handler called when the selection changes       |
| `disabledKeys`        | `Iterable<Key>`                    | -        | Keys of disabled items                          |
| `onAction`            | `(key: Key) => void`               | -        | Handler called when an item is activated        |
| `className`           | `string`                           | -        | Additional CSS classes                          |
| `children`            | `ReactNode`                        | -        | Menu content                                    |

All [Menu](https://react-spectrum.adobe.com/react-aria/Menu.html#menu) props are also supported.

### Dropdown.Section Props

| Prop                  | Type                        | Default | Description                                  |
| --------------------- | --------------------------- | ------- | -------------------------------------------- |
| `selectionMode`       | `"single" \| "multiple"`    | -       | Selection mode for items within this section |
| `selectedKeys`        | `Iterable<Key>`             | -       | The currently selected keys (controlled)     |
| `defaultSelectedKeys` | `Iterable<Key>`             | -       | The initial selected keys (uncontrolled)     |
| `onSelectionChange`   | `(keys: Selection) => void` | -       | Handler called when the selection changes    |
| `disabledKeys`        | `Iterable<Key>`             | -       | Keys of disabled items                       |
| `className`           | `string`                    | -       | Additional CSS classes                       |
| `children`            | `ReactNode`                 | -       | Section content                              |

All [MenuSection](https://react-spectrum.adobe.com/react-aria/Menu.html#menusection) props are also supported.

### Dropdown.Item Props

| Prop        | Type                          | Default     | Description                            |
| ----------- | ----------------------------- | ----------- | -------------------------------------- |
| `id`        | `Key`                         | -           | Unique identifier for the item         |
| `textValue` | `string`                      | -           | Text content of the item for typeahead |
| `variant`   | `"default" \| "danger"`       | `"default"` | Visual variant of the item             |
| `className` | `string`                      | -           | Additional CSS classes                 |
| `children`  | `ReactNode \| RenderFunction` | -           | Item content or render function        |

All [MenuItem](https://react-spectrum.adobe.com/react-aria/Menu.html#menuitem) props are also supported.

### Dropdown.ItemIndicator Props

| Prop        | Type                          | Default       | Description                                 |
| ----------- | ----------------------------- | ------------- | ------------------------------------------- |
| `type`      | `"checkmark" \| "dot"`        | `"checkmark"` | Type of indicator to display                |
| `className` | `string`                      | -             | Additional CSS classes                      |
| `children`  | `ReactNode \| RenderFunction` | -             | Custom indicator content or render function |

When using a render function, these values are provided:

| Prop              | Type      | Description                                   |
| ----------------- | --------- | --------------------------------------------- |
| `isSelected`      | `boolean` | Whether the item is selected                  |
| `isIndeterminate` | `boolean` | Whether the item is in an indeterminate state |

### Dropdown.SubmenuIndicator Props

| Prop        | Type        | Default | Description              |
| ----------- | ----------- | ------- | ------------------------ |
| `className` | `string`    | -       | Additional CSS classes   |
| `children`  | `ReactNode` | -       | Custom indicator content |

### Dropdown.SubmenuTrigger Props

| Prop        | Type        | Default | Description             |
| ----------- | ----------- | ------- | ----------------------- |
| `className` | `string`    | -       | Additional CSS classes  |
| `children`  | `ReactNode` | -       | Submenu trigger content |

All [SubmenuTrigger](https://react-spectrum.adobe.com/react-aria/Menu.html#submenutrigger) props are also supported.

### RenderProps

When using render functions with Dropdown.Item, these values are provided:

| Prop         | Type      | Description                       |
| ------------ | --------- | --------------------------------- |
| `isSelected` | `boolean` | Whether the item is selected      |
| `isFocused`  | `boolean` | Whether the item is focused       |
| `isDisabled` | `boolean` | Whether the item is disabled      |
| `isPressed`  | `boolean` | Whether the item is being pressed |

## Examples

### Basic Usage

```tsx
import { Dropdown, Button, Label } from '@heroui/react';

<Dropdown>
  <Button aria-label="Menu" variant="secondary">
    Actions
  </Button>
  <Dropdown.Popover>
    <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
      <Dropdown.Item id="new-file" textValue="New file">
        <Label>New file</Label>
      </Dropdown.Item>
      <Dropdown.Item id="open-file" textValue="Open file">
        <Label>Open file</Label>
      </Dropdown.Item>
      <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
        <Label>Delete file</Label>
      </Dropdown.Item>
    </Dropdown.Menu>
  </Dropdown.Popover>
</Dropdown>

```

### With Sections

```tsx
import { Dropdown, Button, Label, Header, Separator } from '@heroui/react';

<Dropdown>
  <Button aria-label="Menu" variant="secondary">
    Actions
  </Button>
  <Dropdown.Popover>
    <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
      <Dropdown.Section>
        <Header>Actions</Header>
        <Dropdown.Item id="new-file" textValue="New file">
          <Label>New file</Label>
        </Dropdown.Item>
        <Dropdown.Item id="edit-file" textValue="Edit file">
          <Label>Edit file</Label>
        </Dropdown.Item>
      </Dropdown.Section>
      <Separator />
      <Dropdown.Section>
        <Header>Danger zone</Header>
        <Dropdown.Item id="delete-file" textValue="Delete file" variant="danger">
          <Label>Delete file</Label>
        </Dropdown.Item>
      </Dropdown.Section>
    </Dropdown.Menu>
  </Dropdown.Popover>
</Dropdown>

```

### Controlled Selection

```tsx
import type { Selection } from '@heroui/react';

import { Dropdown, Button, Label } from '@heroui/react';
import { useState } from 'react';

function ControlledDropdown() {
  const [selected, setSelected] = useState<Selection>(new Set(['bold']));

return (
    <Dropdown>
      <Button aria-label="Menu" variant="secondary">
        Actions
      </Button>
      <Dropdown.Popover>
        <Dropdown.Menu
          selectedKeys={selected}
          selectionMode="multiple"
          onSelectionChange={setSelected}
        >
          <Dropdown.Item id="bold" textValue="Bold">
            <Label>Bold</Label>
            <Dropdown.ItemIndicator />
          </Dropdown.Item>
          <Dropdown.Item id="italic" textValue="Italic">
            <Label>Italic</Label>
            <Dropdown.ItemIndicator />
          </Dropdown.Item>
        </Dropdown.Menu>
      </Dropdown.Popover>
    </Dropdown>
  );
}

```

### With Submenus

```tsx
import { Dropdown, Button, Label } from '@heroui/react';

<Dropdown>
  <Button aria-label="Menu" variant="secondary">
    Share
  </Button>
  <Dropdown.Popover>
    <Dropdown.Menu onAction={(key) => alert(`Selected: ${key}`)}>
      <Dropdown.Item id="copy-link" textValue="Copy Link">
        <Label>Copy Link</Label>
      </Dropdown.Item>
      <Dropdown.SubmenuTrigger>
        <Dropdown.Item id="share" textValue="Share">
          <Label>Other</Label>
          <Dropdown.SubmenuIndicator />
        </Dropdown.Item>
        <Dropdown.Popover>
          <Dropdown.Menu>
            <Dropdown.Item id="whatsapp" textValue="WhatsApp">
              <Label>WhatsApp</Label>
            </Dropdown.Item>
            <Dropdown.Item id="telegram" textValue="Telegram">
              <Label>Telegram</Label>
            </Dropdown.Item>
          </Dropdown.Menu>
        </Dropdown.Popover>
      </Dropdown.SubmenuTrigger>
    </Dropdown.Menu>
  </Dropdown.Popover>
</Dropdown>

```

## Accessibility

The Dropdown component implements the ARIA menu pattern and provides:

* Full keyboard navigation support (arrow keys, home/end, typeahead)
* Screen reader announcements for actions and selection changes
* Proper focus management
* Support for disabled states
* Long press interaction support
* Submenu navigation

For more information, see the [React Aria Menu documentation](https://react-spectrum.adobe.com/react-aria/Menu.html#menu).

</page>

<page url="/docs/react/components/listbox">
# ListBox

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/listbox
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(collections)/listbox.mdx
> A listbox displays a list of options and allows a user to select one or more of them

## Import

```tsx
import { ListBox } from '@heroui/react';

```

### Usage

```tsx
import {Avatar, Description, Label, ListBox} from "@heroui/react";

```

### Anatomy

Import the ListBox component and access all parts using dot notation.

```tsx
import { ListBox, Label, Description, Header } from '@heroui/react';

export default () => (
  <ListBox>
    <ListBox.Item>
      <Label />
      <Description />
      <ListBox.ItemIndicator />
    </ListBox.Item>
    <ListBox.Section>
      <Header />
      <ListBox.Item>
        <Label />
      </ListBox.Item>
    </ListBox.Section>
  </ListBox>
)

```

### With Sections

```tsx
"use client";

import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";

export function WithSections() {
  return (
    <Surface className="w-[256px] rounded-3xl shadow-surface">
      <ListBox
        aria-label="File actions"
        className="w-full p-2"
        selectionMode="none"
        onAction={(key) => alert(`Selected item: ${key}`)}
      >
        <ListBox.Section>
          <Header>Actions</Header>
          <ListBox.Item id="new-file" textValue="New file">
            <div className="flex h-8 items-start justify-center pt-px">
              <SquarePlus className="size-4 shrink-0 text-muted" />
            </div>
            <div className="flex flex-col">
              <Label>New file</Label>
              <Description>Create a new file</Description>
            </div>
            <Kbd className="ms-auto" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>N</Kbd.Content>
            </Kbd>
          </ListBox.Item>
          <ListBox.Item id="edit-file" textValue="Edit file">
            <div className="flex h-8 items-start justify-center pt-px">
              <Pencil className="size-4 shrink-0 text-muted" />
            </div>
            <div className="flex flex-col">
              <Label>Edit file</Label>
              <Description>Make changes</Description>
            </div>
            <Kbd className="ms-auto" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>E</Kbd.Content>
            </Kbd>
          </ListBox.Item>
        </ListBox.Section>
        <Separator />
        <ListBox.Section>
          <Header>Danger zone</Header>
          <ListBox.Item id="delete-file" textValue="Delete file" variant="danger">
            <div className="flex h-8 items-start justify-center pt-px">
              <TrashBin className="size-4 shrink-0 text-danger" />
            </div>
            <div className="flex flex-col">
              <Label>Delete file</Label>
              <Description>Move to trash</Description>
            </div>
            <Kbd className="ms-auto" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Abbr keyValue="shift" />
              <Kbd.Content>D</Kbd.Content>
            </Kbd>
          </ListBox.Item>
        </ListBox.Section>
      </ListBox>
    </Surface>
  );
}

```

### Multi Select

```tsx
import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";

export function MultiSelect() {
  return (
    <Surface className="w-[256px] rounded-3xl shadow-surface">
      <ListBox aria-label="Users" selectionMode="multiple">
        <ListBox.Item id="1" textValue="Bob">
          <Avatar size="sm">
            <Avatar.Image
              alt="Bob"
              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
            />
            <Avatar.Fallback>B</Avatar.Fallback>
          </Avatar>
          <div className="flex flex-col">
            <Label>Bob</Label>
            <Description>bob@heroui.com</Description>
          </div>
          <ListBox.ItemIndicator />
        </ListBox.Item>
        <ListBox.Item id="2" textValue="Fred">
          <Avatar size="sm">
            <Avatar.Image
              alt="Fred"
              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
            />
            <Avatar.Fallback>F</Avatar.Fallback>
          </Avatar>
          <div className="flex flex-col">
            <Label>Fred</Label>
            <Description>fred@heroui.com</Description>
          </div>
          <ListBox.ItemIndicator />
        </ListBox.Item>
        <ListBox.Item id="3" textValue="Martha">
          <Avatar size="sm">
            <Avatar.Image
              alt="Martha"
              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
            />
            <Avatar.Fallback>M</Avatar.Fallback>
          </Avatar>
          <div className="flex flex-col">
            <Label>Martha</Label>
            <Description>martha@heroui.com</Description>
          </div>
          <ListBox.ItemIndicator />
        </ListBox.Item>
      </ListBox>
    </Surface>
  );
}

```

### With Disabled Items

```tsx
"use client";

import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons";
import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react";

export function WithDisabledItems() {
  return (
    <Surface className="w-[256px] rounded-3xl shadow-surface">
      <ListBox
        aria-label="File actions"
        className="w-full p-2"
        disabledKeys={["delete-file"]}
        selectionMode="none"
        onAction={(key) => alert(`Selected item: ${key}`)}
      >
        <ListBox.Section>
          <Header>Actions</Header>
          <ListBox.Item id="new-file" textValue="New file">
            <div className="flex h-8 items-start justify-center pt-px">
              <SquarePlus className="size-4 shrink-0 text-muted" />
            </div>
            <div className="flex flex-col">
              <Label>New file</Label>
              <Description>Create a new file</Description>
            </div>
            <Kbd className="ms-auto" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>N</Kbd.Content>
            </Kbd>
          </ListBox.Item>
          <ListBox.Item id="edit-file" textValue="Edit file">
            <div className="flex h-8 items-start justify-center pt-px">
              <Pencil className="size-4 shrink-0 text-muted" />
            </div>
            <div className="flex flex-col">
              <Label>Edit file</Label>
              <Description>Make changes</Description>
            </div>
            <Kbd className="ms-auto" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Content>E</Kbd.Content>
            </Kbd>
          </ListBox.Item>
        </ListBox.Section>
        <Separator />
        <ListBox.Section>
          <Header>Danger zone</Header>
          <ListBox.Item id="delete-file" textValue="Delete file" variant="danger">
            <div className="flex h-8 items-start justify-center pt-px">
              <TrashBin className="size-4 shrink-0 text-danger" />
            </div>
            <div className="flex flex-col">
              <Label>Delete file</Label>
              <Description>Move to trash</Description>
            </div>
            <Kbd className="ms-auto" variant="light">
              <Kbd.Abbr keyValue="command" />
              <Kbd.Abbr keyValue="shift" />
              <Kbd.Content>D</Kbd.Content>
            </Kbd>
          </ListBox.Item>
        </ListBox.Section>
      </ListBox>
    </Surface>
  );
}

```

### Custom Check Icon

```tsx
"use client";

import {Check} from "@gravity-ui/icons";
import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";

export function CustomCheckIcon() {
  return (
    <Surface className="w-[256px] rounded-3xl shadow-surface">
      <ListBox aria-label="Users" selectionMode="multiple">
        <ListBox.Item id="1" textValue="Bob">
          <Avatar size="sm">
            <Avatar.Image
              alt="Bob"
              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
            />
            <Avatar.Fallback>B</Avatar.Fallback>
          </Avatar>
          <div className="flex flex-col">
            <Label>Bob</Label>
            <Description>bob@heroui.com</Description>
          </div>
          <ListBox.ItemIndicator>
            {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
          </ListBox.ItemIndicator>
        </ListBox.Item>
        <ListBox.Item id="2" textValue="Fred">
          <Avatar size="sm">
            <Avatar.Image
              alt="Fred"
              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
            />
            <Avatar.Fallback>F</Avatar.Fallback>
          </Avatar>
          <div className="flex flex-col">
            <Label>Fred</Label>
            <Description>fred@heroui.com</Description>
          </div>
          <ListBox.ItemIndicator>
            {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
          </ListBox.ItemIndicator>
        </ListBox.Item>
        <ListBox.Item id="3" textValue="Martha">
          <Avatar size="sm">
            <Avatar.Image
              alt="Martha"
              src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
            />
            <Avatar.Fallback>M</Avatar.Fallback>
          </Avatar>
          <div className="flex flex-col">
            <Label>Martha</Label>
            <Description>martha@heroui.com</Description>
          </div>
          <ListBox.ItemIndicator>
            {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
          </ListBox.ItemIndicator>
        </ListBox.Item>
      </ListBox>
    </Surface>
  );
}

```

### Controlled

```tsx
"use client";

import type {Selection} from "@heroui/react";

import {Check} from "@gravity-ui/icons";
import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react";
import {useState} from "react";

export function Controlled() {
  const [selected, setSelected] = useState<Selection>(new Set(["1"]));

const selectedItems = Array.from(selected);

return (
    <div className="space-y-4">
      <Surface className="w-[256px] rounded-3xl shadow-surface">
        <ListBox
          aria-label="Users"
          selectedKeys={selected}
          selectionMode="multiple"
          onSelectionChange={setSelected}
        >
          <ListBox.Item id="1" textValue="Bob">
            <Avatar size="sm">
              <Avatar.Image
                alt="Bob"
                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"
              />
              <Avatar.Fallback>B</Avatar.Fallback>
            </Avatar>
            <div className="flex flex-col">
              <Label>Bob</Label>
              <Description>bob@heroui.com</Description>
            </div>
            <ListBox.ItemIndicator>
              {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
            </ListBox.ItemIndicator>
          </ListBox.Item>
          <ListBox.Item id="2" textValue="Fred">
            <Avatar size="sm">
              <Avatar.Image
                alt="Fred"
                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"
              />
              <Avatar.Fallback>F</Avatar.Fallback>
            </Avatar>
            <div className="flex flex-col">
              <Label>Fred</Label>
              <Description>fred@heroui.com</Description>
            </div>
            <ListBox.ItemIndicator>
              {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
            </ListBox.ItemIndicator>
          </ListBox.Item>
          <ListBox.Item id="3" textValue="Martha">
            <Avatar size="sm">
              <Avatar.Image
                alt="Martha"
                src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg"
              />
              <Avatar.Fallback>M</Avatar.Fallback>
            </Avatar>
            <div className="flex flex-col">
              <Label>Martha</Label>
              <Description>martha@heroui.com</Description>
            </div>
            <ListBox.ItemIndicator>
              {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)}
            </ListBox.ItemIndicator>
          </ListBox.Item>
        </ListBox>
      </Surface>
      <p className="text-sm text-muted">
        Selected: {selectedItems.length > 0 ? selectedItems.join(", ") : "None"}
      </p>
    </div>
  );
}

```

## Related Components

* **Select**: Dropdown select control
* **ComboBox**: Text input with searchable dropdown list
* **Avatar**: Display user profile images

## Styling

### Passing Tailwind CSS classes

```tsx
import { ListBox } from '@heroui/react';

function CustomListBox() {
  return (
    <ListBox className="border rounded-lg p-2 bg-surface">
      <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary">
        Item 1
      </ListBox.Item>
    </ListBox>
  );
}

```

### Customizing the component classes

To customize the ListBox component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .listbox {
    @apply rounded-lg border border-border bg-surface p-2;
  }

.listbox-item {
    @apply rounded px-2 py-1 cursor-pointer;
  }

.listbox-item--danger {
    @apply text-danger;
  }

.listbox-item__indicator {
    @apply text-accent;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The ListBox component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/listbox.css)):

#### Base Classes

* `.listbox` - Base listbox container
* `.listbox-item` - Individual listbox item
* `.listbox-item__indicator` - Selection indicator icon
* `.listbox-section` - Section container for grouping items

#### Variant Classes

* `.listbox--default` - Default variant styling
* `.listbox--danger` - Danger variant styling
* `.listbox-item--default` - Default item variant
* `.listbox-item--danger` - Danger item variant

#### State Classes

* `.listbox-item[data-selected="true"]` - Selected item state
* `.listbox-item[data-focus-visible="true"]` - Focused item state
* `.listbox-item[data-disabled="true"]` - Disabled item state
* `.listbox-item__indicator[data-visible="true"]` - Visible indicator state

### Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

* **Hover**: `:hover` or `[data-hovered="true"]` on item
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on item
* **Selected**: `[data-selected="true"]` on item
* **Disabled**: `:disabled` or `[data-disabled="true"]` on item

## API Reference

### ListBox Props

| Prop                  | Type                               | Default     | Description                              |
| --------------------- | ---------------------------------- | ----------- | ---------------------------------------- |
| `aria-label`          | `string`                           | -           | Accessibility label for the listbox      |
| `aria-labelledby`     | `string`                           | -           | ID of element that labels the listbox    |
| `selectionMode`       | `"none" \| "single" \| "multiple"` | `"single"`  | Selection behavior                       |
| `selectedKeys`        | `Selection`                        | -           | Controlled selected keys                 |
| `defaultSelectedKeys` | `Selection`                        | -           | Initial selected keys                    |
| `onSelectionChange`   | `(keys: Selection) => void`        | -           | Handler called when selection changes    |
| `disabledKeys`        | `Iterable<Key>`                    | -           | Keys of disabled items                   |
| `onAction`            | `(key: Key) => void`               | -           | Handler called when an item is activated |
| `variant`             | `"default" \| "danger"`            | `"default"` | Visual variant                           |
| `className`           | `string`                           | -           | Additional CSS classes                   |
| `children`            | `ReactNode`                        | -           | ListBox items and sections               |

### ListBox.Item Props

| Prop         | Type                          | Default     | Description                                |
| ------------ | ----------------------------- | ----------- | ------------------------------------------ |
| `id`         | `Key`                         | -           | Unique identifier for the item             |
| `textValue`  | `string`                      | -           | Text value for accessibility and typeahead |
| `isDisabled` | `boolean`                     | `false`     | Whether this item is disabled              |
| `variant`    | `"default" \| "danger"`       | `"default"` | Visual variant                             |
| `className`  | `string`                      | -           | Additional CSS classes                     |
| `children`   | `ReactNode \| RenderFunction` | -           | Item content or render function            |

### ListBox.ItemIndicator Props

| Prop        | Type                          | Default | Description                                 |
| ----------- | ----------------------------- | ------- | ------------------------------------------- |
| `className` | `string`                      | -       | Additional CSS classes                      |
| `children`  | `ReactNode \| RenderFunction` | -       | Custom indicator content or render function |

### ListBox.Section Props

| Prop        | Type        | Default | Description                                |
| ----------- | ----------- | ------- | ------------------------------------------ |
| `className` | `string`    | -       | Additional CSS classes                     |
| `children`  | `ReactNode` | -       | Section content including Header and Items |

### RenderProps

When using render functions with ListBox.Item or ListBox.ItemIndicator, these values are provided:

## Examples

### Basic Usage

```tsx
import { ListBox, Label, Description } from '@heroui/react';

<ListBox aria-label="Users" selectionMode="single">
  <ListBox.Item id="1" textValue="Bob">
    <Label>Bob</Label>
    <Description>bob@heroui.com</Description>
  </ListBox.Item>
  <ListBox.Item id="2" textValue="Alice">
    <Label>Alice</Label>
    <Description>alice@heroui.com</Description>
  </ListBox.Item>
</ListBox>

```

### With Sections

```tsx
import { ListBox, Header, Separator } from '@heroui/react';

<ListBox aria-label="Actions" selectionMode="none" onAction={(key) => console.log(key)}>
  <ListBox.Section>
    <Header>Actions</Header>
    <ListBox.Item id="new" textValue="New file">New file</ListBox.Item>
    <ListBox.Item id="edit" textValue="Edit file">Edit file</ListBox.Item>
  </ListBox.Section>
  <Separator />
  <ListBox.Section>
    <Header>Danger zone</Header>
    <ListBox.Item id="delete" textValue="Delete" variant="danger">Delete</ListBox.Item>
  </ListBox.Section>
</ListBox>

```

### Controlled Selection

```tsx
import { ListBox, Selection } from '@heroui/react';
import { useState } from 'react';

function ControlledListBox() {
  const [selected, setSelected] = useState<Selection>(new Set(["1"]));

return (
    <ListBox
      aria-label="Options"
      selectedKeys={selected}
      selectionMode="multiple"
      onSelectionChange={setSelected}
    >
      <ListBox.Item id="1" textValue="Option 1">Option 1</ListBox.Item>
      <ListBox.Item id="2" textValue="Option 2">Option 2</ListBox.Item>
      <ListBox.Item id="3" textValue="Option 3">Option 3</ListBox.Item>
    </ListBox>
  );
}

```

### Custom Indicator

```tsx
import { ListBox, ListBoxItemIndicator } from '@heroui/react';
import { Icon } from '@iconify/react';

<ListBox aria-label="Options" selectionMode="multiple">
  <ListBox.Item id="1" textValue="Option 1">
    Option 1
    <ListBox.ItemIndicator>
      {({isSelected}) =>
        isSelected ? <Icon icon="gravity-ui:check" /> : null
      }
    </ListBox.ItemIndicator>
  </ListBox.Item>
</ListBox>

```

## Accessibility

The ListBox component implements the ARIA listbox pattern and provides:

* Full keyboard navigation support
* Screen reader announcements for selection changes
* Proper focus management
* Support for disabled states
* Typeahead search functionality

For more information, see the [React Aria ListBox documentation](https://react-spectrum.adobe.com/react-aria/ListBox.html).

</page>

<page url="/docs/react/components/tag-group">
# TagGroup

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/tag-group
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(collections)/tag-group.mdx
> A focusable list of tags with support for keyboard navigation, selection, and removal

## Import

```tsx
import { TagGroup } from '@heroui/react';

```

### Usage

```tsx
"use client";

import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
import {Tag, TagGroup} from "@heroui/react";

```

### Anatomy

```tsx
import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';

export default () => (
  <TagGroup>
    <Label />
    <TagGroup.List>
      <Tag>
        <Tag.RemoveButton />
      </Tag>
    </TagGroup.List>
    <Description />
    <ErrorMessage />
  </TagGroup>
)

```

### Sizes

```tsx
"use client";

import {Label, Tag, TagGroup} from "@heroui/react";

export function TagGroupSizes() {
  return (
    <div className="flex flex-col gap-6">
      <TagGroup selectionMode="single" size="sm">
        <Label>Small</Label>
        <TagGroup.List>
          <Tag>News</Tag>
          <Tag>Travel</Tag>
          <Tag>Gaming</Tag>
        </TagGroup.List>
      </TagGroup>
      <TagGroup selectionMode="single" size="md">
        <Label>Medium</Label>
        <TagGroup.List>
          <Tag>News</Tag>
          <Tag>Travel</Tag>
          <Tag>Gaming</Tag>
        </TagGroup.List>
      </TagGroup>
      <TagGroup selectionMode="single" size="lg">
        <Label>Large</Label>
        <TagGroup.List>
          <Tag>News</Tag>
          <Tag>Travel</Tag>
          <Tag>Gaming</Tag>
        </TagGroup.List>
      </TagGroup>
    </div>
  );
}

```

### Variants

```tsx
"use client";

import {Description, Form, Label, ListBox, Select, Surface, Tag, TagGroup} from "@heroui/react";

export function TagGroupVariants() {
  const items = [
    {id: "news", name: "News"},
    {id: "travel", name: "Travel"},
    {id: "gaming", name: "Gaming"},
  ];

return (
    <div className="flex flex-col gap-8">
      <TagGroup selectionMode="single" variant="default">
        <Label>Default</Label>
        <TagGroup.List>
          <Tag>News</Tag>
          <Tag>Travel</Tag>
          <Tag>Gaming</Tag>
        </TagGroup.List>
      </TagGroup>

<TagGroup selectionMode="single" variant="surface">
        <Label>Surface</Label>
        <TagGroup.List>
          <Tag>News</Tag>
          <Tag>Travel</Tag>
          <Tag>Gaming</Tag>
        </TagGroup.List>
      </TagGroup>

<div className="flex w-sm items-center justify-center rounded-3xl bg-surface p-4">
        <Surface className="w-full">
          <TagGroup selectionMode="single" variant="on-surface">
            <Label>On Surface</Label>
            <TagGroup.List>
              <Tag>News</Tag>
              <Tag>Travel</Tag>
              <Tag>Gaming</Tag>
            </TagGroup.List>
            <Description>Tags on surface component</Description>
          </TagGroup>
        </Surface>
      </div>

<Form className="w-100">
        <div className="flex flex-col gap-2">
          <Select
            className="w-full"
            defaultValue={["news", "travel"]}
            placeholder="Select items"
            selectionMode="multiple"
          >
            <Select.Trigger>
              <Select.Value className="no-truncate flex flex-wrap gap-2">
                {({defaultChildren, isPlaceholder, state}) => {
                  if (isPlaceholder || state.selectedItems.length === 0) {
                    return defaultChildren;
                  }

const selectedItemsKeys = state.selectedItems.map((item) => item.key);

return (
                    <TagGroup variant="on-form-field">
                      <Label>On Form Field</Label>
                      <TagGroup.List className="flex flex-wrap gap-1">
                        {selectedItemsKeys.map((selectedItemKey) => {
                          const item = items.find((s) => s.id === selectedItemKey);

if (!item) return null;

return (
                            <Tag key={item.id} id={item.id}>
                              {item.name}
                            </Tag>
                          );
                        })}
                      </TagGroup.List>
                    </TagGroup>
                  );
                }}
              </Select.Value>
              <Select.Indicator />
            </Select.Trigger>
            <Select.Popover>
              <ListBox selectionMode="multiple">
                {items.map((skill) => (
                  <ListBox.Item key={skill.id} id={skill.id} textValue={skill.name}>
                    {skill.name}
                    <ListBox.ItemIndicator />
                  </ListBox.Item>
                ))}
              </ListBox>
            </Select.Popover>
          </Select>
        </div>
      </Form>
    </div>
  );
}

```

### Disabled

```tsx
"use client";

import {Description, Label, Tag, TagGroup} from "@heroui/react";

export function TagGroupDisabled() {
  return (
    <div className="flex flex-col gap-4">
      <TagGroup selectionMode="single">
        <Label>Disabled Tags</Label>
        <TagGroup.List>
          <Tag isDisabled>News</Tag>
          <Tag>Travel</Tag>
          <Tag isDisabled>Gaming</Tag>
        </TagGroup.List>
        <Description>Some tags are disabled</Description>
      </TagGroup>

<TagGroup disabledKeys={["travel"]} selectionMode="single">
        <Label>Disabled Keys</Label>
        <TagGroup.List>
          <Tag id="news">News</Tag>
          <Tag id="travel">Travel</Tag>
          <Tag id="gaming">Gaming</Tag>
        </TagGroup.List>
        <Description>Tags disabled via disabledKeys prop</Description>
      </TagGroup>
    </div>
  );
}

```

### Selection Modes

```tsx
"use client";

import type {Key} from "@heroui/react";

import {Description, Label, Tag, TagGroup} from "@heroui/react";
import {useState} from "react";

export function TagGroupSelectionModes() {
  const [singleSelected, setSingleSelected] = useState<Iterable<Key>>(new Set(["news"]));
  const [multipleSelected, setMultipleSelected] = useState<Iterable<Key>>(
    new Set(["news", "travel"]),
  );

return (
    <div className="flex flex-col gap-8">
      <TagGroup
        selectedKeys={singleSelected}
        selectionMode="single"
        onSelectionChange={(keys) => setSingleSelected(keys)}
      >
        <Label>Single Selection</Label>
        <TagGroup.List>
          <Tag>News</Tag>
          <Tag>Travel</Tag>
          <Tag>Gaming</Tag>
          <Tag>Shopping</Tag>
        </TagGroup.List>
        <Description>Choose one category</Description>
      </TagGroup>

<TagGroup
        selectedKeys={multipleSelected}
        selectionMode="multiple"
        onSelectionChange={(keys) => setMultipleSelected(keys)}
      >
        <Label>Multiple Selection</Label>
        <TagGroup.List>
          <Tag>News</Tag>
          <Tag>Travel</Tag>
          <Tag>Gaming</Tag>
          <Tag>Shopping</Tag>
        </TagGroup.List>
        <Description>Choose multiple categories</Description>
      </TagGroup>
    </div>
  );
}

```

### Controlled

```tsx
"use client";

import type {Key} from "@heroui/react";

import {Description, Label, Tag, TagGroup} from "@heroui/react";
import {useState} from "react";

export function TagGroupControlled() {
  const [selected, setSelected] = useState<Iterable<Key>>(new Set(["news", "travel"]));

return (
    <div className="flex flex-col gap-3">
      <TagGroup
        selectedKeys={selected}
        selectionMode="multiple"
        onSelectionChange={(keys) => setSelected(keys)}
      >
        <Label>Categories (controlled)</Label>
        <TagGroup.List>
          <Tag id="news">News</Tag>
          <Tag id="travel">Travel</Tag>
          <Tag id="gaming">Gaming</Tag>
          <Tag id="shopping">Shopping</Tag>
        </TagGroup.List>
        <Description>
          Selected: {Array.from(selected).length > 0 ? Array.from(selected).join(", ") : "None"}
        </Description>
      </TagGroup>
    </div>
  );
}

```

### With Error Message

```tsx
"use client";

import type {Key} from "@heroui/react";

import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react";
import {useMemo, useState} from "react";

export function TagGroupWithErrorMessage() {
  const [selected, setSelected] = useState<Iterable<Key>>(new Set());

const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]);

return (
    <TagGroup
      selectedKeys={selected}
      selectionMode="multiple"
      onSelectionChange={(keys) => setSelected(keys)}
    >
      <Label>Amenities</Label>
      <TagGroup.List>
        <Tag id="laundry">Laundry</Tag>
        <Tag id="fitness">Fitness center</Tag>
        <Tag id="parking">Parking</Tag>
        <Tag id="pool">Swimming pool</Tag>
        <Tag id="breakfast">Breakfast</Tag>
      </TagGroup.List>
      <Description>
        {isInvalid
          ? "Select at least one category"
          : "Selected: " + Array.from(selected).join(", ")}
      </Description>
      <ErrorMessage>{!!isInvalid && <>Please select at least one category</>}</ErrorMessage>
    </TagGroup>
  );
}

```

### With Prefix

```tsx
"use client";

import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons";
import {Avatar, Description, Label, Tag, TagGroup} from "@heroui/react";

export function TagGroupWithPrefix() {
  return (
    <div className="flex flex-col gap-8">
      <TagGroup selectionMode="single">
        <Label>With Icons</Label>
        <TagGroup.List>
          <Tag>
            <SquareArticle />
            News
          </Tag>
          <Tag>
            <PlanetEarth />
            Travel
          </Tag>
          <Tag>
            <Rocket />
            Gaming
          </Tag>
          <Tag>
            <ShoppingBag />
            Shopping
          </Tag>
        </TagGroup.List>
        <Description>Tags with icons</Description>
      </TagGroup>

<TagGroup selectionMode="single">
        <Label>With Avatars</Label>
        <TagGroup.List>
          <Tag>
            <Avatar className="size-4">
              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" />
              <Avatar.Fallback>F</Avatar.Fallback>
            </Avatar>
            Fred
          </Tag>
          <Tag>
            <Avatar className="size-4">
              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" />
              <Avatar.Fallback>M</Avatar.Fallback>
            </Avatar>
            Michael
          </Tag>
          <Tag>
            <Avatar className="size-4">
              <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" />
              <Avatar.Fallback>J</Avatar.Fallback>
            </Avatar>
            Jane
          </Tag>
        </TagGroup.List>
        <Description>Tags with avatars</Description>
      </TagGroup>
    </div>
  );
}

```

### With Remove Button

```tsx
"use client";

import type {Key} from "@heroui/react";

import {CircleXmarkFill} from "@gravity-ui/icons";
import {Description, EmptyState, Label, Tag, TagGroup} from "@heroui/react";
import {useState} from "react";

export function TagGroupWithRemoveButton() {
  type TagItem = {id: string; name: string};

const [tags, setTags] = useState<TagItem[]>([
    {id: "news", name: "News"},
    {id: "travel", name: "Travel"},
    {id: "gaming", name: "Gaming"},
    {id: "shopping", name: "Shopping"},
  ]);

const [frameworks, setFrameworks] = useState<TagItem[]>([
    {id: "react", name: "React"},
    {id: "vue", name: "Vue"},
    {id: "angular", name: "Angular"},
    {id: "svelte", name: "Svelte"},
  ]);

const onRemoveTags = (keys: Set<Key>) => {
    setTags(tags.filter((tag) => !keys.has(tag.id)));
  };

const onRemoveFrameworks = (keys: Set<Key>) => {
    setFrameworks(frameworks.filter((framework) => !keys.has(framework.id)));
  };

return (
    <div className="flex flex-col gap-8">
      <div className="w-sm">
        <TagGroup selectionMode="single" onRemove={onRemoveTags}>
          <Label>Default Remove Button</Label>
          <TagGroup.List
            items={tags}
            renderEmptyState={() => <EmptyState className="p-1">No categories found</EmptyState>}
          >
            {(tag) => (
              <Tag key={tag.name} id={tag.id} textValue={tag.name}>
                {tag.name}
              </Tag>
            )}
          </TagGroup.List>
          <Description>Click the X to remove tags</Description>
        </TagGroup>
      </div>

<div className="w-md">
        <TagGroup selectionMode="single" onRemove={onRemoveFrameworks}>
          <Label>Custom Remove Button</Label>
          <TagGroup.List
            items={frameworks}
            renderEmptyState={() => <EmptyState className="p-1">No frameworks found</EmptyState>}
          >
            {(tag) => (
              <Tag key={tag.id} id={tag.id} textValue={tag.name}>
                {(renderProps) => (
                  <>
                    {tag.name}
                    {!!renderProps.allowsRemoving && (
                      <Tag.RemoveButton>
                        <CircleXmarkFill />
                      </Tag.RemoveButton>
                    )}
                  </>
                )}
              </Tag>
            )}
          </TagGroup.List>
          <Description>Custom remove button with icon</Description>
        </TagGroup>
      </div>
    </div>
  );
}

```

### With List Data

```tsx
"use client";

import type {Key} from "@heroui/react";

import {Avatar, Description, EmptyState, Label, Tag, TagGroup, useListData} from "@heroui/react";

export function TagGroupWithListData() {
  type User = {
    id: string;
    name: string;
    avatar: string;
    fallback: string;
  };

const list = useListData<User>({
    getKey: (item) => item.id,
    initialItems: [
      {
        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg",
        fallback: "F",
        id: "fred",
        name: "Fred",
      },
      {
        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg",
        fallback: "M",
        id: "michael",
        name: "Michael",
      },
      {
        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg",
        fallback: "J",
        id: "jane",
        name: "Jane",
      },
      {
        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg",
        fallback: "A",
        id: "alice",
        name: "Alice",
      },
      {
        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg",
        fallback: "B",
        id: "bob",
        name: "Bob",
      },
      {
        avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg",
        fallback: "C",
        id: "charlie",
        name: "Charlie",
      },
    ],
    initialSelectedKeys: new Set(["fred", "michael"]),
  });

const onRemove = (keys: Set<Key>) => {
    list.remove(...keys);
  };

return (
    <div className="w-sm">
      <TagGroup
        selectedKeys={list.selectedKeys}
        selectionMode="multiple"
        onRemove={onRemove}
        onSelectionChange={(keys) => list.setSelectedKeys(keys)}
      >
        <Label>Team Members</Label>
        <TagGroup.List
          items={list.items}
          renderEmptyState={() => <EmptyState className="p-1">No team members</EmptyState>}
        >
          {(user) => (
            <Tag key={user.id} id={user.id} textValue={user.name}>
              <Avatar className="size-4" size="sm">
                <Avatar.Image src={user.avatar} />
                <Avatar.Fallback>{user.fallback}</Avatar.Fallback>
              </Avatar>
              {user.name}
            </Tag>
          )}
        </TagGroup.List>
        <Description>Select team members for your project</Description>
      </TagGroup>
      {list.selectedKeys !== "all" && Array.from(list.selectedKeys).length > 0 && (
        <div className="mt-4 flex flex-col gap-2">
          <p className="text-sm font-medium text-muted">Selected:</p>
          <div className="flex flex-wrap gap-2">
            {Array.from(list.selectedKeys).map((key) => {
              const user = list.getItem(key);

if (!user) return null;

return (
                <div
                  key={`${user.id}-selected`}
                  className="flex items-center gap-2 rounded-lg bg-surface-tertiary px-2 py-1"
                >
                  <Avatar className="size-4" size="sm">
                    <Avatar.Image src={user.avatar} />
                    <Avatar.Fallback>{user.fallback}</Avatar.Fallback>
                  </Avatar>
                  <span className="text-sm">{user.name}</span>
                </div>
              );
            })}
          </div>
        </div>
      )}
    </div>
  );
}

```

## Related Components

* **Label**: Accessible label for form controls
* **Description**: Helper text for form fields
* **ErrorMessage**: Displays validation error messages for components with validation support

## Styling

### Passing Tailwind CSS classes

```tsx
import { TagGroup, Tag, Label } from '@heroui/react';

function CustomTagGroup() {
  return (
    <TagGroup className="w-full">
      <Label>Categories</Label>
      <TagGroup.List className="gap-2">
        <Tag className="rounded-lg px-4 py-2 font-bold">
          Custom Styled
        </Tag>
      </TagGroup.List>
    </TagGroup>
  );
}

```

### Customizing the component classes

To customize the TagGroup component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .tag-group {
    @apply flex flex-col gap-2;
  }

.tag-group__list {
    @apply flex flex-wrap gap-2;
  }

.tag {
    @apply rounded-full px-3 py-1;
  }

.tag__remove-button {
    @apply ml-1;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The TagGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag-group.css) and [tag.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag.css)):

#### Base Classes

* `.tag-group` - Base tag group container
* `.tag-group__list` - Container for the list of tags
* `.tag` - Base tag styles
* `.tag__remove-button` - Remove button trigger

#### Slot Classes

* `.tag-group [slot="description"]` - Description slot styles
* `.tag-group [slot="errorMessage"]` - ErrorMessage slot styles

#### Size Classes

* `.tag--sm` - Small size tag
* `.tag--md` - Medium size tag (default)
* `.tag--lg` - Large size tag

#### Variant Classes

* `.tag--default` - Default variant with field-on-background styling
* `.tag--surface` - Surface variant with surface background
* `.tag--on-surface` - On-surface variant for use on surface components
* `.tag--on-form-field` - On-form-field variant for use within form components

#### Modifier Classes

* `.tag__remove-button--on-surface` - Remove button modifier for on-surface variant

#### State Classes

* `.tag[data-selected="true"]` - Selected tag state
* `.tag[data-disabled="true"]` - Disabled tag state
* `.tag[data-hovered="true"]` - Hovered tag state
* `.tag[data-pressed="true"]` - Pressed tag state
* `.tag[data-focus-visible="true"]` - Focused tag state (keyboard focus)

### Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

* **Hover**: `:hover` or `[data-hovered="true"]` on tag
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on tag
* **Pressed**: `:active` or `[data-pressed="true"]` on tag
* **Selected**: `[data-selected="true"]` or `[aria-selected="true"]` on tag
* **Disabled**: `:disabled` or `[data-disabled="true"]` on tag

## API Reference

### TagGroup Props

| Prop                  | Type                                                        | Default     | Description                               |
| --------------------- | ----------------------------------------------------------- | ----------- | ----------------------------------------- |
| `selectionMode`       | `"none" \| "single" \| "multiple"`                          | `"none"`    | The type of selection that is allowed     |
| `selectedKeys`        | `Selection`                                                 | -           | The currently selected keys (controlled)  |
| `defaultSelectedKeys` | `Selection`                                                 | -           | The initial selected keys (uncontrolled)  |
| `onSelectionChange`   | `(keys: Selection) => void`                                 | -           | Handler called when the selection changes |
| `disabledKeys`        | `Iterable<Key>`                                             | -           | Keys of disabled tags                     |
| `isDisabled`          | `boolean`                                                   | -           | Whether the tag group is disabled         |
| `onRemove`            | `(keys: Set<Key>) => void`                                  | -           | Handler called when tags are removed      |
| `size`                | `"sm" \| "md" \| "lg"`                                      | `"md"`      | Size of the tags in the group             |
| `variant`             | `"default" \| "surface" \| "on-surface" \| "on-form-field"` | `"default"` | Visual variant of the tags                |
| `className`           | `string`                                                    | -           | Additional CSS classes                    |
| `children`            | `ReactNode \| RenderFunction`                               | -           | TagGroup content or render function       |

### TagGroup.List Props

| Prop               | Type                          | Default | Description                               |
| ------------------ | ----------------------------- | ------- | ----------------------------------------- |
| `items`            | `Iterable<T>`                 | -       | The items to display in the tag list      |
| `renderEmptyState` | `() => ReactNode`             | -       | Function to render when the list is empty |
| `className`        | `string`                      | -       | Additional CSS classes                    |
| `children`         | `ReactNode \| RenderFunction` | -       | TagList content or render function        |

### Tag Props

| Prop         | Type                          | Default | Description                                                          |
| ------------ | ----------------------------- | ------- | -------------------------------------------------------------------- |
| `id`         | `Key`                         | -       | The unique identifier for the tag                                    |
| `textValue`  | `string`                      | -       | A string representation of the tag's content, used for accessibility |
| `isDisabled` | `boolean`                     | -       | Whether the tag is disabled                                          |
| `className`  | `string`                      | -       | Additional CSS classes                                               |
| `children`   | `ReactNode \| RenderFunction` | -       | Tag content or render function                                       |

**Note**: `size`, `variant`, `isOnSurface`, and `isOnFormField` are inherited from the parent `TagGroup` component and cannot be set directly on individual `Tag` components.

### Tag.RemoveButton Props

| Prop        | Type        | Default | Description                                           |
| ----------- | ----------- | ------- | ----------------------------------------------------- |
| `className` | `string`    | -       | Additional CSS classes                                |
| `children`  | `ReactNode` | -       | Custom remove button content (defaults to close icon) |

### RenderProps

When using render functions with TagGroup.List, these values are provided:

| Prop             | Type      | Description                        |
| ---------------- | --------- | ---------------------------------- |
| `isSelected`     | `boolean` | Whether the tag is selected        |
| `isDisabled`     | `boolean` | Whether the tag is disabled        |
| `isHovered`      | `boolean` | Whether the tag is hovered         |
| `isPressed`      | `boolean` | Whether the tag is pressed         |
| `isFocused`      | `boolean` | Whether the tag is focused         |
| `isFocusVisible` | `boolean` | Whether the tag has keyboard focus |

</page>

<page url="/docs/react/components/slider">
# Slider

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/slider
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(controls)/slider.mdx
> A slider allows a user to select one or more values within a range

## Import

```tsx
import { Slider } from '@heroui/react';

```

### Usage

```tsx
import {Label, Slider} from "@heroui/react";

```

### Anatomy

Import the Slider component and access all parts using dot notation.

```tsx
import { Slider, Label } from '@heroui/react';

export default () => (
  <Slider>
    <Label />
    <Slider.Output />
    <Slider.Track>
      <Slider.Fill />
      <Slider.Thumb />
    </Slider.Track>
  </Slider>
)

```

### Range Slider Anatomy

```tsx
import { Slider, Label } from '@heroui/react';

export default () => (
  <Slider defaultValue={[25, 75]}>
    <Label />
    <Slider.Output />
    <Slider.Track>
      {({state}) => (
        <>
          <Slider.Fill />
          {state.values.map((_, i) => (
            <Slider.Thumb key={i} index={i} />
          ))}
        </>
      )}
    </Slider.Track>
  </Slider>
)

```

### Vertical

```tsx
import {Label, Slider} from "@heroui/react";

export function Vertical() {
  return (
    <div className="flex h-64 items-center justify-center">
      <Slider className="h-full" defaultValue={30} orientation="vertical">
        <Label>Volume</Label>
        <Slider.Output />
        <Slider.Track>
          <Slider.Fill />
          <Slider.Thumb />
        </Slider.Track>
      </Slider>
    </div>
  );
}

```

### Range

```tsx
"use client";

import {Label, Slider} from "@heroui/react";

export function Range() {
  return (
    <Slider
      className="w-full max-w-xs"
      defaultValue={[100, 500]}
      formatOptions={{currency: "USD", style: "currency"}}
      maxValue={1000}
      minValue={0}
      step={50}
    >
      <Label>Price Range</Label>
      <Slider.Output />
      <Slider.Track>
        {({state}) => (
          <>
            <Slider.Fill />
            {state.values.map((_, i) => (
              <Slider.Thumb key={i} index={i} />
            ))}
          </>
        )}
      </Slider.Track>
    </Slider>
  );
}

```

### Disabled

```tsx
import {Label, Slider} from "@heroui/react";

export function Disabled() {
  return (
    <Slider isDisabled className="w-full max-w-xs" defaultValue={30}>
      <Label>Volume</Label>
      <Slider.Output />
      <Slider.Track>
        <Slider.Fill />
        <Slider.Thumb />
      </Slider.Track>
    </Slider>
  );
}

```

## Related Components

* **Label**: Accessible label for form controls
* **Form**: Form validation and submission handling
* **Description**: Helper text for form fields

## Styling

### Passing Tailwind CSS classes

```tsx
import { Slider, Label } from '@heroui/react';

function CustomSlider() {
  return (
    <Slider className="w-full">
      <Label>Volume</Label>
      <Slider.Output className="text-muted-fg text-sm" />
      <Slider.Track className="h-2 rounded-full bg-surface-secondary">
        <Slider.Fill className="bg-accent" />
        <Slider.Thumb className="size-4 rounded-full bg-accent" />
      </Slider.Track>
    </Slider>
  );
}

```

### Customizing the component classes

To customize the Slider component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .slider {
    @apply flex flex-col gap-2;
  }

.slider__output {
    @apply text-muted-fg text-sm;
  }

.slider-track {
    @apply relative h-2 w-full rounded-full bg-surface-secondary;
  }

.slider-fill {
    @apply absolute h-full rounded-full bg-accent;
  }

.slider-thumb {
    @apply size-4 rounded-full bg-accent border-2 border-background;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The Slider component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/slider.css)):

#### Base Classes

* `.slider` - Base slider container
* `.slider__output` - Output element displaying current value(s)
* `.slider-track` - Track element containing fill and thumbs
* `.slider-fill` - Fill element showing selected range
* `.slider-thumb` - Individual thumb element

#### State Classes

* `.slider[data-disabled="true"]` - Disabled slider state
* `.slider[data-orientation="vertical"]` - Vertical orientation
* `.slider-thumb[data-dragging="true"]` - Thumb being dragged
* `.slider-thumb[data-focus-visible="true"]` - Thumb keyboard focused
* `.slider-thumb[data-disabled="true"]` - Disabled thumb state
* `.slider-track[data-fill-start="true"]` - Fill starts at beginning
* `.slider-track[data-fill-end="true"]` - Fill ends at end

### Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

* **Hover**: `:hover` or `[data-hovered="true"]` on thumb
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on thumb
* **Dragging**: `[data-dragging="true"]` on thumb
* **Disabled**: `:disabled` or `[data-disabled="true"]` on slider or thumb

## API Reference

### Slider Props

| Prop              | Type                                  | Default        | Description                           |
| ----------------- | ------------------------------------- | -------------- | ------------------------------------- |
| `value`           | `number \| number[]`                  | -              | The current value (controlled)        |
| `defaultValue`    | `number \| number[]`                  | -              | The default value (uncontrolled)      |
| `onChange`        | `(value: number \| number[]) => void` | -              | Handler called when the value changes |
| `onChangeEnd`     | `(value: number \| number[]) => void` | -              | Handler called when dragging ends     |
| `minValue`        | `number`                              | `0`            | The slider's minimum value            |
| `maxValue`        | `number`                              | `100`          | The slider's maximum value            |
| `step`            | `number`                              | `1`            | The slider's step value               |
| `formatOptions`   | `Intl.NumberFormatOptions`            | -              | The display format of the value label |
| `orientation`     | `"horizontal" \| "vertical"`          | `"horizontal"` | The orientation of the slider         |
| `isDisabled`      | `boolean`                             | -              | Whether the slider is disabled        |
| `aria-label`      | `string`                              | -              | Accessibility label for the slider    |
| `aria-labelledby` | `string`                              | -              | ID of element that labels the slider  |
| `className`       | `string`                              | -              | Additional CSS classes                |
| `children`        | `ReactNode \| RenderFunction`         | -              | Slider content or render function     |

### Slider.Output Props

| Prop        | Type                          | Default | Description                       |
| ----------- | ----------------------------- | ------- | --------------------------------- |
| `className` | `string`                      | -       | Additional CSS classes            |
| `children`  | `ReactNode \| RenderFunction` | -       | Output content or render function |

### Slider.Track Props

| Prop        | Type                          | Default | Description                      |
| ----------- | ----------------------------- | ------- | -------------------------------- |
| `className` | `string`                      | -       | Additional CSS classes           |
| `children`  | `ReactNode \| RenderFunction` | -       | Track content or render function |

### Slider.Fill Props

| Prop        | Type            | Default | Description            |
| ----------- | --------------- | ------- | ---------------------- |
| `className` | `string`        | -       | Additional CSS classes |
| `style`     | `CSSProperties` | -       | Inline styles          |

### Slider.Thumb Props

| Prop         | Type                          | Default | Description                                                      |
| ------------ | ----------------------------- | ------- | ---------------------------------------------------------------- |
| `index`      | `number`                      | `0`     | Index of the thumb within the slider                             |
| `isDisabled` | `boolean`                     | -       | Whether this thumb is disabled                                   |
| `name`       | `string`                      | -       | The name of the input element, used when submitting an HTML form |
| `className`  | `string`                      | -       | Additional CSS classes                                           |
| `children`   | `ReactNode \| RenderFunction` | -       | Thumb content or render function                                 |

### RenderProps

When using render functions with Slider.Output or Slider.Track, these values are provided:

| Prop                 | Type                         | Description                                              |
| -------------------- | ---------------------------- | -------------------------------------------------------- |
| `state`              | `SliderState`                | The state of the slider                                  |
| `values`             | `number[]`                   | Values managed by the slider by thumb index              |
| `getThumbValueLabel` | `(index: number) => string`  | Returns the string label for the specified thumb's value |
| `orientation`        | `"horizontal" \| "vertical"` | The orientation of the slider                            |
| `isDisabled`         | `boolean`                    | Whether the slider is disabled                           |

## Examples

### Basic Usage

```tsx
import { Slider, Label } from '@heroui/react';

<Slider defaultValue={30}>
  <Label>Volume</Label>
  <Slider.Output />
  <Slider.Track>
    <Slider.Fill />
    <Slider.Thumb />
  </Slider.Track>
</Slider>

```

### Range Slider

```tsx
import { Slider, Label } from '@heroui/react';

<Slider
  defaultValue={[100, 500]}
  formatOptions={{style: "currency", currency: "USD"}}
  maxValue={1000}
  minValue={0}
  step={50}
>
  <Label>Price Range</Label>
  <Slider.Output />
  <Slider.Track>
    {({state}) => (
      <>
        <Slider.Fill />
        {state.values.map((_, i) => (
          <Slider.Thumb key={i} index={i} />
        ))}
      </>
    )}
  </Slider.Track>
</Slider>

```

### Controlled Value

```tsx
import { Slider, Label } from '@heroui/react';
import { useState } from 'react';

function ControlledSlider() {
  const [value, setValue] = useState(25);

return (
    <>
      <Slider value={value} onChange={setValue}>
        <Label>Volume</Label>
        <Slider.Output />
        <Slider.Track>
          <Slider.Fill />
          <Slider.Thumb />
        </Slider.Track>
      </Slider>
      <p>Current value: {value}</p>
    </>
  );
}

```

### Custom Value Formatting

```tsx
import { Slider, Label } from '@heroui/react';

<Slider
  defaultValue={60}
  formatOptions={{style: "currency", currency: "USD"}}
>
  <Label>Price</Label>
  <Slider.Output />
  <Slider.Track>
    <Slider.Fill />
    <Slider.Thumb />
  </Slider.Track>
</Slider>

```

### Vertical Orientation

```tsx
import { Slider, Label } from '@heroui/react';

<Slider defaultValue={30} orientation="vertical" aria-label="Volume">
  <Label>Volume</Label>
  <Slider.Output />
  <Slider.Track>
    <Slider.Fill />
    <Slider.Thumb />
  </Slider.Track>
</Slider>

```

### Custom Output Display

```tsx
import { Slider, Label } from '@heroui/react';

<Slider defaultValue={[25, 75]}>
  <Label>Range</Label>
  <Slider.Output>
    {({state}) => 
      state.values.map((_, i) => state.getThumbValueLabel(i)).join(' – ')
    }
  </Slider.Output>
  <Slider.Track>
    {({state}) => (
      <>
        <Slider.Fill />
        {state.values.map((_, i) => (
          <Slider.Thumb key={i} index={i} />
        ))}
      </>
    )}
  </Slider.Track>
</Slider>

```

## Accessibility

The Slider component implements the ARIA slider pattern and provides:

* Full keyboard navigation support (Arrow keys, Home, End, Page Up/Down)
* Screen reader announcements for value changes
* Proper focus management
* Support for disabled states
* HTML form integration via hidden input elements
* Internationalization support with locale-aware value formatting
* Right-to-left (RTL) language support

For more information, see the [React Aria Slider documentation](https://react-spectrum.adobe.com/react-aria/Slider.html).

</page>

<page url="/docs/react/components/switch">
# Switch

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/switch
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(controls)/switch.mdx
> A toggle switch component for boolean states

## Import

```tsx
import { Switch, SwitchGroup, Label } from '@heroui/react';

```

### Usage

```tsx
import {Label, Switch} from "@heroui/react";

```

### Anatomy

Import the Switch component and access all parts using dot notation.

```tsx
import { Switch, Label } from '@heroui/react';

export default () => (
  <Switch>
    <Switch.Control>
      <Switch.Thumb>
        <Switch.Icon/> {/* Optional */}
      </Switch.Thumb>
    </Switch.Control>
    <Label/> {/* Optional */}
  </Switch>
);

```

For grouping multiple switches, use the `SwitchGroup` component:

```tsx
import { Switch, SwitchGroup, Label } from '@heroui/react';

export default () => (
  <SwitchGroup>
    <Switch>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      <Label>Option 1</Label>
    </Switch>
    <Switch>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      <Label>Option 2</Label>
    </Switch>
  </SwitchGroup>
);

```

### Disabled

```tsx
import {Label, Switch} from "@heroui/react";

export function Disabled() {
  return (
    <Switch isDisabled>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      <Label className="text-sm">Enable notifications</Label>
    </Switch>
  );
}

```

### Default Selected

```tsx
import {Label, Switch} from "@heroui/react";

export function DefaultSelected() {
  return (
    <Switch defaultSelected>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      <Label className="text-sm">Enable notifications</Label>
    </Switch>
  );
}

```

### Controlled

```tsx
"use client";

import {Label, Switch} from "@heroui/react";
import React from "react";

export function Controlled() {
  const [isSelected, setIsSelected] = React.useState(false);

return (
    <div className="flex flex-col gap-4">
      <Switch isSelected={isSelected} onChange={setIsSelected}>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label className="text-sm">Enable notifications</Label>
      </Switch>
      <p className="text-sm text-muted">Switch is {isSelected ? "on" : "off"}</p>
    </div>
  );
}

```

### Without Label

```tsx
import {Switch} from "@heroui/react";

export function WithoutLabel() {
  return (
    <Switch aria-label="Enable notifications">
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
    </Switch>
  );
}

```

### Sizes

```tsx
import {Label, Switch} from "@heroui/react";

export function Sizes() {
  return (
    <div className="flex gap-6">
      <Switch size="sm">
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label className="text-xs">Small</Label>
      </Switch>
      <Switch size="md">
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label className="text-sm">Medium</Label>
      </Switch>
      <Switch size="lg">
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label className="text-base">Large</Label>
      </Switch>
    </div>
  );
}

```

### Label Position

```tsx
import {Label, Switch} from "@heroui/react";

export function LabelPosition() {
  return (
    <div className="flex flex-col gap-4">
      <Switch>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label className="text-sm">Label after</Label>
      </Switch>
      <Switch>
        <Label className="text-sm">Label before</Label>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
      </Switch>
    </div>
  );
}

```

### With Icons

```tsx
"use client";

import {
  BellFill,
  BellSlash,
  Check,
  Microphone,
  MicrophoneSlash,
  Moon,
  Power,
  Sun,
  VolumeFill,
  VolumeSlashFill,
} from "@gravity-ui/icons";
import {Switch} from "@heroui/react";

export function WithIcons() {
  const icons = {
    check: {
      off: Power,
      on: Check,
      selectedControlClass: "bg-green-500/80",
    },
    darkMode: {
      off: Moon,
      on: Sun,
      selectedControlClass: "",
    },
    microphone: {
      off: Microphone,
      on: MicrophoneSlash,
      selectedControlClass: "bg-red-500/80",
    },
    notification: {
      off: BellSlash,
      on: BellFill,
      selectedControlClass: "bg-purple-500/80",
    },
    volume: {
      off: VolumeFill,
      on: VolumeSlashFill,
      selectedControlClass: "bg-blue-500/80",
    },
  };

return (
    <div className="flex gap-3">
      {Object.entries(icons).map(([key, value]) => (
        <Switch key={key} defaultSelected size="lg">
          {({isSelected}) => (
            <>
              <Switch.Control className={isSelected ? value.selectedControlClass : ""}>
                <Switch.Thumb>
                  <Switch.Icon>
                    {isSelected ? (
                      <value.on className="size-3 text-inherit opacity-100" />
                    ) : (
                      <value.off className="size-3 text-inherit opacity-70" />
                    )}
                  </Switch.Icon>
                </Switch.Thumb>
              </Switch.Control>
            </>
          )}
        </Switch>
      ))}
    </div>
  );
}

```

### With Description

```tsx
import {Description, Label, Switch} from "@heroui/react";

export function WithDescription() {
  return (
    <div className="max-w-sm">
      <Switch>
        <div className="flex gap-3">
          <Switch.Control>
            <Switch.Thumb />
          </Switch.Control>
          <div className="-mt-0.5 flex flex-col gap-1">
            <Label className="text-sm">Public profile</Label>
            <Description>Allow others to see your profile information</Description>
          </div>
        </div>
      </Switch>
    </div>
  );
}

```

### Group

```tsx
import {Label, Switch, SwitchGroup} from "@heroui/react";

export function Group() {
  return (
    <SwitchGroup>
      <Switch name="notifications">
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label className="text-sm">Allow Notifications</Label>
      </Switch>
      <Switch name="marketing">
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label className="text-sm">Marketing emails</Label>
      </Switch>
      <Switch name="social">
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label className="text-sm">Social media updates</Label>
      </Switch>
    </SwitchGroup>
  );
}

```

### Group Horizontal

```tsx
import {Label, Switch, SwitchGroup} from "@heroui/react";

export function GroupHorizontal() {
  return (
    <SwitchGroup className="overflow-x-auto" orientation="horizontal">
      <Switch name="notifications">
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label className="text-sm">Notifications</Label>
      </Switch>
      <Switch name="marketing">
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label className="text-sm">Marketing</Label>
      </Switch>
      <Switch name="social">
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label className="text-sm">Social</Label>
      </Switch>
    </SwitchGroup>
  );
}

```

### Render Props

```tsx
"use client";

import {Label, Switch} from "@heroui/react";

export function RenderProps() {
  return (
    <Switch>
      {({isSelected}) => (
        <>
          <Switch.Control>
            <Switch.Thumb />
          </Switch.Control>
          <Label className="text-sm">{isSelected ? "Enabled" : "Disabled"}</Label>
        </>
      )}
    </Switch>
  );
}

```

### Form Integration

```tsx
"use client";

import {Button, Label, Switch, SwitchGroup} from "@heroui/react";
import React from "react";

export function Form() {
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const formData = new FormData(e.target as HTMLFormElement);

alert(
      `Form submitted with:\n${Array.from(formData.entries())
        .map(([key, value]) => `${key}: ${value}`)
        .join("\n")}`,
    );
  };

return (
    <form className="flex flex-col gap-4" onSubmit={handleSubmit}>
      <SwitchGroup>
        <Switch name="notifications" value="on">
          <Switch.Control>
            <Switch.Thumb />
          </Switch.Control>
          <Label className="text-sm">Enable notifications</Label>
        </Switch>
        <Switch defaultSelected name="newsletter" value="on">
          <Switch.Control>
            <Switch.Thumb />
          </Switch.Control>
          <Label className="text-sm">Subscribe to newsletter</Label>
        </Switch>
        <Switch name="marketing" value="on">
          <Switch.Control>
            <Switch.Thumb />
          </Switch.Control>
          <Label className="text-sm">Receive marketing updates</Label>
        </Switch>
      </SwitchGroup>
      <Button className="mt-4" size="sm" type="submit" variant="primary">
        Submit
      </Button>
    </form>
  );
}

```

### Custom Styles

```tsx
"use client";

import {Check, Power} from "@gravity-ui/icons";
import {Switch} from "@heroui/react";

export function CustomStyles() {
  return (
    <Switch>
      {({isSelected}) => (
        <>
          <Switch.Control
            className={`h-[31px] w-[51px] bg-blue-500 ${isSelected ? "bg-cyan-500 shadow-[0_0_12px_rgba(6,182,212,0.5)]" : ""}`}
          >
            <Switch.Thumb
              className={`size-[27px] bg-white shadow-sm ${isSelected ? "ms-[22px] shadow-lg" : ""}`}
            >
              <Switch.Icon>
                {isSelected ? (
                  <Check className="size-4 text-cyan-600" />
                ) : (
                  <Power className="size-4 text-blue-600" />
                )}
              </Switch.Icon>
            </Switch.Thumb>
          </Switch.Control>
        </>
      )}
    </Switch>
  );
}

```

## Related Components

* **Label**: Accessible label for form controls
* **Description**: Helper text for form fields
* **Button**: Allows a user to perform an action

## Styling

### Passing Tailwind CSS classes

You can customize individual Switch components:

```tsx
import { Switch, Label } from '@heroui/react';

function CustomSwitch() {
  return (
    <Switch>
      {({isSelected}) => (
        <>
          <Switch.Control
            className={`h-[31px] w-[51px] bg-blue-500 ${isSelected ? "bg-cyan-500 shadow-[0_0_12px_rgba(6,182,212,0.5)]" : ""}`}
          >
            <Switch.Thumb
              className={`size-[27px] bg-white shadow-sm ${isSelected ? "translate-x-5 shadow-lg" : ""}`}
            />
          </Switch.Control>
          <Label>Custom Switch</Label>
        </>
      )}
    </Switch>
  );
}

```

Or customize the SwitchGroup layout:

```tsx
import { Switch, SwitchGroup, Label } from '@heroui/react';

function CustomSwitchGroup() {
  return (
    <SwitchGroup className="gap-8" orientation="horizontal">
      <Switch>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label>Option 1</Label>
      </Switch>
      <Switch>
        <Switch.Control>
          <Switch.Thumb />
        </Switch.Control>
        <Label>Option 2</Label>
      </Switch>
    </SwitchGroup>
  );
}

```

### Customizing the component classes

To customize the Switch component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .switch {
    @apply inline-flex gap-3 items-center;
  }

.switch__control {
    @apply h-5 w-8 bg-gray-400 data-[selected=true]:bg-blue-500;
  }

.switch__thumb {
    @apply bg-white shadow-sm;
  }

.switch__icon {
    @apply h-3 w-3 text-current;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

#### Switch Classes

The Switch component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch.css)):

* `.switch` - Base switch container
* `.switch__control` - Switch control track
* `.switch__thumb` - Switch thumb that moves
* `.switch__icon` - Optional icon inside the thumb
* `.switch--sm` - Small size variant
* `.switch--md` - Medium size variant (default)
* `.switch--lg` - Large size variant

#### SwitchGroup Classes

The SwitchGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch-group.css)):

* `.switch-group` - Switch group container
* `.switch-group__items` - Container for switch items
* `.switch-group--horizontal` - Horizontal layout
* `.switch-group--vertical` - Vertical layout (default)

### Interactive States

The switch supports both CSS pseudo-classes and data attributes for flexibility:

* **Selected**: `[data-selected="true"]` (thumb position and background color change)
* **Hover**: `:hover` or `[data-hovered="true"]`
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
* **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)
* **Pressed**: `:active` or `[data-pressed="true"]`

## API Reference

### Switch Props

Inherits from [React Aria Switch](https://react-spectrum.adobe.com/react-aria/Switch.html).

| Prop              | Type                                                                | Default | Description                                                       |
| ----------------- | ------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| `size`            | `'sm' \| 'md' \| 'lg'`                                              | `'md'`  | The size of the switch                                            |
| `isSelected`      | `boolean`                                                           | `false` | Whether the switch is on                                          |
| `defaultSelected` | `boolean`                                                           | `false` | Whether the switch is on by default (uncontrolled)                |
| `isDisabled`      | `boolean`                                                           | `false` | Whether the switch is disabled                                    |
| `name`            | `string`                                                            | -       | The name of the input element, used when submitting an HTML form  |
| `value`           | `string`                                                            | -       | The value of the input element, used when submitting an HTML form |
| `onChange`        | `(isSelected: boolean) => void`                                     | -       | Handler called when the switch value changes                      |
| `onPress`         | `(e: PressEvent) => void`                                           | -       | Handler called when the switch is pressed                         |
| `children`        | `React.ReactNode \| (values: SwitchRenderProps) => React.ReactNode` | -       | Switch content or render prop                                     |

### SwitchRenderProps

When using the render prop pattern, these values are provided:

| Prop             | Type      | Description                             |
| ---------------- | --------- | --------------------------------------- |
| `isSelected`     | `boolean` | Whether the switch is currently on      |
| `isHovered`      | `boolean` | Whether the switch is hovered           |
| `isPressed`      | `boolean` | Whether the switch is currently pressed |
| `isFocused`      | `boolean` | Whether the switch is focused           |
| `isFocusVisible` | `boolean` | Whether the switch is keyboard focused  |
| `isDisabled`     | `boolean` | Whether the switch is disabled          |
| `isReadOnly`     | `boolean` | Whether the switch is read only         |
| `state`          | `-`       | State of the switch.                    |

### SwitchGroup Props

| Prop          | Type                         | Default      | Description                         |
| ------------- | ---------------------------- | ------------ | ----------------------------------- |
| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | The orientation of the switch group |
| `children`    | `React.ReactNode`            | -            | The switch items to render          |
| `className`   | `string`                     | -            | Additional CSS class names          |

</page>

<page url="/docs/react/components/chip">
# Chip

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/chip
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(data-display)/chip.mdx
> Small informational badges for displaying labels, statuses, and categories

## Import

```tsx
import { Chip } from '@heroui/react';

```

### Usage

```tsx
import {Chip} from "@heroui/react";

```

### Variants

```tsx
import {CircleDashed} from "@gravity-ui/icons";
import {Chip, Separator} from "@heroui/react";
import React from "react";

export function ChipVariants() {
  const sizes = ["lg", "md", "sm"] as const;
  const variants = ["primary", "secondary", "tertiary", "soft"] as const;
  const colors = ["accent", "default", "success", "warning", "danger"] as const;

return (
    <div className="flex flex-col gap-8 overflow-x-auto">
      {sizes.map((size, index) => (
        <React.Fragment key={size}>
          <div className="flex flex-col gap-4">
            <h3 className="text-sm font-semibold text-muted capitalize">{size}</h3>
            {/* Color labels header */}
            <div className="flex items-center gap-3">
              <div className="w-24 shrink-0" />
              {colors.map((color) => (
                <div
                  key={color}
                  className="flex shrink-0 items-center justify-center"
                  style={{width: "130px"}}
                >
                  <span className="text-xs text-muted capitalize">{color}</span>
                </div>
              ))}
            </div>
            <div className="flex flex-col gap-3">
              {variants.map((variant) => (
                <div key={variant} className="flex items-center gap-3">
                  <div className="w-24 shrink-0 text-sm text-muted capitalize">{variant}</div>
                  {colors.map((color) => (
                    <div
                      key={color}
                      className="flex shrink-0 items-center justify-center"
                      style={{width: "130px"}}
                    >
                      <Chip color={color} size={size} variant={variant}>
                        <CircleDashed />
                        Label <CircleDashed />
                      </Chip>
                    </div>
                  ))}
                </div>
              ))}
            </div>
          </div>
          {index < sizes.length - 1 && <Separator />}
        </React.Fragment>
      ))}
    </div>
  );
}

```

### With Icons

```tsx
import {ChevronDown, CircleCheckFill, CircleFill, Clock, Xmark} from "@gravity-ui/icons";
import {Chip} from "@heroui/react";

export function ChipWithIcon() {
  return (
    <div className="flex flex-wrap items-center gap-3">
      <Chip>
        <CircleFill width={6} />
        Information
      </Chip>
      <Chip color="success">
        <CircleCheckFill width={12} />
        Completed
      </Chip>
      <Chip color="warning">
        <Clock width={12} />
        Pending
      </Chip>
      <Chip color="danger">
        <Xmark width={12} />
        Failed
      </Chip>
      <Chip color="accent">
        Label
        <ChevronDown width={12} />
      </Chip>
    </div>
  );
}

```

### Statuses

```tsx
import {Ban, Check, CircleFill, CircleInfo, TriangleExclamation} from "@gravity-ui/icons";
import {Chip} from "@heroui/react";

export function ChipStatuses() {
  return (
    <div className="flex flex-col gap-4">
      <div className="flex flex-wrap items-center gap-3">
        <Chip variant="primary">
          <CircleFill width={6} />
          Default
        </Chip>
        <Chip color="success" variant="primary">
          <CircleFill width={6} />
          Active
        </Chip>
        <Chip color="warning" variant="primary">
          <CircleFill width={6} />
          Pending
        </Chip>
        <Chip color="danger" variant="primary">
          <CircleFill width={6} />
          Inactive
        </Chip>
      </div>

<div className="flex flex-wrap items-center gap-3">
        <Chip>
          <CircleInfo width={12} />
          New Feature
        </Chip>
        <Chip color="success">
          <Check width={12} />
          Available
        </Chip>
        <Chip color="warning">
          <TriangleExclamation width={12} />
          Beta
        </Chip>
        <Chip color="danger">
          <Ban width={12} />
          Deprecated
        </Chip>
      </div>
    </div>
  );
}

```

## Related Components

* **Avatar**: Display user profile images
* **CloseButton**: Button for dismissing overlays
* **Separator**: Visual divider between content

## Styling

### Passing Tailwind CSS classes

```tsx
import {Chip} from '@heroui/react';

function CustomChip() {
  return (
    <Chip className="rounded-full px-4 py-2 font-bold">
      Custom Styled
    </Chip>
  );
}

```

### Customizing the component classes

To customize the Chip component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .chip {
    @apply rounded-full text-xs;
  }

.chip--accent {
    @apply border-accent/20;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The Chip component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/chip.css)):

#### Base Classes

* `.chip` - Base chip styles

#### Color Classes

* `.chip--accent` - Accent color variant
* `.chip--danger` - Danger color variant
* `.chip--default` - Default color variant
* `.chip--success` - Success color variant
* `.chip--warning` - Warning color variant

#### Variant Classes

* `.chip--primary` - Primary variant with filled background
* `.chip--secondary` - Secondary variant with border
* `.chip--tertiary` - Tertiary variant with transparent background
* `.chip--soft` - Soft variant with lighter background

#### Size Classes

* `.chip--sm` - Small size
* `.chip--md` - Medium size (default)
* `.chip--lg` - Large size

#### Compound Variant Classes

Chips support combining variant and color classes (e.g., `.chip--secondary.chip--accent`). The following combinations have default styles defined:

**Primary Variants:**

* `.chip--primary.chip--accent` - Primary accent combination with filled background
* `.chip--primary.chip--success` - Primary success combination with filled background
* `.chip--primary.chip--warning` - Primary warning combination with filled background
* `.chip--primary.chip--danger` - Primary danger combination with filled background

**Soft Variants:**

* `.chip--accent.chip--soft` - Soft accent combination with lighter background
* `.chip--success.chip--soft` - Soft success combination with lighter background
* `.chip--warning.chip--soft` - Soft warning combination with lighter background
* `.chip--danger.chip--soft` - Soft danger combination with lighter background

**Note:** You can apply custom styles to any variant-color combination (e.g., `.chip--secondary.chip--accent`, `.chip--tertiary.chip--success`) using the `@layer components` directive in your CSS.

## API Reference

### Chip Props

| Prop        | Type                                                          | Default       | Description                        |
| ----------- | ------------------------------------------------------------- | ------------- | ---------------------------------- |
| `children`  | `React.ReactNode`                                             | -             | Content to display inside the chip |
| `className` | `string`                                                      | -             | Additional CSS classes             |
| `color`     | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"`   | Color variant of the chip          |
| `variant`   | `"primary" \| "secondary" \| "tertiary" \| "soft"`            | `"secondary"` | Visual style variant               |
| `size`      | `"sm" \| "md" \| "lg"`                                        | `"md"`        | Size of the chip                   |

</page>

<page url="/docs/react/components/alert">
# Alert

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/alert
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(feedback)/alert.mdx
> Display important messages and notifications to users with status indicators

## Import

```tsx
import { Alert } from '@heroui/react';

```

### Usage

```tsx
import {Alert, Button, CloseButton, Spinner} from "@heroui/react";
import React from "react";

```

### Anatomy

Import the Alert component and access all parts using dot notation.

```tsx
import { Alert } from '@heroui/react';

export default () => (
  <Alert>
    <Alert.Indicator />
    <Alert.Content>
      <Alert.Title />
      <Alert.Description />
    </Alert.Content>
  </Alert>
)

```

## Related Components

* **CloseButton**: Button for dismissing overlays
* **Button**: Allows a user to perform an action
* **Spinner**: Loading indicator

## Styling

### Passing Tailwind CSS classes

```tsx
import { Alert } from "@heroui/react";

function CustomAlert() {
  return (
    <Alert className="border-2 border-blue-500 rounded-xl" status="accent">
      <Alert.Indicator className="text-blue-600" />
      <Alert.Content className="gap-1">
        <Alert.Title className="font-bold text-lg">Custom Alert</Alert.Title>
        <Alert.Description className="text-sm opacity-80">
          This alert has custom styling applied
        </Alert.Description>
      </Alert.Content>
    </Alert>
  );
}

```

### Customizing the component classes

To customize the Alert component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .alert {
    @apply rounded-2xl shadow-lg;
  }

.alert__title {
    @apply font-bold text-lg;
  }

.alert--danger {
    @apply border-l-4 border-red-600;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The Alert component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert.css)):

#### Base Classes

* `.alert` - Base alert container
* `.alert__indicator` - Icon/indicator container
* `.alert__content` - Content wrapper for title and description
* `.alert__title` - Alert title text
* `.alert__description` - Alert description text

#### Status Variant Classes

* `.alert--default` - Default gray status
* `.alert--accent` - Accent blue status
* `.alert--success` - Success green status
* `.alert--warning` - Warning yellow/orange status
* `.alert--danger` - Danger red status

### Interactive States

The Alert component is primarily informational and doesn't have interactive states on the base component. However, it can contain interactive elements like buttons or close buttons.

## API Reference

### Alert Props

| Prop        | Type                                                          | Default     | Description                    |
| ----------- | ------------------------------------------------------------- | ----------- | ------------------------------ |
| `status`    | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | The visual status of the alert |
| `className` | `string`                                                      | -           | Additional CSS classes         |
| `children`  | `ReactNode`                                                   | -           | The alert content              |

### Alert.Indicator Props

| Prop        | Type        | Default | Description                                     |
| ----------- | ----------- | ------- | ----------------------------------------------- |
| `className` | `string`    | -       | Additional CSS classes                          |
| `children`  | `ReactNode` | -       | Custom indicator icon (defaults to status icon) |

### Alert.Content Props

| Prop        | Type        | Default | Description                               |
| ----------- | ----------- | ------- | ----------------------------------------- |
| `className` | `string`    | -       | Additional CSS classes                    |
| `children`  | `ReactNode` | -       | Content (typically Title and Description) |

### Alert.Title Props

| Prop        | Type        | Default | Description            |
| ----------- | ----------- | ------- | ---------------------- |
| `className` | `string`    | -       | Additional CSS classes |
| `children`  | `ReactNode` | -       | The alert title text   |

### Alert.Description Props

| Prop        | Type        | Default | Description                |
| ----------- | ----------- | ------- | -------------------------- |
| `className` | `string`    | -       | Additional CSS classes     |
| `children`  | `ReactNode` | -       | The alert description text |

</page>

<page url="/docs/react/components/skeleton">
# Skeleton

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/skeleton
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(feedback)/skeleton.mdx
> Skeleton is a placeholder to show a loading state and the expected shape of a component.

## Import

```tsx
import { Skeleton } from '@heroui/react';

```

### Usage

```tsx
import {Skeleton} from "@heroui/react";

export function Basic() {
  return (
    <div className="shadow-panel w-[250px] space-y-5 rounded-lg bg-transparent p-4">
      <Skeleton className="h-32 rounded-lg" />
      <div className="space-y-3">
        <Skeleton className="h-3 w-3/5 rounded-lg" />
        <Skeleton className="h-3 w-4/5 rounded-lg" />
        <Skeleton className="h-3 w-2/5 rounded-lg" />
      </div>
    </div>
  );
}

```

### Text Content

```tsx
import {Skeleton} from "@heroui/react";

export function TextContent() {
  return (
    <div className="w-full max-w-md space-y-3">
      <Skeleton className="h-4 w-full rounded" />
      <Skeleton className="h-4 w-5/6 rounded" />
      <Skeleton className="h-4 w-4/6 rounded" />
      <Skeleton className="h-4 w-full rounded" />
      <Skeleton className="h-4 w-3/6 rounded" />
    </div>
  );
}

```

### User Profile

```tsx
import {Skeleton} from "@heroui/react";

export function UserProfile() {
  return (
    <div className="flex items-center gap-3">
      <Skeleton className="h-10 w-10 shrink-0 rounded-full" />
      <div className="flex-1 space-y-2">
        <Skeleton className="h-3 w-36 rounded-lg" />
        <Skeleton className="h-3 w-24 rounded-lg" />
      </div>
    </div>
  );
}

```

### List Items

```tsx
import {Skeleton} from "@heroui/react";

export function List() {
  return (
    <div className="w-full max-w-sm space-y-4">
      {Array.from({length: 3}).map((_, index) => (
        <div key={index} className="flex items-center gap-3">
          <Skeleton className="h-10 w-10 shrink-0 rounded-lg" />
          <div className="flex-1 space-y-2">
            <Skeleton className="h-3 w-full rounded" />
            <Skeleton className="h-3 w-4/5 rounded" />
          </div>
        </div>
      ))}
    </div>
  );
}

```

### Animation Types

```tsx
import {Skeleton} from "@heroui/react";

export function AnimationTypes() {
  return (
    <div className="grid w-full max-w-xl grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3">
      <div className="space-y-2">
        <p className="truncate text-xs text-muted">Shimmer</p>
        <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4">
          <Skeleton animationType="shimmer" className="h-20 rounded-lg" />
          <Skeleton animationType="shimmer" className="h-3 w-3/5 rounded-lg" />
          <Skeleton animationType="shimmer" className="h-3 w-4/5 rounded-lg" />
        </div>
      </div>

<div className="space-y-2">
        <p className="truncate text-xs text-muted">Pulse</p>
        <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4">
          <Skeleton animationType="pulse" className="h-20 rounded-lg" />
          <Skeleton animationType="pulse" className="h-3 w-3/5 rounded-lg" />
          <Skeleton animationType="pulse" className="h-3 w-4/5 rounded-lg" />
        </div>
      </div>

<div className="space-y-2">
        <p className="truncate text-xs text-muted">None</p>
        <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4">
          <Skeleton animationType="none" className="h-20 rounded-lg" />
          <Skeleton animationType="none" className="h-3 w-3/5 rounded-lg" />
          <Skeleton animationType="none" className="h-3 w-4/5 rounded-lg" />
        </div>
      </div>
    </div>
  );
}

```

### Grid

```tsx
import {Skeleton} from "@heroui/react";

export function Grid() {
  return (
    <div className="grid w-full max-w-xl grid-cols-3 gap-4">
      <Skeleton className="h-24 rounded-xl" />
      <Skeleton className="h-24 rounded-xl" />
      <Skeleton className="h-24 rounded-xl" />
    </div>
  );
}

```

### Single Shimmer

A synchronized shimmer effect that passes over all skeleton elements at once. Apply the `skeleton--shimmer` class to a parent container and set `animationType="none"` on child skeletons.

```tsx
import {Skeleton} from "@heroui/react";

export function SingleShimmer() {
  return (
    <div className="skeleton--shimmer relative grid w-full max-w-xl grid-cols-3 gap-4 overflow-hidden rounded-xl">
      <Skeleton animationType="none" className="h-24 rounded-xl" />
      <Skeleton animationType="none" className="h-24 rounded-xl" />
      <Skeleton animationType="none" className="h-24 rounded-xl" />
    </div>
  );
}

```

## Related Components

* **Card**: Content container with header, body, and footer
* **Avatar**: Display user profile images

## Styling

### Global Animation Configuration

You can set a default animation type for all Skeleton components in your application by defining the `--skeleton-animation` CSS variable:

```css
/* In your global CSS file */
:root {
  /* Possible values: shimmer, pulse, none */
  --skeleton-animation: pulse;
}

/* You can also set different values for light/dark themes */
.light, [data-theme="light"] {
  --skeleton-animation: shimmer;
}

.dark, [data-theme="dark"] {
  --skeleton-animation: pulse;
}

```

This global setting will be overridden by the `animationType` prop when specified on individual components.

### Passing Tailwind CSS classes

```tsx
import { Skeleton } from '@heroui/react';

function CustomSkeleton() {
  return (
    <Skeleton className="h-20 w-32 rounded-full" />
  );
}

```

### Customizing the component classes

To customize the Skeleton component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  /* Base skeleton styles */
  .skeleton {
    @apply bg-surface-secondary/50; /* Change base background */
  }

/* Shimmer animation gradient */
  .skeleton--shimmer:before {
    @apply viasurface; /* Change shimmer gradient color */
  }

/* Pulse animation */
  .skeleton--pulse {
    @apply animate-pulse opacity-75; /* Customize pulse animation */
  }

/* No animation variant */
  .skeleton--none {
    @apply opacity-50; /* Style for static skeleton */
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The Skeleton component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/skeleton.css)):

#### Base Class

`.skeleton` - Base skeleton styles with background and rounded corners

#### Animation Variant Classes

* `.skeleton--shimmer` - Adds shimmer animation with gradient effect (default)
* `.skeleton--pulse` - Adds pulse animation using Tailwind's animate-pulse
* `.skeleton--none` - No animation, static skeleton

### Animation

The Skeleton component supports three animation types, each with different visual effects:

#### Shimmer Animation

The shimmer effect creates a gradient that moves across the skeleton element:

```css
.skeleton--shimmer:before {
  @apply animate-skeleton via-surface-3 absolute inset-0 -translate-x-full
         bg-gradient-to-r from-transparent to-transparent content-[''];
}

```

The shimmer animation is defined in the theme using:

```css
@theme inline {
  --animate-skeleton: skeleton 2s linear infinite;

@keyframes skeleton {
    100% {
      transform: translateX(200%);
    }
  }
}

```

#### Pulse Animation

The pulse animation uses Tailwind's built-in `animate-pulse` utility:

```css
.skeleton--pulse {
  @apply animate-pulse;
}

```

#### No Animation

For static skeletons without any animation:

```css
.skeleton--none {
  /* No animation styles applied */
}

```

## API Reference

### Skeleton Props

| Prop            | Type                             | Default                     | Description                                                                                             |
| --------------- | -------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------- |
| `animationType` | `"shimmer" \| "pulse" \| "none"` | `"shimmer"` or CSS variable | The animation type for the skeleton. Can be globally configured via `--skeleton-animation` CSS variable |
| `className`     | `string`                         | -                           | Additional CSS classes                                                                                  |

</page>

<page url="/docs/react/components/spinner">
# Spinner

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/spinner
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(feedback)/spinner.mdx
> A loading indicator component to show pending states

## Import

```tsx
import { Spinner } from '@heroui/react';

```

### Usage

```tsx
import {Spinner} from "@heroui/react";

export function SpinnerBasic() {
  return (
    <div className="flex items-center gap-4">
      <Spinner />
    </div>
  );
}

```

### Colors

```tsx
import {Spinner} from "@heroui/react";

export function SpinnerColors() {
  return (
    <div className="flex items-center gap-8">
      <div className="flex flex-col items-center gap-2">
        <Spinner color="current" />
        <span className="text-xs text-muted">Current</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <Spinner color="accent" />
        <span className="text-xs text-muted">Accent</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <Spinner color="success" />
        <span className="text-xs text-muted">Success</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <Spinner color="warning" />
        <span className="text-xs text-muted">Warning</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <Spinner color="danger" />
        <span className="text-xs text-muted">Danger</span>
      </div>
    </div>
  );
}

```

### Sizes

```tsx
import {Spinner} from "@heroui/react";

export function SpinnerSizes() {
  return (
    <div className="flex items-center gap-8">
      <div className="flex flex-col items-center gap-2">
        <Spinner size="sm" />
        <span className="text-xs text-muted">Small</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <Spinner size="md" />
        <span className="text-xs text-muted">Medium</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <Spinner size="lg" />
        <span className="text-xs text-muted">Large</span>
      </div>
      <div className="flex flex-col items-center gap-2">
        <Spinner size="xl" />
        <span className="text-xs text-muted">Extra Large</span>
      </div>
    </div>
  );
}

```

## Styling

### Passing Tailwind CSS classes

```tsx
import {Spinner} from '@heroui/react';

function CustomSpinner() {
  return (
    <Spinner className="text-blue-500" />
  );
}

```

### Customizing the component classes

To customize the Spinner component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .spinner {
    @apply animate-spin;
  }

.spinner--accent {
    color: var(--accent);
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The Spinner component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/spinner.css)):

#### Base & Size Classes

* `.spinner` - Base spinner styles with default size
* `.spinner--sm` - Small size variant
* `.spinner--md` - Medium size variant (default)
* `.spinner--lg` - Large size variant
* `.spinner--xl` - Extra large size variant

#### Color Classes

* `.spinner--current` - Inherits current text color
* `.spinner--accent` - Accent color variant
* `.spinner--danger` - Danger color variant
* `.spinner--success` - Success color variant
* `.spinner--warning` - Warning color variant

## API Reference

### Spinner Props

| Prop        | Type                                                          | Default     | Description                  |
| ----------- | ------------------------------------------------------------- | ----------- | ---------------------------- |
| `size`      | `"sm" \| "md" \| "lg" \| "xl"`                                | `"md"`      | Size of the spinner          |
| `color`     | `"current" \| "accent" \| "success" \| "warning" \| "danger"` | `"current"` | Color variant of the spinner |
| `className` | `string`                                                      | -           | Additional CSS classes       |

</page>

<page url="/docs/react/components/checkbox-group">
# CheckboxGroup

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/checkbox-group
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/checkbox-group.mdx
> A checkbox group component for managing multiple checkbox selections

## Import

```tsx
import { CheckboxGroup, Checkbox, Label, Description } from '@heroui/react';

```

### Usage

```tsx
import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";

```

### Anatomy

Import the CheckboxGroup component and access all parts using dot notation.

```tsx
import {CheckboxGroup, Checkbox, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <CheckboxGroup name="interests">
    <Label />
    <Description /> {/* Optional */}
    <Checkbox value="option1">
      <Checkbox.Control>
        <Checkbox.Indicator />
      </Checkbox.Control>
      <Checkbox.Content>
        <Label />
        <Description /> {/* Optional */}
      </Checkbox.Content>
    </Checkbox>
    <FieldError /> {/* Optional */}
  </CheckboxGroup>
);

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, CheckboxGroup automatically applies on-surface styling.

```tsx
import {Checkbox, CheckboxGroup, Description, Label, Surface} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="w-full rounded-3xl p-6">
      <CheckboxGroup name="interests">
        <Label>Select your interests</Label>
        <Description>Choose all that apply</Description>
        <Checkbox value="coding">
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          <Checkbox.Content>
            <Label>Coding</Label>
            <Description>Love building software</Description>
          </Checkbox.Content>
        </Checkbox>
        <Checkbox value="design">
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          <Checkbox.Content>
            <Label>Design</Label>
            <Description>Enjoy creating beautiful interfaces</Description>
          </Checkbox.Content>
        </Checkbox>
        <Checkbox value="writing">
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          <Checkbox.Content>
            <Label>Writing</Label>
            <Description>Passionate about content creation</Description>
          </Checkbox.Content>
        </Checkbox>
      </CheckboxGroup>
    </Surface>
  );
}

```

### With Custom Indicator

```tsx
"use client";

import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";

export function WithCustomIndicator() {
  return (
    <CheckboxGroup name="features">
      <Label>Features</Label>
      <Description>Select the features you want</Description>
      <Checkbox value="notifications">
        <Checkbox.Control>
          <Checkbox.Indicator>
            {({isSelected}) =>
              isSelected ? (
                <svg
                  aria-hidden="true"
                  fill="none"
                  stroke="currentColor"
                  strokeLinecap="round"
                  strokeWidth={2}
                  viewBox="0 0 24 24"
                >
                  <path d="M6 18L18 6M6 6l12 12" />
                </svg>
              ) : null
            }
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Email notifications</Label>
          <Description>Receive updates via email</Description>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="newsletter">
        <Checkbox.Control>
          <Checkbox.Indicator>
            {({isSelected}) =>
              isSelected ? (
                <svg
                  aria-hidden="true"
                  fill="none"
                  stroke="currentColor"
                  strokeLinecap="round"
                  strokeWidth={2}
                  viewBox="0 0 24 24"
                >
                  <path d="M6 18L18 6M6 6l12 12" />
                </svg>
              ) : null
            }
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Newsletter</Label>
          <Description>Get weekly newsletters</Description>
        </Checkbox.Content>
      </Checkbox>
    </CheckboxGroup>
  );
}

```

### Indeterminate

```tsx
"use client";

import {Checkbox, CheckboxGroup, Label} from "@heroui/react";
import {useState} from "react";

export function Indeterminate() {
  const [selected, setSelected] = useState(["coding"]);
  const allOptions = ["coding", "design", "writing"];

return (
    <div>
      <Checkbox
        isIndeterminate={selected.length > 0 && selected.length < allOptions.length}
        isSelected={selected.length === allOptions.length}
        name="select-all"
        onChange={(isSelected: boolean) => {
          setSelected(isSelected ? allOptions : []);
        }}
      >
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Select all</Label>
        </Checkbox.Content>
      </Checkbox>
      <div className="ml-6 flex flex-col gap-2">
        <CheckboxGroup value={selected} onChange={setSelected}>
          <Checkbox value="coding">
            <Checkbox.Control>
              <Checkbox.Indicator />
            </Checkbox.Control>
            <Checkbox.Content>
              <Label>Coding</Label>
            </Checkbox.Content>
          </Checkbox>
          <Checkbox value="design">
            <Checkbox.Control>
              <Checkbox.Indicator />
            </Checkbox.Control>
            <Checkbox.Content>
              <Label>Design</Label>
            </Checkbox.Content>
          </Checkbox>
          <Checkbox value="writing">
            <Checkbox.Control>
              <Checkbox.Indicator />
            </Checkbox.Control>
            <Checkbox.Content>
              <Label>Writing</Label>
            </Checkbox.Content>
          </Checkbox>
        </CheckboxGroup>
      </div>
    </div>
  );
}

```

### Controlled

```tsx
"use client";

import {Checkbox, CheckboxGroup, Label} from "@heroui/react";
import {useState} from "react";

export function Controlled() {
  const [selected, setSelected] = useState(["coding", "design"]);

return (
    <CheckboxGroup className="min-w-[320px]" name="skills" value={selected} onChange={setSelected}>
      <Label>Your skills</Label>
      <Checkbox value="coding">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Coding</Label>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="design">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Design</Label>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="writing">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Writing</Label>
        </Checkbox.Content>
      </Checkbox>
      <Label className="my-4 text-sm text-muted">Selected: {selected.join(", ") || "None"}</Label>
    </CheckboxGroup>
  );
}

```

### Validation

```tsx
"use client";

import {Button, Checkbox, CheckboxGroup, FieldError, Form, Label} from "@heroui/react";

export function Validation() {
  return (
    <Form
      className="flex flex-col gap-4 px-4"
      onSubmit={(e) => {
        e.preventDefault();

const formData = new FormData(e.currentTarget);
        const values = formData.getAll("preferences");

alert(`Selected preferences: ${values.join(", ")}`);
      }}
    >
      <CheckboxGroup isRequired name="preferences">
        <Label>Preferences</Label>
        <Checkbox value="email">
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          <Checkbox.Content>
            <Label>Email notifications</Label>
          </Checkbox.Content>
        </Checkbox>
        <Checkbox value="sms">
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          <Checkbox.Content>
            <Label>SMS notifications</Label>
          </Checkbox.Content>
        </Checkbox>
        <Checkbox value="push">
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          <Checkbox.Content>
            <Label>Push notifications</Label>
          </Checkbox.Content>
        </Checkbox>
        <FieldError>Please select at least one notification method.</FieldError>
      </CheckboxGroup>
      <Button type="submit">Submit</Button>
    </Form>
  );
}

```

### Disabled

```tsx
import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";

export function Disabled() {
  return (
    <CheckboxGroup isDisabled name="disabled-features">
      <Label>Features</Label>
      <Description>Feature selection is temporarily disabled</Description>
      <Checkbox value="feature1">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Feature 1</Label>
          <Description>This feature is coming soon</Description>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox value="feature2">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Feature 2</Label>
          <Description>This feature is coming soon</Description>
        </Checkbox.Content>
      </Checkbox>
    </CheckboxGroup>
  );
}

```

### Features and Add-ons Example

```tsx
import {Bell, Comment, Envelope} from "@gravity-ui/icons";
import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react";
import clsx from "clsx";

export function FeaturesAndAddOns() {
  const addOns = [
    {
      description: "Receive updates via email",
      icon: Envelope,
      title: "Email Notifications",
      value: "email",
    },
    {
      description: "Get instant SMS notifications",
      icon: Comment,
      title: "SMS Alerts",
      value: "sms",
    },
    {
      description: "Browser and mobile push alerts",
      icon: Bell,
      title: "Push Notifications",
      value: "push",
    },
  ];

return (
    <div className="flex w-full flex-col items-center gap-10 px-4 py-8">
      <section className="flex w-full min-w-[320px] flex-col gap-4">
        <CheckboxGroup name="notification-preferences">
          <Label>Notification preferences</Label>
          <Description>Choose how you want to receive updates</Description>
          <div className="flex flex-col gap-2">
            {addOns.map((addon) => (
              <Checkbox
                key={addon.value}
                isOnSurface
                value={addon.value}
                className={clsx(
                  "group relative flex-col gap-4 rounded-3xl bg-surface px-5 py-4 transition-all",
                  "data-[selected=true]:bg-accent/10",
                )}
              >
                <Checkbox.Control className="absolute top-3 right-4 size-5 rounded-full before:rounded-full">
                  <Checkbox.Indicator />
                </Checkbox.Control>
                <Checkbox.Content className="flex flex-row items-start justify-start gap-4">
                  <addon.icon className="size-5 text-accent" />
                  <div className="flex flex-col gap-1">
                    <Label>{addon.title}</Label>
                    <Description>{addon.description}</Description>
                  </div>
                </Checkbox.Content>
              </Checkbox>
            ))}
          </div>
        </CheckboxGroup>
      </section>
    </div>
  );
}

```

## Related Components

* **Checkbox**: Binary choice input control
* **Label**: Accessible label for form controls
* **Fieldset**: Group related form controls with legends

## Styling

### Passing Tailwind CSS classes

You can customize the CheckboxGroup component:

```tsx
import { CheckboxGroup, Checkbox, Label } from '@heroui/react';

function CustomCheckboxGroup() {
  return (
    <CheckboxGroup className="gap-4" name="custom">
      <Checkbox value="option1">
        <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
          <Checkbox.Indicator className="text-white" />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Option 1</Label>
        </Checkbox.Content>
      </Checkbox>
    </CheckboxGroup>
  );
}

```

### Customizing the component classes

To customize the CheckboxGroup component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .checkbox-group {
    @apply flex flex-col gap-2;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The CheckboxGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox-group.css)):

* `.checkbox-group` - Base checkbox group container

## API Reference

### CheckboxGroup Props

Inherits from [React Aria CheckboxGroup](https://react-spectrum.adobe.com/react-aria/CheckboxGroup.html).

| Prop           | Type                                                                       | Default | Description                                                       |
| -------------- | -------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| `value`        | `string[]`                                                                 | -       | The current selected values (controlled)                          |
| `defaultValue` | `string[]`                                                                 | -       | The default selected values (uncontrolled)                        |
| `onChange`     | `(value: string[]) => void`                                                | -       | Handler called when the selected values change                    |
| `isDisabled`   | `boolean`                                                                  | `false` | Whether the checkbox group is disabled                            |
| `isRequired`   | `boolean`                                                                  | `false` | Whether the checkbox group is required                            |
| `isReadOnly`   | `boolean`                                                                  | `false` | Whether the checkbox group is read only                           |
| `isInvalid`    | `boolean`                                                                  | `false` | Whether the checkbox group is in an invalid state                 |
| `name`         | `string`                                                                   | -       | The name of the checkbox group, used when submitting an HTML form |
| `children`     | `React.ReactNode \| (values: CheckboxGroupRenderProps) => React.ReactNode` | -       | Checkbox group content or render prop                             |

### CheckboxGroupRenderProps

When using the render prop pattern, these values are provided:

| Prop         | Type       | Description                                       |
| ------------ | ---------- | ------------------------------------------------- |
| `value`      | `string[]` | The currently selected values                     |
| `isDisabled` | `boolean`  | Whether the checkbox group is disabled            |
| `isReadOnly` | `boolean`  | Whether the checkbox group is read only           |
| `isInvalid`  | `boolean`  | Whether the checkbox group is in an invalid state |
| `isRequired` | `boolean`  | Whether the checkbox group is required            |

</page>

<page url="/docs/react/components/checkbox">
# Checkbox

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/checkbox
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/checkbox.mdx
> Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.

## Import

```tsx
import { Checkbox, Label } from '@heroui/react';

```

### Usage

```tsx
import {Checkbox, Label} from "@heroui/react";

```

### Anatomy

Import the Checkbox component and access all parts using dot notation.

```tsx
import { Checkbox, Label, Description } from '@heroui/react';

export default () => (
  <Checkbox name="terms">
    <Checkbox.Control>
      <Checkbox.Indicator />  
    </Checkbox.Control>
    <Checkbox.Content>
      <Label />
      <Description /> {/* Optional */}
    </Checkbox.Content>
  </Checkbox>
);

```

### Disabled

```tsx
import {Checkbox, Description, Label} from "@heroui/react";

export function Disabled() {
  return (
    <div className="flex gap-3">
      <Checkbox isDisabled className="mt-0.5" id="feature">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
      </Checkbox>
      <div className="flex flex-col gap-1">
        <Label htmlFor="feature">Premium Feature</Label>
        <Description>This feature is coming soon</Description>
      </div>
    </div>
  );
}

```

### Default Selected

```tsx
import {Checkbox, Label} from "@heroui/react";

export function DefaultSelected() {
  return (
    <div className="flex items-center gap-3">
      <Checkbox defaultSelected id="default-notifications">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
      </Checkbox>
      <Label htmlFor="default-notifications">Enable email notifications</Label>
    </div>
  );
}

```

### Controlled

```tsx
"use client";

import {Checkbox, Label} from "@heroui/react";
import {useState} from "react";

export function Controlled() {
  const [isSelected, setIsSelected] = useState(true);

return (
    <div className="flex flex-col gap-3">
      <div className="flex items-center gap-3">
        <Checkbox id="email-notifications" isSelected={isSelected} onChange={setIsSelected}>
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
        </Checkbox>
        <Label htmlFor="email-notifications">Email notifications</Label>
      </div>
      <p className="text-sm text-muted">
        Status: <span className="font-medium">{isSelected ? "Enabled" : "Disabled"}</span>
      </p>
    </div>
  );
}

```

### Indeterminate

```tsx
"use client";

import {Checkbox, Description, Label} from "@heroui/react";
import {useState} from "react";

export function Indeterminate() {
  const [isIndeterminate, setIsIndeterminate] = useState(true);
  const [isSelected, setIsSelected] = useState(false);

return (
    <div className="flex gap-3">
      <Checkbox
        className="mt-0.5"
        id="select-all"
        isIndeterminate={isIndeterminate}
        isSelected={isSelected}
        onChange={(selected: boolean) => {
          setIsSelected(selected);
          setIsIndeterminate(false);
        }}
      >
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
      </Checkbox>
      <div className="flex flex-col gap-1">
        <Label htmlFor="select-all">Select all</Label>
        <Description>Shows indeterminate state (dash icon)</Description>
      </div>
    </div>
  );
}

```

### With Label

```tsx
import {Checkbox, Label} from "@heroui/react";

export function WithLabel() {
  return (
    <Checkbox id="label-marketing">
      <Checkbox.Control>
        <Checkbox.Indicator />
      </Checkbox.Control>
      <Checkbox.Content>
        <Label htmlFor="label-marketing">Send me marketing emails</Label>
      </Checkbox.Content>
    </Checkbox>
  );
}

```

### With Description

```tsx
import {Checkbox, Description, Label} from "@heroui/react";

export function WithDescription() {
  return (
    <div className="flex gap-3">
      <Checkbox className="mt-0.5" id="description-notifications">
        <Checkbox.Control>
          <Checkbox.Indicator />
        </Checkbox.Control>
      </Checkbox>
      <div className="flex flex-col gap-1">
        <Label htmlFor="description-notifications">Email notifications</Label>
        <Description>Get notified when someone mentions you in a comment</Description>
      </div>
    </div>
  );
}

```

### Render Props

```tsx
"use client";

import {Checkbox, Description, Label} from "@heroui/react";

export function RenderProps() {
  return (
    <Checkbox id="render-props-terms">
      {({isSelected}) => (
        <>
          <Checkbox.Control>
            <Checkbox.Indicator />
          </Checkbox.Control>
          <Checkbox.Content>
            <Label htmlFor="render-props-terms">
              {isSelected ? "Terms accepted" : "Accept terms"}
            </Label>
            <Description>
              {isSelected ? "Thank you for accepting" : "Please read and accept the terms"}
            </Description>
          </Checkbox.Content>
        </>
      )}
    </Checkbox>
  );
}

```

### Form Integration

```tsx
"use client";

import {Button, Checkbox, Label} from "@heroui/react";
import React from "react";

export function Form() {
  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    const formData = new FormData(e.target as HTMLFormElement);

alert(
      `Form submitted with:\n${Array.from(formData.entries())
        .map(([key, value]) => `${key}: ${value}`)
        .join("\n")}`,
    );
  };

return (
    <form className="flex flex-col gap-4" onSubmit={handleSubmit}>
      <div className="flex flex-col gap-3">
        <div className="flex items-center gap-3">
          <Checkbox id="form-notifications" name="notifications" value="on">
            <Checkbox.Control>
              <Checkbox.Indicator />
            </Checkbox.Control>
          </Checkbox>
          <Label htmlFor="form-notifications">Enable notifications</Label>
        </div>
        <div className="flex items-center gap-3">
          <Checkbox defaultSelected id="form-newsletter" name="newsletter" value="on">
            <Checkbox.Control>
              <Checkbox.Indicator />
            </Checkbox.Control>
          </Checkbox>
          <Label htmlFor="form-newsletter">Subscribe to newsletter</Label>
        </div>
        <div className="flex items-center gap-3">
          <Checkbox id="form-marketing" name="marketing" value="on">
            <Checkbox.Control>
              <Checkbox.Indicator />
            </Checkbox.Control>
          </Checkbox>
          <Label htmlFor="form-marketing">Receive marketing updates</Label>
        </div>
      </div>
      <Button className="mt-4" size="sm" type="submit" variant="primary">
        Submit
      </Button>
    </form>
  );
}

```

### Invalid

```tsx
import {Checkbox, Description, Label} from "@heroui/react";

export function Invalid() {
  return (
    <Checkbox isInvalid name="agreement">
      <Checkbox.Control>
        <Checkbox.Indicator />
      </Checkbox.Control>
      <Checkbox.Content>
        <Label>I agree to the terms</Label>
        <Description>You must accept the terms to continue</Description>
      </Checkbox.Content>
    </Checkbox>
  );
}

```

### Custom Indicator

```tsx
"use client";

import {Checkbox, Label} from "@heroui/react";

export function CustomIndicator() {
  return (
    <div className="flex gap-4">
      <Checkbox defaultSelected name="heart">
        <Checkbox.Control>
          <Checkbox.Indicator>
            {({isSelected}) =>
              isSelected ? (
                <svg fill="currentColor" viewBox="0 0 24 24">
                  <path
                    d="M12.62 20.81c-.34.12-.9.12-1.24 0C8.48 19.82 2 15.69 2 8.69 2 5.6 4.49 3.1 7.56 3.1c1.82 0 3.43.88 4.44 2.24a5.53 5.53 0 0 1 4.44-2.24C19.51 3.1 22 5.6 22 8.69c0 7-6.48 11.13-9.38 12.12Z"
                    fill="currentColor"
                  />
                </svg>
              ) : null
            }
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Heart</Label>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox defaultSelected name="plus">
        <Checkbox.Control>
          <Checkbox.Indicator>
            {({isSelected}) =>
              isSelected ? (
                <svg fill="none" viewBox="0 0 24 24">
                  <path
                    d="M6 12H18"
                    stroke="currentColor"
                    strokeLinecap="round"
                    strokeLinejoin="round"
                    strokeWidth="3"
                  />
                  <path
                    d="M12 18V6"
                    stroke="currentColor"
                    strokeLinecap="round"
                    strokeLinejoin="round"
                    strokeWidth="3"
                  />
                </svg>
              ) : null
            }
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Plus</Label>
        </Checkbox.Content>
      </Checkbox>
      <Checkbox isIndeterminate name="indeterminate">
        <Checkbox.Control>
          <Checkbox.Indicator>
            {({isIndeterminate}) =>
              isIndeterminate ? (
                <svg stroke="currentColor" strokeWidth={3} viewBox="0 0 24 24">
                  <line x1="21" x2="3" y1="12" y2="12" />
                </svg>
              ) : null
            }
          </Checkbox.Indicator>
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Indeterminate</Label>
        </Checkbox.Content>
      </Checkbox>
    </div>
  );
}

```

### Full Rounded

```tsx
import {Checkbox, Label} from "@heroui/react";

export function FullRounded() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex flex-col gap-3">
        <Label className="text-muted">Rounded checkboxes</Label>
        <Checkbox
          className="[&_[data-slot='checkbox-default-indicator--checkmark']]:size-2"
          name="small-rounded"
        >
          <Checkbox.Control className="size-3 rounded-full before:rounded-full">
            <Checkbox.Indicator />
          </Checkbox.Control>
          <Checkbox.Content>
            <Label>Small size</Label>
          </Checkbox.Content>
        </Checkbox>
      </div>
      <div className="flex flex-col gap-3">
        <Checkbox name="default-rounded">
          <Checkbox.Control className="size-4 rounded-full before:rounded-full">
            <Checkbox.Indicator />
          </Checkbox.Control>
          <Checkbox.Content>
            <Label>Default size</Label>
          </Checkbox.Content>
        </Checkbox>
      </div>
      <div className="flex flex-col gap-3">
        <Checkbox name="large-rounded">
          <Checkbox.Control className="size-5 rounded-full before:rounded-full">
            <Checkbox.Indicator />
          </Checkbox.Control>
          <Checkbox.Content>
            <Label>Large size</Label>
          </Checkbox.Content>
        </Checkbox>
      </div>
      <div className="flex flex-col gap-3">
        <Checkbox
          className="[&_[data-slot='checkbox-default-indicator--checkmark']]:size-4"
          name="xl-rounded"
        >
          <Checkbox.Control className="size-6 rounded-full before:rounded-full">
            <Checkbox.Indicator />
          </Checkbox.Control>
          <Checkbox.Content>
            <Label>Extra large size</Label>
          </Checkbox.Content>
        </Checkbox>
      </div>
    </div>
  );
}

```

## Related Components

* **Label**: Accessible label for form controls
* **CheckboxGroup**: Group of checkboxes with shared state
* **Description**: Helper text for form fields

## Styling

### Passing Tailwind CSS classes

You can customize individual Checkbox components:

```tsx
import { Checkbox, Label } from '@heroui/react';

function CustomCheckbox() {
  return (
    <Checkbox name="custom">
      <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
        <Checkbox.Indicator className="text-white" />
      </Checkbox.Control>
      <Checkbox.Content>
        <Label>Custom Checkbox</Label>
      </Checkbox.Content>
    </Checkbox>
  );
}

```

### Customizing the component classes

To customize the Checkbox component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .checkbox {
    @apply inline-flex gap-3 items-center;
  }

.checkbox__control {
    @apply size-5 border-2 border-gray-400 rounded data-[selected=true]:bg-blue-500 data-[selected=true]:border-blue-500;

/* Animated background indicator */
    &::before {
      @apply bg-accent pointer-events-none absolute inset-0 z-0 origin-center scale-50 rounded-md opacity-0 content-[''];
      
      transition:
        scale 200ms linear,
        opacity 200ms linear,
        background-color 200ms ease-out;
    }

/* Show indicator when selected */
    &[data-selected="true"]::before {
      @apply scale-100 opacity-100;
    }
  }

.checkbox__indicator {
    @apply text-white;
  }

.checkbox__content {
    @apply flex flex-col gap-1;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The Checkbox component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox.css)):

* `.checkbox` - Base checkbox container
* `.checkbox__control` - Checkbox control box
* `.checkbox__indicator` - Checkbox checkmark indicator
* `.checkbox__content` - Optional content container

### Interactive States

The checkbox supports both CSS pseudo-classes and data attributes for flexibility:

* **Selected**: `[data-selected="true"]` or `[aria-checked="true"]` (shows checkmark and background color change)
* **Indeterminate**: `[data-indeterminate="true"]` (shows indeterminate state with dash)
* **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` (shows error state with danger colors)
* **Hover**: `:hover` or `[data-hovered="true"]`
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
* **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)
* **Pressed**: `:active` or `[data-pressed="true"]`

## API Reference

### Checkbox Props

Inherits from [React Aria Checkbox](https://react-spectrum.adobe.com/react-aria/Checkbox.html).

| Prop              | Type                                                                  | Default | Description                                                       |
| ----------------- | --------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- |
| `isSelected`      | `boolean`                                                             | `false` | Whether the checkbox is checked                                   |
| `defaultSelected` | `boolean`                                                             | `false` | Whether the checkbox is checked by default (uncontrolled)         |
| `isIndeterminate` | `boolean`                                                             | `false` | Whether the checkbox is in an indeterminate state                 |
| `isDisabled`      | `boolean`                                                             | `false` | Whether the checkbox is disabled                                  |
| `isInvalid`       | `boolean`                                                             | `false` | Whether the checkbox is invalid                                   |
| `isReadOnly`      | `boolean`                                                             | `false` | Whether the checkbox is read only                                 |
| `isOnSurface`     | `boolean`                                                             | `false` | Whether the checkbox is displayed on a surface (affects styling)  |
| `name`            | `string`                                                              | -       | The name of the input element, used when submitting an HTML form  |
| `value`           | `string`                                                              | -       | The value of the input element, used when submitting an HTML form |
| `onChange`        | `(isSelected: boolean) => void`                                       | -       | Handler called when the checkbox value changes                    |
| `children`        | `React.ReactNode \| (values: CheckboxRenderProps) => React.ReactNode` | -       | Checkbox content or render prop                                   |

### CheckboxRenderProps

When using the render prop pattern, these values are provided:

| Prop              | Type      | Description                                       |
| ----------------- | --------- | ------------------------------------------------- |
| `isSelected`      | `boolean` | Whether the checkbox is currently checked         |
| `isIndeterminate` | `boolean` | Whether the checkbox is in an indeterminate state |
| `isHovered`       | `boolean` | Whether the checkbox is hovered                   |
| `isPressed`       | `boolean` | Whether the checkbox is currently pressed         |
| `isFocused`       | `boolean` | Whether the checkbox is focused                   |
| `isFocusVisible`  | `boolean` | Whether the checkbox is keyboard focused          |
| `isDisabled`      | `boolean` | Whether the checkbox is disabled                  |
| `isReadOnly`      | `boolean` | Whether the checkbox is read only                 |

</page>

<page url="/docs/react/components/date-field">
# DateField

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/date-field
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/date-field.mdx
> Date input field with labels, descriptions, and validation built on React Aria DateField

## Import

```tsx
import { DateField } from '@heroui/react';

```

### Usage

```tsx
"use client";

import {DateField, DateInputGroup, Label} from "@heroui/react";

```

### Anatomy

```tsx
import {DateField, Label, DateInputGroup, Description, FieldError} from '@heroui/react';

export default () => (
  <DateField>
    <Label />
    <DateInputGroup>
      <DateInputGroup.Input>
        {(segment) => <DateInputGroup.Segment segment={segment} />}
      </DateInputGroup.Input>
    </DateInputGroup>
    <Description />
    <FieldError />
  </DateField>
)

```

> **DateField** combines label, date input, description, and error into a single accessible component.

### With Description

```tsx
"use client";

import {DateField, DateInputGroup, Description, Label} from "@heroui/react";

export function WithDescription() {
  return (
    <div className="flex flex-col gap-4">
      <DateField className="w-[256px]" name="date">
        <Label>Birth date</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Enter your date of birth</Description>
      </DateField>
      <DateField className="w-[256px]" name="appointment-date">
        <Label>Appointment date</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Enter a date for your appointment</Description>
      </DateField>
    </div>
  );
}

```

### Required Field

```tsx
"use client";

import {DateField, DateInputGroup, Description, Label} from "@heroui/react";

export function Required() {
  return (
    <div className="flex flex-col gap-4">
      <DateField isRequired className="w-[256px]" name="date">
        <Label>Date</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
      </DateField>
      <DateField isRequired className="w-[256px]" name="start-date">
        <Label>Start date</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Required field</Description>
      </DateField>
    </div>
  );
}

```

### Validation

Use `isInvalid` together with `FieldError` to surface validation messages.

```tsx
"use client";

import {DateField, DateInputGroup, FieldError, Label} from "@heroui/react";

export function Invalid() {
  return (
    <div className="flex flex-col gap-4">
      <DateField isInvalid isRequired className="w-[256px]" name="date">
        <Label>Date</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <FieldError>Please enter a valid date</FieldError>
      </DateField>
      <DateField isInvalid className="w-[256px]" name="invalid-date">
        <Label>Date</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <FieldError>Date must be in the future</FieldError>
      </DateField>
    </div>
  );
}

```

### With Validation

DateField supports validation with `minValue`, `maxValue`, and custom validation logic.

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {DateField, DateInputGroup, Description, FieldError, Label} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";
import {useState} from "react";

export function WithValidation() {
  const [value, setValue] = useState<DateValue | null>(null);
  const todayDate = today(getLocalTimeZone());
  const isInvalid = value !== null && value.compare(todayDate) < 0;

return (
    <div className="flex flex-col gap-4">
      <DateField
        isRequired
        className="w-[256px]"
        isInvalid={isInvalid}
        minValue={todayDate}
        name="date"
        value={value}
        onChange={setValue}
      >
        <Label>Date</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        {isInvalid ? (
          <FieldError>Date must be today or in the future</FieldError>
        ) : (
          <Description>Enter a date from today onwards</Description>
        )}
      </DateField>
    </div>
  );
}

```

### Controlled

Control the value to synchronize with other components or state management.

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {Button, DateField, DateInputGroup, Description, Label} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";
import {useState} from "react";

export function Controlled() {
  const [value, setValue] = useState<DateValue | null>(null);

return (
    <div className="flex flex-col gap-4">
      <DateField className="w-[256px]" name="date" value={value} onChange={setValue}>
        <Label>Date</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Current value: {value ? value.toString() : "(empty)"}</Description>
      </DateField>
      <div className="flex gap-2">
        <Button variant="tertiary" onPress={() => setValue(today(getLocalTimeZone()))}>
          Set today
        </Button>
        <Button variant="tertiary" onPress={() => setValue(null)}>
          Clear
        </Button>
      </div>
    </div>
  );
}

```

### Disabled State

```tsx
"use client";

import {DateField, DateInputGroup, Description, Label} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";

export function Disabled() {
  return (
    <div className="flex flex-col gap-4">
      <DateField isDisabled className="w-[256px]" name="date" value={today(getLocalTimeZone())}>
        <Label>Date</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>This date field is disabled</Description>
      </DateField>
      <DateField isDisabled className="w-[256px]" name="date-empty">
        <Label>Date</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>This date field is disabled</Description>
      </DateField>
    </div>
  );
}

```

### With Icons

Add prefix or suffix icons to enhance the date field.

```tsx
"use client";

import {Calendar} from "@gravity-ui/icons";
import {DateField, DateInputGroup, Label} from "@heroui/react";

export function WithPrefixIcon() {
  return (
    <DateField className="w-[256px]" name="date">
      <Label>Date</Label>
      <DateInputGroup>
        <DateInputGroup.Prefix>
          <Calendar className="size-4 text-muted" />
        </DateInputGroup.Prefix>
        <DateInputGroup.Input>
          {(segment) => <DateInputGroup.Segment segment={segment} />}
        </DateInputGroup.Input>
      </DateInputGroup>
    </DateField>
  );
}

```

```tsx
"use client";

import {Calendar} from "@gravity-ui/icons";
import {DateField, DateInputGroup, Label} from "@heroui/react";

export function WithSuffixIcon() {
  return (
    <DateField className="w-[256px]" name="date">
      <Label>Date</Label>
      <DateInputGroup>
        <DateInputGroup.Input>
          {(segment) => <DateInputGroup.Segment segment={segment} />}
        </DateInputGroup.Input>
        <DateInputGroup.Suffix>
          <Calendar className="size-4 text-muted" />
        </DateInputGroup.Suffix>
      </DateInputGroup>
    </DateField>
  );
}

```

```tsx
"use client";

import {Calendar, ChevronDown} from "@gravity-ui/icons";
import {DateField, DateInputGroup, Description, Label} from "@heroui/react";

export function WithPrefixAndSuffix() {
  return (
    <DateField className="w-[256px]" name="date">
      <Label>Date</Label>
      <DateInputGroup>
        <DateInputGroup.Prefix>
          <Calendar className="size-4 text-muted" />
        </DateInputGroup.Prefix>
        <DateInputGroup.Input>
          {(segment) => <DateInputGroup.Segment segment={segment} />}
        </DateInputGroup.Input>
        <DateInputGroup.Suffix>
          <ChevronDown className="size-4 text-muted" />
        </DateInputGroup.Suffix>
      </DateInputGroup>
      <Description>Enter a date</Description>
    </DateField>
  );
}

```

### Full Width

```tsx
"use client";

import {Calendar, ChevronDown} from "@gravity-ui/icons";
import {DateField, DateInputGroup, Label} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-4">
      <DateField fullWidth name="date">
        <Label>Date</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
      </DateField>
      <DateField fullWidth name="date-icons">
        <Label>Date</Label>
        <DateInputGroup>
          <DateInputGroup.Prefix>
            <Calendar className="size-4 text-muted" />
          </DateInputGroup.Prefix>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
          <DateInputGroup.Suffix>
            <ChevronDown className="size-4 text-muted" />
          </DateInputGroup.Suffix>
        </DateInputGroup>
      </DateField>
    </div>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, DateField and its child DateInputGroup automatically apply on-surface styling.

```tsx
"use client";

import {Calendar} from "@gravity-ui/icons";
import {DateField, DateInputGroup, Description, Label, Surface} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6">
      <DateField className="w-full" name="date">
        <Label>Date</Label>
        <DateInputGroup isOnSurface>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Enter a date</Description>
      </DateField>
      <DateField className="w-full" name="date-2">
        <Label>Appointment date</Label>
        <DateInputGroup isOnSurface>
          <DateInputGroup.Prefix>
            <Calendar className="size-4 text-muted" />
          </DateInputGroup.Prefix>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Enter a date for your appointment</Description>
      </DateField>
    </Surface>
  );
}

```

### Form Example

Complete form example with validation and submission handling.

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {Calendar} from "@gravity-ui/icons";
import {
  Button,
  DateField,
  DateInputGroup,
  Description,
  FieldError,
  Form,
  Label,
} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";
import {useState} from "react";

export function FormExample() {
  const [value, setValue] = useState<DateValue | null>(null);
  const [isSubmitting, setIsSubmitting] = useState(false);
  const todayDate = today(getLocalTimeZone());
  const isInvalid = value !== null && value.compare(todayDate) < 0;

const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();

if (!value || isInvalid) {
      return;
    }

setIsSubmitting(true);

// Simulate API call
    setTimeout(() => {
      console.log("Date submitted:", {date: value});
      setValue(null);
      setIsSubmitting(false);
    }, 1500);
  };

return (
    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
      <DateField
        isRequired
        className="w-full"
        isInvalid={isInvalid}
        minValue={todayDate}
        name="date"
        value={value}
        onChange={setValue}
      >
        <Label>Appointment date</Label>
        <DateInputGroup>
          <DateInputGroup.Prefix>
            <Calendar className="size-4 text-muted" />
          </DateInputGroup.Prefix>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        {isInvalid ? (
          <FieldError>Date must be today or in the future</FieldError>
        ) : (
          <Description>Enter a date from today onwards</Description>
        )}
      </DateField>
      <Button
        className="w-full"
        isDisabled={!value || isInvalid}
        isPending={isSubmitting}
        type="submit"
        variant="primary"
      >
        {isSubmitting ? "Submitting..." : "Submit"}
      </Button>
    </Form>
  );
}

```

## Related Components

* **Label**: Accessible label for form controls
* **FieldError**: Inline validation messages for form fields
* **Description**: Helper text for form fields

## Styling

### Passing Tailwind CSS classes

```tsx
import {DateField, Label, DateInputGroup, Description} from '@heroui/react';

function CustomDateField() {
  return (
    <DateField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
      <Label className="text-sm font-semibold text-default-700">
        Appointment date
      </Label>
      <DateInputGroup className="rounded-lg border border-border/60 bg-surface px-3 py-2">
        <DateInputGroup.Input>
          {(segment) => <DateInputGroup.Segment segment={segment} />}
        </DateInputGroup.Input>
      </DateInputGroup>
      <Description className="text-xs text-default-500">
        Select a date for your appointment.
      </Description>
    </DateField>
  );
}

```

### Customizing the component classes

DateField has minimal default styling. Override the `.date-field` class to customize the container styling.

```css
@layer components {
  .date-field {
    @apply flex flex-col gap-1;

&[data-invalid="true"],
    &[aria-invalid="true"] {
      [data-slot="description"] {
        @apply hidden;
      }
    }

[data-slot="label"] {
      @apply w-fit;
    }

[data-slot="description"] {
      @apply px-1;
    }
  }
}

```

### CSS Classes

* `.date-field` – Root container with minimal styling (`flex flex-col gap-1`)

> **Note:** Child components ([Label](/docs/components/label), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options. DateInputGroup styling is documented below in the API Reference section.

### Interactive States

DateField automatically manages these data attributes based on its state:

* **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
* **Required**: `[data-required="true"]` - Applied when `isRequired` is true
* **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
* **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused

## API Reference

### DateField Props

DateField inherits all props from React Aria's [DateField](https://react-aria.adobe.com/DateField.md) component.

#### Base Props

| Prop        | Type                                                                           | Default | Description                                                        |
| ----------- | ------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------ |
| `children`  | `React.ReactNode \| (values: DateFieldRenderProps) => React.ReactNode`         | -       | Child components (Label, DateInputGroup, etc.) or render function. |
| `className` | `string \| (values: DateFieldRenderProps) => string`                           | -       | CSS classes for styling, supports render props.                    |
| `style`     | `React.CSSProperties \| (values: DateFieldRenderProps) => React.CSSProperties` | -       | Inline styles, supports render props.                              |
| `fullWidth` | `boolean`                                                                      | `false` | Whether the date field should take full width of its container     |
| `id`        | `string`                                                                       | -       | The element's unique identifier.                                   |

#### Value Props

| Prop               | Type                                 | Default | Description                                                                                                                 |
| ------------------ | ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `value`            | `DateValue \| null`                  | -       | Current value (controlled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types.   |
| `defaultValue`     | `DateValue \| null`                  | -       | Default value (uncontrolled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
| `onChange`         | `(value: DateValue \| null) => void` | -       | Handler called when the value changes.                                                                                      |
| `placeholderValue` | `DateValue \| null`                  | -       | Placeholder date that influences the format of the placeholder.                                                             |

#### Validation Props

| Prop                 | Type                                                                 | Default    | Description                                                                                                                                    |
| -------------------- | -------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `isRequired`         | `boolean`                                                            | `false`    | Whether user input is required before form submission.                                                                                         |
| `isInvalid`          | `boolean`                                                            | -          | Whether the value is invalid.                                                                                                                  |
| `minValue`           | `DateValue \| null`                                                  | -          | The minimum allowed date that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
| `maxValue`           | `DateValue \| null`                                                  | -          | The maximum allowed date that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
| `isDateUnavailable`  | `(date: DateValue) => boolean`                                       | -          | Callback that is called for each date. If it returns true, the date is unavailable.                                                            |
| `validate`           | `(value: DateValue) => ValidationError \| true \| null \| undefined` | -          | Custom validation function.                                                                                                                    |
| `validationBehavior` | `'native' \| 'aria'`                                                 | `'native'` | Whether to use native HTML form validation or ARIA attributes.                                                                                 |

#### Format Props

| Prop                      | Type          | Default | Description                                                                                  |
| ------------------------- | ------------- | ------- | -------------------------------------------------------------------------------------------- |
| `granularity`             | `Granularity` | -       | Determines the smallest unit displayed. Defaults to `"day"` for dates, `"minute"` for times. |
| `hourCycle`               | `12 \| 24`    | -       | Whether to display time in 12 or 24 hour format. By default, determined by locale.           |
| `hideTimeZone`            | `boolean`     | `false` | Whether to hide the time zone abbreviation.                                                  |
| `shouldForceLeadingZeros` | `boolean`     | -       | Whether to always show leading zeros in month, day, and hour fields.                         |

#### State Props

| Prop         | Type      | Default | Description                                        |
| ------------ | --------- | ------- | -------------------------------------------------- |
| `isDisabled` | `boolean` | -       | Whether the input is disabled.                     |
| `isReadOnly` | `boolean` | -       | Whether the input can be selected but not changed. |

#### Form Props

| Prop           | Type      | Default | Description                                                                      |
| -------------- | --------- | ------- | -------------------------------------------------------------------------------- |
| `name`         | `string`  | -       | Name of the input element, for HTML form submission. Submits as ISO 8601 string. |
| `autoFocus`    | `boolean` | -       | Whether the element should receive focus on render.                              |
| `autoComplete` | `string`  | -       | Type of autocomplete functionality the input should provide.                     |

#### Accessibility Props

| Prop               | Type     | Default | Description                                           |
| ------------------ | -------- | ------- | ----------------------------------------------------- |
| `aria-label`       | `string` | -       | Accessibility label when no visible label is present. |
| `aria-labelledby`  | `string` | -       | ID of elements that label this field.                 |
| `aria-describedby` | `string` | -       | ID of elements that describe this field.              |
| `aria-details`     | `string` | -       | ID of elements with additional details.               |

### Composition Components

DateField works with these separate components that should be imported and used directly:

* **Label** - Field label component from `@heroui/react`
* **DateInputGroup** - Date input component with segmented editing from `@heroui/react` (documented below)
* **Description** - Helper text component from `@heroui/react`
* **FieldError** - Validation error message from `@heroui/react`

Each of these components has its own props API. Use them directly within DateField for composition:

```tsx
import {parseDate} from '@internationalized/date';
import {DateField, Label, DateInputGroup, Description, FieldError} from '@heroui/react';

<DateField
  isRequired
  isInvalid={hasError}
  minValue={today(getLocalTimeZone())}
  value={date}
  onChange={setDate}
>
  <Label>Appointment Date</Label>
  <DateInputGroup>
    <DateInputGroup.Input>
      {(segment) => <DateInputGroup.Segment segment={segment} />}
    </DateInputGroup.Input>
  </DateInputGroup>
  <Description>Select a date from today onwards.</Description>
  <FieldError>Please select a valid date.</FieldError>
</DateField>

```

### DateValue Types

DateField uses types from [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/):

* `CalendarDate` - Date without time or timezone
* `CalendarDateTime` - Date with time but no timezone
* `ZonedDateTime` - Date with time and timezone
* `Time` - Time only

Example:

```tsx
import {parseDate, today, getLocalTimeZone} from '@internationalized/date';

// Parse from string
const date = parseDate('2024-01-15');

// Today's date
const todayDate = today(getLocalTimeZone());

// Use in DateField
<DateField value={date} onChange={setDate}>
  {/* ... */}
</DateField>

```

> **Note:** DateField uses the [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) package for date manipulation, parsing, and type definitions. See the [Internationalized Date documentation](https://react-aria.adobe.com/internationalized/date/) for more information about available types and functions.

### DateFieldRenderProps

When using render props with `className`, `style`, or `children`, these values are available:

| Prop             | Type      | Description                                     |
| ---------------- | --------- | ----------------------------------------------- |
| `isDisabled`     | `boolean` | Whether the field is disabled.                  |
| `isInvalid`      | `boolean` | Whether the field is currently invalid.         |
| `isReadOnly`     | `boolean` | Whether the field is read-only.                 |
| `isRequired`     | `boolean` | Whether the field is required.                  |
| `isFocused`      | `boolean` | Whether the field is currently focused.         |
| `isFocusWithin`  | `boolean` | Whether any child element is focused.           |
| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). |

### DateInputGroup Props

DateInputGroup accepts all props from React Aria's `Group` component plus the following:

| Prop          | Type      | Default | Description                                                          |
| ------------- | --------- | ------- | -------------------------------------------------------------------- |
| `className`   | `string`  | -       | Tailwind classes merged with the component styles.                   |
| `fullWidth`   | `boolean` | `false` | Whether the date input group should take full width of its container |
| `isOnSurface` | `boolean` | `false` | Whether the input is displayed on a surface (affects styling)        |

### DateInputGroup.Input Props

DateInputGroup.Input accepts all props from React Aria's `DateInput` component plus the following:

| Prop          | Type      | Default | Description                                                   |
| ------------- | --------- | ------- | ------------------------------------------------------------- |
| `className`   | `string`  | -       | Tailwind classes merged with the component styles.            |
| `isOnSurface` | `boolean` | `false` | Whether the input is displayed on a surface (affects styling) |

The `DateInput` component accepts a render prop function that receives date segments. Each segment represents a part of the date (year, month, day, etc.).

### DateInputGroup.Segment Props

DateInputGroup.Segment accepts all props from React Aria's `DateSegment` component:

| Prop        | Type          | Default | Description                                             |
| ----------- | ------------- | ------- | ------------------------------------------------------- |
| `segment`   | `DateSegment` | -       | The date segment object from the DateInput render prop. |
| `className` | `string`      | -       | Tailwind classes merged with the component styles.      |

### DateInputGroup.Prefix Props

DateInputGroup.Prefix accepts standard HTML `div` attributes:

| Prop        | Type        | Default | Description                                        |
| ----------- | ----------- | ------- | -------------------------------------------------- |
| `className` | `string`    | -       | Tailwind classes merged with the component styles. |
| `children`  | `ReactNode` | -       | Content to display in the prefix slot.             |

### DateInputGroup.Suffix Props

DateInputGroup.Suffix accepts standard HTML `div` attributes:

## DateInputGroup Styling

### Customizing the component classes

The base classes power every instance. Override them once with `@layer components`.

```css
@layer components {
  .date-input-group {
    @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none;

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

&[data-focus-within="true"],
    &:focus-within {
      @apply status-focused-field;
    }

&[data-invalid="true"] {
      @apply status-invalid-field;
    }

&[data-disabled="true"],
    &[aria-disabled="true"] {
      @apply status-disabled;
    }
  }

.date-input-group__input {
    @apply flex flex-1 items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
  }

.date-input-group__segment {
    @apply inline-block rounded-md px-0.5 text-end tabular-nums outline-none;

&:focus,
    &[data-focused="true"] {
      @apply bg-accent-soft text-accent-soft-foreground;
    }
  }

.date-input-group__prefix,
  .date-input-group__suffix {
    @apply pointer-events-none shrink-0 text-field-placeholder flex items-center;
  }
}

```

### DateInputGroup CSS Classes

* `.date-input-group` – Root container styling
* `.date-input-group__input` – Input wrapper styling
* `.date-input-group__segment` – Individual date segment styling
* `.date-input-group__prefix` – Prefix element styling
* `.date-input-group__suffix` – Suffix element styling

### DateInputGroup Interactive States

* **Hover**: `:hover` or `[data-hovered="true"]`
* **Focus Within**: `[data-focus-within="true"]` or `:focus-within`
* **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`)
* **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]`
* **Segment Focus**: `:focus` or `[data-focused="true"]` on segment elements
* **Segment Placeholder**: `[data-placeholder="true"]` on segment elements

</page>

<page url="/docs/react/components/description">
# Description

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/description
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/description.mdx
> Provides supplementary text for form fields and other components

## Import

```tsx
import { Description } from '@heroui/react';

```

## Usage

```tsx
import {Description, Input, Label} from "@heroui/react";

export function Basic() {
  return (
    <div className="flex flex-col gap-1">
      <Label htmlFor="email">Email</Label>
      <Input
        aria-describedby="email-description"
        className="w-64"
        id="email"
        placeholder="you@example.com"
        type="email"
      />
      <Description id="email-description">
        We'll never share your email with anyone else.
      </Description>
    </div>
  );
}

```

## Related Components

* **TextField**: Composition-friendly fields with labels and validation
* **Input**: Single-line text input built on React Aria
* **TextArea**: Multiline text input with focus management

## API

### Description Props

| Prop        | Type        | Default | Description                    |
| ----------- | ----------- | ------- | ------------------------------ |
| `className` | `string`    | -       | Additional CSS classes         |
| `children`  | `ReactNode` | -       | The content of the description |

## Accessibility

The Description component enhances accessibility by:

* Using semantic HTML that screen readers can identify
* Providing the `slot="description"` attribute for React Aria integration
* Supporting proper text contrast ratios

## Styling

The Description component uses the following CSS classes:

* `.description` - Base description styles with `muted` text color

## Examples

### With Form Fields

```tsx
<div className="flex flex-col gap-1">
  <Label htmlFor="password">Password</Label>
  <Input id="password" type="password" aria-describedby="password-description" />
  <Description id="password-description">
    Must be at least 8 characters with one uppercase letter
  </Description>
</div>

```

### Integration with TextField

```tsx
import {TextField, Label, Input, Description} from '@heroui/react';

<TextField type="email">
  <Label>Email</Label>
  <Input placeholder="Enter your email" />
  <Description>We'll never share your email</Description>
</TextField>

```

When using the [TextField](./text-field) component, accessibility attributes are automatically applied to the label and description.

</page>

<page url="/docs/react/components/error-message">
# ErrorMessage

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/error-message
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/error-message.mdx
> A low-level error message component for displaying errors

## Import

```tsx
import { ErrorMessage } from '@heroui/react';

```

## Usage

`ErrorMessage` is a low-level component built on React Aria's `Text` component with an `errorMessage` slot. It's designed for displaying error messages in **non-form components** such as `TagGroup`, `Calendar`, and other collection-based components.

```tsx
"use client";

import type {Key} from "@heroui/react";

import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react";
import {useMemo, useState} from "react";

export function ErrorMessageBasic() {
  const [selected, setSelected] = useState<Iterable<Key>>(new Set());
  const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]);

```

### Anatomy

```tsx
import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react';

```

## Related Components

* **TagGroup**: Focusable list of tags with selection and removal support

## When to Use

`ErrorMessage` is **not tied to forms**. It's a generic error display component for non-form contexts.

* **Recommended for** non-form components (e.g., `TagGroup`, `Calendar`, collection components)
* **For form fields**, we recommend using [`FieldError`](/docs/components/field-error) instead, which provides form-specific validation features and automatic error handling, following standardized form validation patterns.

## ErrorMessage vs FieldError

| Component      | Use Case                  | Form Integration | Example Components                   |
| -------------- | ------------------------- | ---------------- | ------------------------------------ |
| `ErrorMessage` | Non-form components       | No               | `TagGroup`, `Calendar`               |
| `FieldError`   | Form fields (recommended) | Yes              | `TextField`, `NumberField`, `Select` |

For form validation, we recommend using `FieldError` as it follows standardized form validation patterns and provides form-specific features. See the [FieldError documentation](/docs/components/field-error) and the [Form guide](/docs/components/form) for examples and best practices.

## API Reference

### ErrorMessage Props

| Prop        | Type        | Default | Description               |
| ----------- | ----------- | ------- | ------------------------- |
| `className` | `string`    | -       | Additional CSS classes    |
| `children`  | `ReactNode` | -       | The error message content |

**Note**: `ErrorMessage` is built on React Aria's `Text` component with `slot="errorMessage"`. It can be targeted using the `[slot=errorMessage]` CSS selector.

## Accessibility

The ErrorMessage component enhances accessibility by:

* Using semantic HTML that screen readers can identify
* Providing the `slot="errorMessage"` attribute for React Aria integration
* Supporting proper text contrast ratios for error states
* Following WAI-ARIA best practices for error messaging

## Styling

### Passing Tailwind CSS classes

```tsx
import { ErrorMessage } from '@heroui/react';

function CustomErrorMessage() {
  return (
    <ErrorMessage className="font-bold text-sm">
      Custom styled error message
    </ErrorMessage>
  );
}

```

### Customizing the component classes

To customize the ErrorMessage component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .error-message {
    @apply text-red-600 text-sm font-medium;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The ErrorMessage component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/error-message.css)):

#### Base Classes

* `.error-message` - Base error message styles with danger color and text truncation

#### Slot Classes

* `[slot="errorMessage"]` - ErrorMessage slot styles for React Aria integration

</page>

<page url="/docs/react/components/field-error">
# FieldError

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/field-error
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/field-error.mdx
> Displays validation error messages for form fields

## Import

```tsx
import { FieldError } from '@heroui/react';

```

## Usage

The FieldError component displays validation error messages for form fields. It automatically appears when the parent field is marked as invalid and provides smooth opacity transitions.

```tsx
"use client";

import {FieldError, Input, Label, TextField} from "@heroui/react";
import {useState} from "react";

export function Basic() {
  const [value, setValue] = useState("jr");
  const isInvalid = value.length > 0 && value.length < 3;

return (
    <TextField className="w-64" isInvalid={isInvalid}>
      <Label htmlFor="username">Username</Label>
      <Input
        id="username"
        placeholder="Enter username"
        value={value}
        onChange={(e) => setValue(e.target.value)}
      />
      <FieldError>Username must be at least 3 characters</FieldError>
    </TextField>
  );
}

```

## Related Components

* **TextField**: Composition-friendly fields with labels and validation
* **Input**: Single-line text input built on React Aria
* **TextArea**: Multiline text input with focus management

## API

### FieldError Props

| Prop        | Type                                                         | Default | Description                              |
| ----------- | ------------------------------------------------------------ | ------- | ---------------------------------------- |
| `className` | `string`                                                     | -       | Additional CSS classes                   |
| `children`  | `ReactNode \| ((validation: ValidationResult) => ReactNode)` | -       | Error message content or render function |

## Accessibility

The FieldError component ensures accessibility by:

* Using proper ARIA attributes for error announcement
* Supporting screen readers with semantic HTML
* Providing visual and programmatic error indication
* Automatically managing visibility based on validation state

## Styling

The FieldError component uses the following CSS classes:

* `.field-error` - Base error styles with danger color
* Only shows when the `data-visible` attribute is present
* Text is truncated with ellipsis for long messages

## Examples

### Basic Validation

```tsx
export function Basic() {
  const [value, setValue] = useState("");
  const isInvalid = value.length > 0 && value.length < 3;

```

### With Dynamic Messages

```tsx
<TextField isInvalid={errors.length > 0}>
  <Label>Password</Label>
  <Input type="password" />
  <FieldError>
    {(validation) => validation.validationErrors.join(', ')}
  </FieldError>
</TextField>

```

### Custom Validation Logic

```tsx
function EmailField() {
  const [email, setEmail] = useState('');
  const isInvalid = email.length > 0 && !email.includes('@');

return (
    <TextField isInvalid={isInvalid}>
      <Label>Email</Label>
      <Input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
      />
      <FieldError>Email must include @ symbol</FieldError>
    </TextField>
  );
}

```

### Multiple Error Messages

```tsx
<TextField isInvalid={hasErrors}>
  <Label>Username</Label>
  <Input />
  <FieldError>
    {errors.map((error, i) => (
      <div key={i}>{error}</div>
    ))}
  </FieldError>
</TextField>
```

</page>

<page url="/docs/react/components/fieldset">
# Fieldset

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/fieldset
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/fieldset.mdx
> Group related form controls with legends, descriptions, and actions

## Import

```tsx
import { Fieldset } from '@heroui/react';

```

### Usage

```tsx
"use client";

import {FloppyDisk} from "@gravity-ui/icons";
import {
  Button,
  Description,
  FieldError,
  FieldGroup,
  Fieldset,
  Form,
  Input,
  Label,
  TextArea,
  TextField,
} from "@heroui/react";

// Convert FormData to plain object
    formData.forEach((value, key) => {
      data[key] = value.toString();
    });

alert("Form submitted successfully!");
  };

return (
    <Form className="w-full max-w-96" onSubmit={onSubmit}>
      <Fieldset>
        <Fieldset.Legend>Profile Settings</Fieldset.Legend>
        <Description>Update your profile information.</Description>
        <FieldGroup>
          <TextField
            isRequired
            name="name"
            validate={(value) => {
              if (value.length < 3) {
                return "Name must be at least 3 characters";
              }

return null;
            }}
          >
            <Label>Name</Label>
            <Input placeholder="John Doe" />
            <FieldError />
          </TextField>
          <TextField isRequired name="email" type="email">
            <Label>Email</Label>
            <Input placeholder="john@example.com" />
            <FieldError />
          </TextField>
          <TextField
            isRequired
            name="bio"
            validate={(value) => {
              if (value.length < 10) {
                return "Bio must be at least 10 characters";
              }

return null;
            }}
          >
            <Label>Bio</Label>
            <TextArea placeholder="Tell us about yourself..." />
            <Description>Minimum 10 characters</Description>
            <FieldError />
          </TextField>
        </FieldGroup>
        <Fieldset.Actions>
          <Button type="submit">
            <FloppyDisk />
            Save changes
          </Button>
          <Button type="reset" variant="secondary">
            Cancel
          </Button>
        </Fieldset.Actions>
      </Fieldset>
    </Form>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, form controls within Fieldset automatically apply on-surface styling.

```tsx
"use client";

import {FloppyDisk} from "@gravity-ui/icons";
import {
  Button,
  Description,
  FieldError,
  Fieldset,
  Form,
  Input,
  Label,
  Surface,
  TextArea,
  TextField,
} from "@heroui/react";
import React from "react";

export function OnSurface() {
  const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const data: Record<string, string> = {};

// Convert FormData to plain object
    formData.forEach((value, key) => {
      data[key] = value.toString();
    });

alert("Form submitted successfully!");
  };

return (
    <div className="flex items-center justify-center rounded-3xl bg-surface p-6">
      <Surface className="w-full min-w-[380px]">
        <Form onSubmit={onSubmit}>
          <Fieldset className="w-full">
            <Fieldset.Legend>Profile Settings</Fieldset.Legend>
            <Description>Update your profile information.</Description>
            <Fieldset.Group>
              <TextField
                isRequired
                name="name"
                validate={(value) => {
                  if (value.length < 3) {
                    return "Name must be at least 3 characters";
                  }

return null;
                }}
              >
                <Label>Name</Label>
                <Input placeholder="John Doe" />
                <FieldError />
              </TextField>
              <TextField isRequired name="email" type="email">
                <Label>Email</Label>
                <Input placeholder="john@example.com" />
                <FieldError />
              </TextField>
              <TextField
                isRequired
                name="bio"
                validate={(value) => {
                  if (value.length < 10) {
                    return "Bio must be at least 10 characters";
                  }

return null;
                }}
              >
                <Label>Bio</Label>
                <TextArea placeholder="Tell us about yourself..." />
                <Description>Minimum 10 characters</Description>
                <FieldError />
              </TextField>
            </Fieldset.Group>
            <Fieldset.Actions>
              <Button type="submit">
                <FloppyDisk />
                Save changes
              </Button>
              <Button type="reset" variant="tertiary">
                Cancel
              </Button>
            </Fieldset.Actions>
          </Fieldset>
        </Form>
      </Surface>
    </div>
  );
}

```

### Anatomy

Import the Fieldset component and access all parts using dot notation.

```tsx
import { Fieldset } from '@heroui/react';

export default () => (
  <Fieldset>
    <Fieldset.Legend />
    <Fieldset.Group>
      {/* form fields go here */}
    </Fieldset.Group>
    <Fieldset.Actions>
      {/* action buttons go here */}
    </Fieldset.Actions>
  </Fieldset>
)

```

## Related Components

* **TextField**: Composition-friendly fields with labels and validation
* **Label**: Accessible label for form controls
* **CheckboxGroup**: Group of checkboxes with shared state

## Styling

### Passing Tailwind CSS classes

```tsx
import { Fieldset, TextField, Label, Input } from '@heroui/react';

function CustomFieldset() {
  return (
    <Fieldset className="rounded-xl border border-border bg-surface p-6 shadow-sm">
      <Fieldset.Legend className="text-lg font-semibold">Team members</Fieldset.Legend>
      <Fieldset.Group className="grid gap-4 md:grid-cols-2">
        <TextField>
          <Label>First name</Label>
          <Input className="rounded-full border-border/60" placeholder="Jane" />
        </TextField>
        <TextField>
          <Label>Last name</Label>
          <Input className="rounded-full border-border/60" placeholder="Doe" />
        </TextField>
      </Fieldset.Group>
      <Fieldset.Actions className="justify-end gap-3">
        {/* Action buttons */}
      </Fieldset.Actions>
    </Fieldset>
  );
}

```

### Customizing the component classes

Use the `@layer components` directive to target Fieldset [BEM](https://getbem.com/)-style classes.

```css
@layer components {
  .fieldset {
    @apply gap-5 rounded-xl border border-border/60 bg-surface p-6 shadow-field;
  }

.fieldset__legend {
    @apply text-lg font-semibold;
  }

.fieldset_field_group {
    @apply gap-3 md:grid md:grid-cols-2;
  }

.fieldset_actions {
    @apply flex justify-end gap-2 pt-2;
  }
}

```

### CSS Classes

The Fieldset compound component exposes these CSS selectors:

* `.fieldset` – Root container
* `.fieldset__legend` – Legend element
* `.fieldset_field_group` – Wrapper for grouped fields
* `.fieldset_actions` – Action bar below the fields

## API Reference

### Fieldset Props

| Prop          | Type                                        | Default                                         | Description                                               |
| ------------- | ------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
| `className`   | `string`                                    | -                                               | Tailwind CSS classes applied to the root element.         |
| `children`    | `React.ReactNode`                           | -                                               | Fieldset content (legend, groups, descriptions, actions). |
| `nativeProps` | `React.HTMLAttributes<HTMLFieldSetElement>` | Supports native fieldset attributes and events. |                                                           |

### Fieldset.Legend Props

| Prop          | Type                                      | Default | Description                              |
| ------------- | ----------------------------------------- | ------- | ---------------------------------------- |
| `className`   | `string`                                  | -       | Tailwind classes for the legend element. |
| `children`    | `React.ReactNode`                         | -       | Legend content, usually plain text.      |
| `nativeProps` | `React.HTMLAttributes<HTMLLegendElement>` | -       | Native legend attributes.                |

### Fieldset.Group Props

| Prop          | Type                                   | Default | Description                                    |
| ------------- | -------------------------------------- | ------- | ---------------------------------------------- |
| `className`   | `string`                               | -       | Layout and spacing classes for grouped fields. |
| `children`    | `React.ReactNode`                      | -       | Form controls to group inside the fieldset.    |
| `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | -       | Native div attributes.                         |

### Fieldset.Actions Props

| Prop          | Type                                   | Default | Description                                       |
| ------------- | -------------------------------------- | ------- | ------------------------------------------------- |
| `className`   | `string`                               | -       | Tailwind classes to align action buttons or text. |
| `children`    | `React.ReactNode`                      | -       | Action buttons or helper text.                    |
| `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | -       | Native div attributes.                            |

</page>

<page url="/docs/react/components/form">
# Form

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/form
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/form.mdx
> Wrapper component for form validation and submission handling

## Import

```tsx
import { Form } from '@heroui/react';

```

### Usage

```tsx
"use client";

import {Check} from "@gravity-ui/icons";
import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react";

// Convert FormData to plain object
    formData.forEach((value, key) => {
      data[key] = value.toString();
    });

alert(`Form submitted with: ${JSON.stringify(data, null, 2)}`);
  };

return null;
        }}
      >
        <Label>Email</Label>
        <Input placeholder="john@example.com" />
        <FieldError />
      </TextField>

```

### Anatomy

Import all parts and piece them together.

```tsx
import {Form, Button} from '@heroui/react';

export default () => (
  <Form>
    {/* Form fields go here */}
    <Button type="submit"/>
    <Button type="reset"/>
  </Form>
)

```

## Related Components

* **Button**: Allows a user to perform an action
* **Fieldset**: Group related form controls with legends
* **TextField**: Composition-friendly fields with labels and validation

## Styling

### Passing Tailwind CSS classes

```tsx
import {Form, TextField, Label, Input, FieldError, Button} from '@heroui/react';

function CustomForm() {
  return (
    <Form className="w-full max-w-md space-y-4 rounded-lg border border-border bg-surface p-6">
      <TextField>
        <Label className="text-sm font-medium">Email</Label>
        <Input className="rounded-full border-border/60" placeholder="Enter your email" />
        <FieldError className="text-xs" />
      </TextField>
      <Button type="submit" className="w-full">
        Submit
      </Button>
    </Form>
  );
}

```

## API Reference

### Form Props

The Form component is a wrapper around React Aria's Form primitive that provides form validation and submission handling capabilities.

| Prop                 | Type                                                                           | Default    | Description                                                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action`             | `string \| FormHTMLAttributes['action']`                                       | -          | The URL to submit the form data to.                                                                                                                     |
| `className`          | `string`                                                                       | -          | Tailwind CSS classes applied to the form element.                                                                                                       |
| `children`           | `React.ReactNode`                                                              | -          | Form content (fields, buttons, etc.).                                                                                                                   |
| `encType`            | `'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'` | -          | The encoding type for form data submission.                                                                                                             |
| `method`             | `'get' \| 'post'`                                                              | -          | The HTTP method to use when submitting the form.                                                                                                        |
| `onInvalid`          | `(event: FormEvent<HTMLFormElement>) => void`                                  | -          | Handler called when the form validation fails. By default, the first invalid field will be focused. Use `preventDefault()` to customize focus behavior. |
| `onReset`            | `(event: FormEvent<HTMLFormElement>) => void`                                  | -          | Handler called when the form is reset.                                                                                                                  |
| `onSubmit`           | `(event: FormEvent<HTMLFormElement>) => void`                                  | -          | Handler called when the form is submitted.                                                                                                              |
| `target`             | `'_self' \| '_blank' \| '_parent' \| '_top'`                                   | -          | Where to display the response after submitting the form.                                                                                                |
| `validationBehavior` | `'native' \| 'aria'`                                                           | `'native'` | Whether to use native HTML validation or ARIA validation. 'native' blocks form submission, 'aria' displays errors in realtime.                          |
| `validationErrors`   | `ValidationErrors`                                                             | -          | Server-side validation errors mapped by field name. Displayed immediately and cleared when user modifies the field.                                     |
| `aria-label`         | `string`                                                                       | -          | Accessibility label for the form.                                                                                                                       |
| `aria-labelledby`    | `string`                                                                       | -          | ID of element that labels the form. Creates a form landmark when provided.                                                                              |

### Form Validation

The Form component integrates with React Aria's validation system, allowing you to:

* Use built-in HTML5 validation attributes (`required`, `minLength`, `pattern`, etc.)
* Provide custom validation functions on TextField components
* Display validation errors with FieldError components
* Handle form submission with proper validation
* Provide server-side validation errors via `validationErrors` prop

#### Validation Behavior

The `validationBehavior` prop controls how validation is displayed:

* **`native`** (default): Uses native HTML validation, blocks form submission on errors
* **`aria`**: Uses ARIA attributes for validation, displays errors in realtime as user types, doesn't block submission

This behavior can be set at the form level or overridden at individual field level.

### Form Submission

Forms can be submitted in several ways:

* **Traditional submission**: Set the `action` prop to submit to a URL
* **JavaScript handling**: Use the `onSubmit` handler to process form data
* **FormData API**: Access form data using the FormData API in your submit handler

Example with FormData:

```tsx
function handleSubmit(e: FormEvent<HTMLFormElement>) {
  e.preventDefault();
  const formData = new FormData(e.currentTarget);
  const data = Object.fromEntries(formData);
  console.log('Form data:', data);
}

```

### Integration with Form Fields

The Form component works seamlessly with HeroUI's form field components:

* **TextField**: For text inputs with labels and validation
* **Checkbox**: For boolean selections
* **RadioGroup**: For single selection from multiple options
* **Switch**: For toggle controls
* **Button**: For form submission and reset actions

All field components automatically integrate with the Form's validation and submission behavior when placed inside it.

### Accessibility

Forms are accessible by default when using React Aria components. Key features include:

* Native `<form>` element semantics
* Form landmark creation with `aria-label` or `aria-labelledby`
* Automatic focus management on validation errors
* ARIA validation attributes when using `validationBehavior="aria"`

### Advanced Usage

For more advanced use cases including:

* Custom validation context
* Form context providers
* Integration with third-party libraries
* Custom focus management on validation errors

Please refer to the [React Aria Form documentation](https://react-spectrum.adobe.com/react-aria/Form.html).

</page>

<page url="/docs/react/components/input-group">
# InputGroup

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/input-group
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/input-group.mdx
> Group related input controls with prefix and suffix elements for enhanced form fields

## Import

```tsx
import { InputGroup } from '@heroui/react';

```

### Usage

```tsx
"use client";

import {Envelope} from "@gravity-ui/icons";
import {InputGroup, Label, TextField} from "@heroui/react";

export function Default() {
  return (
    <TextField className="w-full max-w-[280px]" name="email">
      <Label>Email address</Label>
      <InputGroup>
        <InputGroup.Prefix>
          <Envelope className="size-4 text-muted" />
        </InputGroup.Prefix>
        <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
      </InputGroup>
    </TextField>
  );
}

```

### Anatomy

```tsx
import {InputGroup, TextField, Label} from '@heroui/react';

export default () => (
  <TextField>
    <Label />
    <InputGroup>
      <InputGroup.Prefix />
      <InputGroup.Input />
      <InputGroup.Suffix />
    </InputGroup>
  </TextField>
)

```

> **InputGroup** wraps an input field with optional prefix and suffix elements, creating a visually cohesive group. It's typically used within **[TextField](/docs/components/text-field)** to add icons, text, buttons, or other elements before or after the input.

### With Prefix Icon

Add an icon before the input field.

```tsx
"use client";

import {Envelope} from "@gravity-ui/icons";
import {Description, InputGroup, Label, TextField} from "@heroui/react";

export function WithPrefixIcon() {
  return (
    <TextField className="w-full max-w-[280px]" name="email">
      <Label>Email address</Label>
      <InputGroup>
        <InputGroup.Prefix>
          <Envelope className="size-4 text-muted" />
        </InputGroup.Prefix>
        <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
      </InputGroup>
      <Description>We'll never share this with anyone else</Description>
    </TextField>
  );
}

```

### With Suffix Icon

Add an icon after the input field.

```tsx
"use client";

import {Envelope} from "@gravity-ui/icons";
import {Description, InputGroup, Label, TextField} from "@heroui/react";

export function WithSuffixIcon() {
  return (
    <TextField className="w-full max-w-[280px]" name="email">
      <Label>Email address</Label>
      <InputGroup>
        <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
        <InputGroup.Suffix>
          <Envelope className="size-4 text-muted" />
        </InputGroup.Suffix>
      </InputGroup>
      <Description>We don't send spam</Description>
    </TextField>
  );
}

```

### With Prefix and Suffix

Combine both prefix and suffix elements.

```tsx
"use client";

import {Description, InputGroup, Label, TextField} from "@heroui/react";

export function WithPrefixAndSuffix() {
  return (
    <TextField className="w-full max-w-[280px]" defaultValue="10" name="price">
      <Label>Set a price</Label>
      <InputGroup>
        <InputGroup.Prefix>$</InputGroup.Prefix>
        <InputGroup.Input className="w-full max-w-[200px]" type="number" />
        <InputGroup.Suffix>USD</InputGroup.Suffix>
      </InputGroup>
      <Description>What customers would pay</Description>
    </TextField>
  );
}

```

### Text Prefix

Use text as a prefix, such as currency symbols or protocol prefixes.

```tsx
"use client";

import {InputGroup, Label, TextField} from "@heroui/react";

export function WithTextPrefix() {
  return (
    <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website">
      <Label>Website</Label>
      <InputGroup>
        <InputGroup.Prefix>https://</InputGroup.Prefix>
        <InputGroup.Input className="w-full max-w-[280px]" />
      </InputGroup>
    </TextField>
  );
}

```

### Text Suffix

Use text as a suffix, such as domain extensions or units.

```tsx
"use client";

import {InputGroup, Label, TextField} from "@heroui/react";

export function WithTextSuffix() {
  return (
    <TextField className="w-full max-w-[280px]" defaultValue="heroui" name="website">
      <Label>Website</Label>
      <InputGroup>
        <InputGroup.Input className="w-full max-w-[280px]" />
        <InputGroup.Suffix>.com</InputGroup.Suffix>
      </InputGroup>
    </TextField>
  );
}

```

### Icon Prefix and Text Suffix

Combine an icon prefix with a text suffix.

```tsx
"use client";

import {Globe} from "@gravity-ui/icons";
import {InputGroup, Label, TextField} from "@heroui/react";

```

### Copy Button Suffix

Add an interactive button in the suffix, such as a copy button.

```tsx
"use client";

import {Copy} from "@gravity-ui/icons";
import {Button, InputGroup, Label, TextField} from "@heroui/react";

export function WithCopySuffix() {
  return (
    <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website">
      <Label>Website</Label>
      <InputGroup>
        <InputGroup.Input className="w-full max-w-[280px]" />
        <InputGroup.Suffix className="pr-0">
          <Button isIconOnly aria-label="Copy" size="sm" variant="ghost">
            <Copy className="size-4" />
          </Button>
        </InputGroup.Suffix>
      </InputGroup>
    </TextField>
  );
}

```

### Icon Prefix and Copy Button

Combine an icon prefix with an interactive button suffix.

```tsx
"use client";

import {Copy, Globe} from "@gravity-ui/icons";
import {Button, InputGroup, Label, TextField} from "@heroui/react";

export function WithIconPrefixAndCopySuffix() {
  return (
    <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website">
      <Label>Website</Label>
      <InputGroup>
        <InputGroup.Prefix>
          <Globe className="size-4 text-muted" />
        </InputGroup.Prefix>
        <InputGroup.Input className="w-full max-w-[280px]" />
        <InputGroup.Suffix className="pr-0">
          <Button isIconOnly aria-label="Copy" size="sm" variant="ghost">
            <Copy className="size-4" />
          </Button>
        </InputGroup.Suffix>
      </InputGroup>
    </TextField>
  );
}

```

### Password Toggle

Use a button in the suffix to toggle password visibility.

```tsx
"use client";

import {Eye, EyeSlash} from "@gravity-ui/icons";
import {Button, InputGroup, Label, TextField} from "@heroui/react";
import {useState} from "react";

export function PasswordWithToggle() {
  const [isVisible, setIsVisible] = useState(false);

return (
    <TextField className="w-full max-w-[280px]" name="password">
      <Label>Password</Label>
      <InputGroup>
        <InputGroup.Input
          className="w-full max-w-[280px]"
          type={isVisible ? "text" : "password"}
          value={isVisible ? "87$2h.3diua" : "••••••••"}
        />
        <InputGroup.Suffix className="pr-0">
          <Button
            isIconOnly
            aria-label={isVisible ? "Hide password" : "Show password"}
            size="sm"
            variant="ghost"
            onPress={() => setIsVisible(!isVisible)}
          >
            {isVisible ? <Eye className="size-4" /> : <EyeSlash className="size-4" />}
          </Button>
        </InputGroup.Suffix>
      </InputGroup>
    </TextField>
  );
}

```

### Loading State

Show a loading spinner in the suffix to indicate processing.

```tsx
"use client";

import {InputGroup, Spinner, TextField} from "@heroui/react";

export function WithLoadingSuffix() {
  return (
    <TextField className="w-full max-w-[280px]" defaultValue="Sending..." name="status">
      <InputGroup>
        <InputGroup.Input className="w-full max-w-[280px]" />
        <InputGroup.Suffix>
          <Spinner className="size-4" />
        </InputGroup.Suffix>
      </InputGroup>
    </TextField>
  );
}

```

### Keyboard Shortcut

Display keyboard shortcuts using the [Kbd](/docs/components/kbd) component.

```tsx
"use client";

import {InputGroup, Kbd, TextField} from "@heroui/react";

export function WithKeyboardShortcut() {
  return (
    <TextField aria-label="Command" className="w-full max-w-[280px]" name="command">
      <InputGroup>
        <InputGroup.Input className="w-full max-w-[280px]" placeholder="Command" />
        <InputGroup.Suffix className="pr-2">
          <Kbd>
            <Kbd.Abbr keyValue="command" />
            <Kbd.Content>K</Kbd.Content>
          </Kbd>
        </InputGroup.Suffix>
      </InputGroup>
    </TextField>
  );
}

```

### Badge Suffix

Add a badge or chip in the suffix to show status or labels.

```tsx
"use client";

import {Chip, InputGroup, TextField} from "@heroui/react";

export function WithBadgeSuffix() {
  return (
    <TextField aria-label="Email address" className="w-full max-w-[280px]" name="email">
      <InputGroup>
        <InputGroup.Input className="w-full max-w-[280px]" placeholder="Email address" />
        <InputGroup.Suffix className="pr-2">
          <Chip color="accent" size="md" variant="soft">
            Pro
          </Chip>
        </InputGroup.Suffix>
      </InputGroup>
    </TextField>
  );
}

```

### Required Field

InputGroup respects the required state from its parent TextField.

```tsx
"use client";

import {Envelope} from "@gravity-ui/icons";
import {Description, InputGroup, Label, TextField} from "@heroui/react";

export function Required() {
  return (
    <div className="flex flex-col gap-4">
      <TextField isRequired className="w-full max-w-[280px]" name="email">
        <Label>Email address</Label>
        <InputGroup>
          <InputGroup.Prefix>
            <Envelope className="size-4 text-muted" />
          </InputGroup.Prefix>
          <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
        </InputGroup>
      </TextField>
      <TextField isRequired className="w-full max-w-[280px]" name="price">
        <Label>Set a price</Label>
        <InputGroup>
          <InputGroup.Prefix>$</InputGroup.Prefix>
          <InputGroup.Input className="w-full max-w-[200px]" placeholder="0" type="number" />
          <InputGroup.Suffix>USD</InputGroup.Suffix>
        </InputGroup>
        <Description>What customers would pay</Description>
      </TextField>
    </div>
  );
}

```

### Validation

InputGroup automatically reflects invalid state from its parent TextField.

```tsx
"use client";

import {Envelope} from "@gravity-ui/icons";
import {FieldError, InputGroup, Label, TextField} from "@heroui/react";

export function Invalid() {
  return (
    <div className="flex flex-col gap-4">
      <TextField isInvalid isRequired className="w-full max-w-[280px]" name="email">
        <Label>Email address</Label>
        <InputGroup>
          <InputGroup.Prefix>
            <Envelope className="size-4 text-muted" />
          </InputGroup.Prefix>
          <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
        </InputGroup>
        <FieldError>Please enter a valid email address</FieldError>
      </TextField>
      <TextField isInvalid isRequired className="w-full max-w-[280px]" name="price">
        <Label>Set a price</Label>
        <InputGroup>
          <InputGroup.Prefix>$</InputGroup.Prefix>
          <InputGroup.Input className="w-full max-w-[200px]" placeholder="0" type="number" />
          <InputGroup.Suffix>USD</InputGroup.Suffix>
        </InputGroup>
        <FieldError>Price must be greater than 0</FieldError>
      </TextField>
    </div>
  );
}

```

### Disabled State

InputGroup respects the disabled state from its parent TextField.

```tsx
"use client";

import {Envelope} from "@gravity-ui/icons";
import {InputGroup, Label, TextField} from "@heroui/react";

export function Disabled() {
  return (
    <div className="flex flex-col gap-4">
      <TextField
        isDisabled
        className="w-full max-w-[280px]"
        defaultValue="name@email.com"
        name="email"
      >
        <Label>Email address</Label>
        <InputGroup>
          <InputGroup.Prefix>
            <Envelope className="size-4 text-muted" />
          </InputGroup.Prefix>
          <InputGroup.Input className="w-full max-w-[280px]" />
        </InputGroup>
      </TextField>
      <TextField isDisabled className="w-full max-w-[280px]" defaultValue="10" name="price">
        <Label>Set a price</Label>
        <InputGroup>
          <InputGroup.Prefix>$</InputGroup.Prefix>
          <InputGroup.Input className="w-full max-w-[200px]" type="number" />
          <InputGroup.Suffix>USD</InputGroup.Suffix>
        </InputGroup>
      </TextField>
    </div>
  );
}

```

### Full Width

```tsx
import {Envelope, Eye} from "@gravity-ui/icons";
import {InputGroup, Label, TextField} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-4">
      <TextField fullWidth name="email">
        <Label>Email address</Label>
        <InputGroup fullWidth>
          <InputGroup.Prefix>
            <Envelope className="size-4 text-muted" />
          </InputGroup.Prefix>
          <InputGroup.Input placeholder="name@email.com" />
        </InputGroup>
      </TextField>
      <TextField fullWidth name="password">
        <Label>Password</Label>
        <InputGroup fullWidth>
          <InputGroup.Input placeholder="Enter password" type="password" />
          <InputGroup.Suffix>
            <Eye className="size-4 text-muted" />
          </InputGroup.Suffix>
        </InputGroup>
      </TextField>
    </div>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, InputGroup automatically applies on-surface styling. You can also manually control this with the `isOnSurface` prop.

```tsx
"use client";

import {Envelope} from "@gravity-ui/icons";
import {Description, InputGroup, Label, Surface, TextField} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="rounded-2xl p-6">
      <TextField className="w-full max-w-[280px]" name="email">
        <Label>Email address</Label>
        <InputGroup isOnSurface>
          <InputGroup.Prefix>
            <Envelope className="size-4 text-muted" />
          </InputGroup.Prefix>
          <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" />
        </InputGroup>
        <Description>We'll never share this with anyone else</Description>
      </TextField>
    </Surface>
  );
}

```

## Related Components

* **TextField**: Composition-friendly fields with labels and validation
* **Input**: Single-line text input built on React Aria
* **Label**: Accessible label for form controls

## Styling

### Passing Tailwind CSS classes

```tsx
import {InputGroup, TextField, Label} from '@heroui/react';

function CustomInputGroup() {
  return (
    <TextField>
      <Label>Website</Label>
      <InputGroup className="rounded-xl border-2 border-primary">
        <InputGroup.Prefix className="bg-primary/10 text-primary">
          https://
        </InputGroup.Prefix>
        <InputGroup.Input className="font-medium" />
        <InputGroup.Suffix className="bg-primary/10 text-primary">
          .com
        </InputGroup.Suffix>
      </InputGroup>
    </TextField>
  );
}

```

### Customizing the component classes

InputGroup uses CSS classes that can be customized. Override the component classes to match your design system.

```css
@layer components {
  .input-group {
    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border text-sm outline-none;
  }

.input-group__input {
    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
  }

.input-group__prefix {
    @apply text-field-placeholder rounded-l-field flex h-full items-center justify-center rounded-r-none bg-transparent px-3;
  }

.input-group__suffix {
    @apply text-field-placeholder rounded-r-field flex h-full items-center justify-center rounded-l-none bg-transparent px-3;
  }

/* On surface variant */
  .input-group--on-surface {
    @apply bg-on-surface shadow-none;
  }
}

```

### CSS Classes

* `.input-group` – Root container with border, background, and flex layout
* `.input-group__input` – Input element with transparent background and no border
* `.input-group__prefix` – Prefix container with left border radius
* `.input-group__suffix` – Suffix container with right border radius
* `.input-group--on-surface` – Variant for use on surface backgrounds

### Interactive States

InputGroup automatically manages these data attributes based on its state:

* **Hover**: `[data-hovered]` - Applied when hovering over the group
* **Focus Within**: `[data-focus-within]` - Applied when the input is focused
* **Invalid**: `[data-invalid]` - Applied when parent TextField is invalid
* **Disabled**: `[data-disabled]` or `[aria-disabled]` - Applied when parent TextField is disabled

## API Reference

### InputGroup Props

InputGroup inherits all props from React Aria's [Group](https://react-spectrum.adobe.com/react-aria/Group.html) component.

#### Base Props

| Prop        | Type                                                                       | Default | Description                                                     |
| ----------- | -------------------------------------------------------------------------- | ------- | --------------------------------------------------------------- |
| `children`  | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode`         | -       | Child components (Input, Prefix, Suffix) or render function.    |
| `className` | `string \| (values: GroupRenderProps) => string`                           | -       | CSS classes for styling, supports render props.                 |
| `style`     | `React.CSSProperties \| (values: GroupRenderProps) => React.CSSProperties` | -       | Inline styles, supports render props.                           |
| `fullWidth` | `boolean`                                                                  | `false` | Whether the input group should take full width of its container |
| `id`        | `string`                                                                   | -       | The element's unique identifier.                                |

#### Variant Props

| Prop          | Type      | Default | Description                                                                                                     |
| ------------- | --------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| `isOnSurface` | `boolean` | -       | Whether the group is displayed on a surface background. Automatically detected when inside a Surface component. |

#### Accessibility Props

| Prop               | Type                                    | Default   | Description                                                                                                    |
| ------------------ | --------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------- |
| `aria-label`       | `string`                                | -         | Accessibility label when no visible label is present.                                                          |
| `aria-labelledby`  | `string`                                | -         | ID of elements that label this group.                                                                          |
| `aria-describedby` | `string`                                | -         | ID of elements that describe this group.                                                                       |
| `aria-details`     | `string`                                | -         | ID of elements with additional details.                                                                        |
| `role`             | `'group' \| 'region' \| 'presentation'` | `'group'` | Accessibility role for the group. Use 'region' for important content, 'presentation' for visual-only grouping. |

### Composition Components

InputGroup works with these subcomponents:

* **InputGroup.Root** - Root container (also available as `InputGroup`)
* **InputGroup.Input** - Input element component
* **InputGroup.Prefix** - Prefix container component
* **InputGroup.Suffix** - Suffix container component

#### InputGroup.Input Props

InputGroup.Input inherits all props from React Aria's [Input](https://react-spectrum.adobe.com/react-aria/Input.html) component.

| Prop           | Type      | Default  | Description                                             |
| -------------- | --------- | -------- | ------------------------------------------------------- |
| `className`    | `string`  | -        | CSS classes for styling.                                |
| `isOnSurface`  | `boolean` | -        | Whether the input is displayed on a surface background. |
| `type`         | `string`  | `'text'` | Input type (text, password, email, etc.).               |
| `value`        | `string`  | -        | Current value (controlled).                             |
| `defaultValue` | `string`  | -        | Default value (uncontrolled).                           |
| `placeholder`  | `string`  | -        | Placeholder text.                                       |
| `disabled`     | `boolean` | -        | Whether the input is disabled.                          |
| `readOnly`     | `boolean` | -        | Whether the input is read-only.                         |

#### InputGroup.Prefix Props

| Prop        | Type              | Default | Description                                           |
| ----------- | ----------------- | ------- | ----------------------------------------------------- |
| `children`  | `React.ReactNode` | -       | Content to display in the prefix (icons, text, etc.). |
| `className` | `string`          | -       | CSS classes for styling.                              |

#### InputGroup.Suffix Props

| Prop        | Type              | Default | Description                                                      |
| ----------- | ----------------- | ------- | ---------------------------------------------------------------- |
| `children`  | `React.ReactNode` | -       | Content to display in the suffix (icons, buttons, badges, etc.). |
| `className` | `string`          | -       | CSS classes for styling.                                         |

### Usage Example

```tsx
import {InputGroup, TextField, Label, Button} from '@heroui/react';
import {Icon} from '@iconify/react';

function Example() {
  return (
    <TextField>
      <Label>Email</Label>
      <InputGroup>
        <InputGroup.Prefix>
          <Icon icon="gravity-ui:envelope" />
        </InputGroup.Prefix>
        <InputGroup.Input placeholder="name@email.com" />
        <InputGroup.Suffix>
          <Button isIconOnly size="sm" variant="ghost">
            <Icon icon="gravity-ui:check" />
          </Button>
        </InputGroup.Suffix>
      </InputGroup>
    </TextField>
  );
}

```

</page>

<page url="/docs/react/components/input-otp">
# InputOTP

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/input-otp
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/input-otp.mdx
> A one-time password input component for verification codes and secure authentication

## Import

```tsx
import { InputOTP } from '@heroui/react';

```

### Usage

```tsx
import {InputOTP, Label, Link} from "@heroui/react";

```

### Anatomy

Import the InputOTP component and access all parts using dot notation.

```tsx
import { InputOTP } from '@heroui/react';

export default () => (
  <InputOTP maxLength={6}>
    <InputOTP.Group>
      <InputOTP.Slot index={0} />
      <InputOTP.Slot index={1} />
      {/* ...rest of the slots */}
    </InputOTP.Group>
    <InputOTP.Separator />
    <InputOTP.Group>
      <InputOTP.Slot index={3} />
      {/* ...rest of the slots */}
    </InputOTP.Group>
  </InputOTP>
)

```

> **InputOTP** is built on top of [input-otp](https://github.com/guilhermerodz/input-otp) by [@guilherme\_rodz](https://twitter.com/guilherme_rodz), providing a flexible and accessible foundation for OTP input components.

### Four Digits

```tsx
import {InputOTP, Label} from "@heroui/react";

export function FourDigits() {
  return (
    <div className="flex w-[280px] flex-col gap-2">
      <Label>Enter PIN</Label>
      <InputOTP maxLength={4}>
        <InputOTP.Group>
          <InputOTP.Slot index={0} />
          <InputOTP.Slot index={1} />
          <InputOTP.Slot index={2} />
          <InputOTP.Slot index={3} />
        </InputOTP.Group>
      </InputOTP>
    </div>
  );
}

```

### Disabled State

```tsx
import {Description, InputOTP, Label} from "@heroui/react";

export function Disabled() {
  return (
    <div className="flex w-[280px] flex-col gap-2">
      <Label isDisabled>Verify account</Label>
      <Description>Code verification is currently disabled</Description>
      <InputOTP isDisabled maxLength={6}>
        <InputOTP.Group>
          <InputOTP.Slot index={0} />
          <InputOTP.Slot index={1} />
          <InputOTP.Slot index={2} />
        </InputOTP.Group>
        <InputOTP.Separator />
        <InputOTP.Group>
          <InputOTP.Slot index={3} />
          <InputOTP.Slot index={4} />
          <InputOTP.Slot index={5} />
        </InputOTP.Group>
      </InputOTP>
    </div>
  );
}

```

### With Pattern

Use the `pattern` prop to restrict input to specific characters. HeroUI exports common patterns like `REGEXP_ONLY_CHARS` and `REGEXP_ONLY_DIGITS`.

```tsx
import {Description, InputOTP, Label, REGEXP_ONLY_CHARS} from "@heroui/react";

export function WithPattern() {
  return (
    <div className="flex w-[280px] flex-col gap-2">
      <Label>Enter code (letters only)</Label>
      <Description>Only alphabetic characters are allowed</Description>
      <InputOTP maxLength={6} pattern={REGEXP_ONLY_CHARS}>
        <InputOTP.Group>
          <InputOTP.Slot index={0} />
          <InputOTP.Slot index={1} />
          <InputOTP.Slot index={2} />
        </InputOTP.Group>
        <InputOTP.Separator />
        <InputOTP.Group>
          <InputOTP.Slot index={3} />
          <InputOTP.Slot index={4} />
          <InputOTP.Slot index={5} />
        </InputOTP.Group>
      </InputOTP>
    </div>
  );
}

```

### Controlled

Control the value to synchronize with state, clear the input, or implement custom validation.

```tsx
"use client";

import {Description, InputOTP, Label} from "@heroui/react";
import React from "react";

export function Controlled() {
  const [value, setValue] = React.useState("");

return (
    <div className="flex w-[280px] flex-col gap-2">
      <Label>Verify account</Label>
      <InputOTP maxLength={6} value={value} onChange={setValue}>
        <InputOTP.Group>
          <InputOTP.Slot index={0} />
          <InputOTP.Slot index={1} />
          <InputOTP.Slot index={2} />
        </InputOTP.Group>
        <InputOTP.Separator />
        <InputOTP.Group>
          <InputOTP.Slot index={3} />
          <InputOTP.Slot index={4} />
          <InputOTP.Slot index={5} />
        </InputOTP.Group>
      </InputOTP>
      <Description>
        {value.length > 0 ? (
          <>
            Value: {value} ({value.length}/6) •{" "}
            <button className="font-medium text-foreground underline" onClick={() => setValue("")}>
              Clear
            </button>
          </>
        ) : (
          "Enter a 6-digit code"
        )}
      </Description>
    </div>
  );
}

```

### With Validation

Use `isInvalid` together with validation messages to surface errors.

```tsx
"use client";

import {Button, Description, Form, InputOTP, Label} from "@heroui/react";
import React from "react";

export function WithValidation() {
  const [value, setValue] = React.useState("");
  const [isInvalid, setIsInvalid] = React.useState(false);

const onSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();
    const formData = new FormData(e.currentTarget);
    const code = formData.get("code");

if (code !== "123456") {
      setIsInvalid(true);

return;
    }

setIsInvalid(false);
    setValue("");

alert("Code verified successfully!");
  };

const handleChange = (val: string) => {
    setValue(val);
    setIsInvalid(false);
  };

return (
    <div className="flex w-[280px] flex-col gap-2">
      <Form className="flex flex-col gap-2" onSubmit={onSubmit}>
        <Label>Verify account</Label>
        <Description>Hint: The code is 123456</Description>
        <InputOTP
          aria-describedby={isInvalid ? "code-error" : undefined}
          isInvalid={isInvalid}
          maxLength={6}
          name="code"
          value={value}
          onChange={handleChange}
        >
          <InputOTP.Group>
            <InputOTP.Slot index={0} />
            <InputOTP.Slot index={1} />
            <InputOTP.Slot index={2} />
          </InputOTP.Group>
          <InputOTP.Separator />
          <InputOTP.Group>
            <InputOTP.Slot index={3} />
            <InputOTP.Slot index={4} />
            <InputOTP.Slot index={5} />
          </InputOTP.Group>
        </InputOTP>
        <span className="field-error" data-visible={isInvalid} id="code-error">
          Invalid code. Please try again.
        </span>
        <Button isDisabled={value.length !== 6} type="submit">
          Submit
        </Button>
      </Form>
    </div>
  );
}

```

### On Complete

Use the `onComplete` callback to trigger actions when all slots are filled.

```tsx
"use client";

import {Button, Form, InputOTP, Label, Spinner} from "@heroui/react";
import React from "react";

export function OnComplete() {
  const [value, setValue] = React.useState("");
  const [isComplete, setIsComplete] = React.useState(false);
  const [isSubmitting, setIsSubmitting] = React.useState(false);

const handleComplete = (code: string) => {
    setIsComplete(true);

console.log("Code complete:", code);
  };

const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => {
    e.preventDefault();

setIsSubmitting(true);
    // Simulate API call
    setTimeout(() => {
      setIsSubmitting(false);
      setValue("");
      setIsComplete(false);
    }, 2000);
  };

return (
    <Form className="flex w-[280px] flex-col gap-2" onSubmit={handleSubmit}>
      <Label>Verify account</Label>
      <InputOTP
        maxLength={6}
        value={value}
        onComplete={handleComplete}
        onChange={(val) => {
          setValue(val);
          setIsComplete(false);
        }}
      >
        <InputOTP.Group>
          <InputOTP.Slot index={0} />
          <InputOTP.Slot index={1} />
          <InputOTP.Slot index={2} />
        </InputOTP.Group>
        <InputOTP.Separator />
        <InputOTP.Group>
          <InputOTP.Slot index={3} />
          <InputOTP.Slot index={4} />
          <InputOTP.Slot index={5} />
        </InputOTP.Group>
      </InputOTP>
      <Button
        className="mt-2 w-full"
        isDisabled={!isComplete}
        isPending={isSubmitting}
        type="submit"
        variant="primary"
      >
        {isSubmitting ? (
          <>
            <Spinner color="current" size="sm" />
            Verifying...
          </>
        ) : (
          "Verify Code"
        )}
      </Button>
    </Form>
  );
}

```

### Form Example

A complete two-factor authentication form with validation and submission.

```tsx
"use client";

import {Button, Description, Form, InputOTP, Label, Link, Spinner} from "@heroui/react";
import React from "react";

export function FormExample() {
  const [value, setValue] = React.useState("");
  const [error, setError] = React.useState("");
  const [isSubmitting, setIsSubmitting] = React.useState(false);

const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    setError("");

if (value.length !== 6) {
      setError("Please enter all 6 digits");

return;
    }

setIsSubmitting(true);

// Simulate API call
    setTimeout(() => {
      if (value === "123456") {
        console.log("Code verified successfully!");
        setValue("");
      } else {
        setError("Invalid code. Please try again.");
      }
      setIsSubmitting(false);
    }, 1500);
  };

return (
    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
      <div className="flex flex-col gap-2">
        <Label>Two-factor authentication</Label>
        <Description>Enter the 6-digit code from your authenticator app</Description>
        <InputOTP
          isInvalid={!!error}
          maxLength={6}
          value={value}
          onChange={(val) => {
            setValue(val);
            setError("");
          }}
        >
          <InputOTP.Group>
            <InputOTP.Slot index={0} />
            <InputOTP.Slot index={1} />
            <InputOTP.Slot index={2} />
          </InputOTP.Group>
          <InputOTP.Separator />
          <InputOTP.Group>
            <InputOTP.Slot index={3} />
            <InputOTP.Slot index={4} />
            <InputOTP.Slot index={5} />
          </InputOTP.Group>
        </InputOTP>
        <span className="field-error" data-visible={!!error} id="code-error">
          {error}
        </span>
      </div>
      <Button
        className="w-full"
        isDisabled={value.length !== 6}
        isPending={isSubmitting}
        type="submit"
        variant="primary"
      >
        {isSubmitting ? (
          <>
            <Spinner color="current" size="sm" />
            Verifying...
          </>
        ) : (
          "Verify"
        )}
      </Button>
      <div className="flex items-center justify-center gap-1">
        <p className="text-sm text-muted">Having trouble?</p>
        <Link className="text-sm text-foreground" underline="always">
          Use backup code
        </Link>
      </div>
    </Form>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, InputOTP automatically applies on-surface styling.

```tsx
import {InputOTP, Label, Link, Surface} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="flex w-full flex-col gap-2 rounded-3xl p-6">
      <div className="flex flex-col gap-1">
        <Label>Verify account</Label>
        <p className="text-sm text-muted">We've sent a code to a****@gmail.com</p>
      </div>
      <InputOTP maxLength={6}>
        <InputOTP.Group>
          <InputOTP.Slot index={0} />
          <InputOTP.Slot index={1} />
          <InputOTP.Slot index={2} />
        </InputOTP.Group>
        <InputOTP.Separator />
        <InputOTP.Group>
          <InputOTP.Slot index={3} />
          <InputOTP.Slot index={4} />
          <InputOTP.Slot index={5} />
        </InputOTP.Group>
      </InputOTP>
      <div className="flex items-center gap-[5px] px-1 pt-1">
        <p className="text-sm text-muted">Didn't receive a code?</p>
        <Link className="text-foreground" underline="always">
          Resend
        </Link>
      </div>
    </Surface>
  );
}

```

## Related Components

* **Input**: Single-line text input built on React Aria
* **Form**: Form validation and submission handling
* **Surface**: Base container surface

## Styling

### Passing Tailwind CSS classes

```tsx
import {InputOTP, Label} from '@heroui/react';

function CustomInputOTP() {
  return (
    <div className="flex flex-col gap-2">
      <Label className="text-sm font-semibold">Enter verification code</Label>
      <InputOTP
        className="gap-3"
        containerClassName="gap-4"
        maxLength={6}
      >
        <InputOTP.Group className="gap-3">
          <InputOTP.Slot
            className="size-12 rounded-lg border-2 text-lg font-bold"
            index={0}
          />
          <InputOTP.Slot
            className="size-12 rounded-lg border-2 text-lg font-bold"
            index={1}
          />
          <InputOTP.Slot
            className="size-12 rounded-lg border-2 text-lg font-bold"
            index={2}
          />
        </InputOTP.Group>
        <InputOTP.Separator className="bg-border h-1 w-2 rounded-full" />
        <InputOTP.Group className="gap-3">
          <InputOTP.Slot
            className="size-12 rounded-lg border-2 text-lg font-bold"
            index={3}
          />
          <InputOTP.Slot
            className="size-12 rounded-lg border-2 text-lg font-bold"
            index={4}
          />
          <InputOTP.Slot
            className="size-12 rounded-lg border-2 text-lg font-bold"
            index={5}
          />
        </InputOTP.Group>
      </InputOTP>
    </div>
  );
}

```

### Customizing the component classes

To customize the InputOTP component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .input-otp {
    @apply gap-3;
  }

.input-otp__slot {
    @apply size-12 rounded-xl border-2 font-bold;
  }

.input-otp__slot[data-active="true"] {
    @apply border-primary-500 ring-2 ring-primary-200;
  }

.input-otp__separator {
    @apply w-2 h-1 bg-border-strong rounded-full;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The InputOTP component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/input-otp.css)):

#### Base Classes

* `.input-otp` - Base container
* `.input-otp__container` - Inner container from input-otp library
* `.input-otp__group` - Group of slots
* `.input-otp__slot` - Individual input slot
* `.input-otp__slot-value` - The character inside a slot
* `.input-otp__caret` - Blinking caret indicator
* `.input-otp__separator` - Visual separator between groups

#### State Classes

* `.input-otp__slot[data-active="true"]` - Currently active slot
* `.input-otp__slot[data-filled="true"]` - Slot with a character
* `.input-otp__slot[data-disabled="true"]` - Disabled slot
* `.input-otp__slot[data-invalid="true"]` - Invalid slot
* `.input-otp__container[data-disabled="true"]` - Disabled container

### Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

* **Hover**: `:hover` or `[data-hovered="true"]` on slot
* **Active**: `[data-active="true"]` on slot (currently focused)
* **Filled**: `[data-filled="true"]` on slot (contains a character)
* **Disabled**: `[data-disabled="true"]` on container and slots
* **Invalid**: `[data-invalid="true"]` on slots

## API Reference

### InputOTP Props

InputOTP is built on top of the [input-otp](https://github.com/guilhermerodz/input-otp) library with additional features.

#### Base Props

| Prop                 | Type                      | Default | Description                                                       |
| -------------------- | ------------------------- | ------- | ----------------------------------------------------------------- |
| `maxLength`          | `number`                  | -       | **Required.** Number of input slots.                              |
| `value`              | `string`                  | -       | Controlled value (uncontrolled if not provided).                  |
| `onChange`           | `(value: string) => void` | -       | Handler called when the value changes.                            |
| `onComplete`         | `(value: string) => void` | -       | Handler called when all slots are filled.                         |
| `className`          | `string`                  | -       | Additional CSS classes for the container.                         |
| `containerClassName` | `string`                  | -       | CSS classes for the inner container.                              |
| `isOnSurface`        | `boolean`                 | `false` | Whether the input is displayed on a surface (affects styling)     |
| `children`           | `React.ReactNode`         | -       | InputOTP.Group, InputOTP.Slot, and InputOTP.Separator components. |

#### Validation Props

| Prop                | Type            | Default | Description                               |
| ------------------- | --------------- | ------- | ----------------------------------------- |
| `isDisabled`        | `boolean`       | `false` | Whether the input is disabled.            |
| `isInvalid`         | `boolean`       | `false` | Whether the input is in an invalid state. |
| `validationErrors`  | `string[]`      | -       | Server-side or custom validation errors.  |
| `validationDetails` | `ValidityState` | -       | HTML5 validation details.                 |

#### Input Props

| Prop               | Type                                                                        | Default     | Description                                                        |
| ------------------ | --------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------ |
| `pattern`          | `string`                                                                    | -           | Regex pattern for allowed characters (e.g., `REGEXP_ONLY_DIGITS`). |
| `textAlign`        | `'left' \| 'center' \| 'right'`                                             | `'left'`    | Text alignment within slots.                                       |
| `inputMode`        | `'numeric' \| 'text' \| 'decimal' \| 'tel' \| 'search' \| 'email' \| 'url'` | `'numeric'` | Virtual keyboard type on mobile devices.                           |
| `placeholder`      | `string`                                                                    | -           | Placeholder text for empty slots.                                  |
| `pasteTransformer` | `(text: string) => string`                                                  | -           | Transform pasted text (e.g., remove hyphens).                      |

#### Form Props

| Prop        | Type      | Default | Description                               |
| ----------- | --------- | ------- | ----------------------------------------- |
| `name`      | `string`  | -       | Name attribute for form submission.       |
| `autoFocus` | `boolean` | -       | Whether to focus the first slot on mount. |

### InputOTP.Group Props

| Prop        | Type              | Default | Description                           |
| ----------- | ----------------- | ------- | ------------------------------------- |
| `className` | `string`          | -       | Additional CSS classes for the group. |
| `children`  | `React.ReactNode` | -       | InputOTP.Slot components.             |

### InputOTP.Slot Props

| Prop        | Type     | Default | Description                                 |
| ----------- | -------- | ------- | ------------------------------------------- |
| `index`     | `number` | -       | **Required.** Zero-based index of the slot. |
| `className` | `string` | -       | Additional CSS classes for the slot.        |

### InputOTP.Separator Props

| Prop        | Type     | Default | Description                               |
| ----------- | -------- | ------- | ----------------------------------------- |
| `className` | `string` | -       | Additional CSS classes for the separator. |

### Exported Patterns

HeroUI re-exports common regex patterns from input-otp for convenience:

```tsx
import { REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS_AND_CHARS } from '@heroui/react';

// Use with pattern prop
<InputOTP pattern={REGEXP_ONLY_DIGITS} maxLength={6}>
  {/* ... */}
</InputOTP>

```

* **REGEXP\_ONLY\_DIGITS** - Only numeric characters (0-9)
* **REGEXP\_ONLY\_CHARS** - Only alphabetic characters (a-z, A-Z)
* **REGEXP\_ONLY\_DIGITS\_AND\_CHARS** - Alphanumeric characters (0-9, a-z, A-Z)

</page>

<page url="/docs/react/components/input">
# Input

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/input
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/input.mdx
> Primitive single-line text input component that accepts standard HTML attributes

## Import

```tsx
import { Input } from '@heroui/react';

```

<Callout>
  For validation, labels, and error messages, see **[TextField](/docs/components/text-field)**.
</Callout>

### Usage

```tsx
import {Input} from "@heroui/react";

export function Basic() {
  return <Input aria-label="Name" className="w-64" placeholder="Enter your name" />;
}

```

### Input Types

```tsx
import {Input, Label} from "@heroui/react";

export function Types() {
  return (
    <div className="flex w-80 flex-col gap-4">
      <div className="flex flex-col gap-1">
        <Label htmlFor="input-type-email">Email</Label>
        <Input id="input-type-email" placeholder="jane@example.com" type="email" />
      </div>
      <div className="flex flex-col gap-1">
        <Label htmlFor="input-type-number">Age</Label>
        <Input id="input-type-number" min={0} placeholder="30" type="number" />
      </div>
      <div className="flex flex-col gap-1">
        <Label htmlFor="input-type-password">Password</Label>
        <Input id="input-type-password" placeholder="••••••••" type="password" />
      </div>
    </div>
  );
}

```

### Controlled

```tsx
"use client";

import {Input} from "@heroui/react";
import React from "react";

export function Controlled() {
  const [value, setValue] = React.useState("heroui.com");

return (
    <div className="flex w-80 flex-col gap-2">
      <Input
        aria-label="Domain"
        placeholder="domain"
        value={value}
        onChange={(event) => setValue(event.target.value)}
      />
      <span className="px-1 text-sm text-muted">https://{value || "your-domain"}</span>
    </div>
  );
}

```

### Full Width

```tsx
import {Input} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-3">
      <Input fullWidth placeholder="Full width input" />
    </div>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, Input automatically applies on-surface styling.

```tsx
import {Input, Surface} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="flex h-[180px] w-[280px] items-center justify-center rounded-3xl bg-surface p-4">
      <Input className="w-full" placeholder="Your name" />
    </Surface>
  );
}

```

## Related Components

* **TextField**: Composition-friendly fields with labels and validation
* **TextArea**: Multiline text input with focus management
* **Label**: Accessible label for form controls

## Styling

### Passing Tailwind CSS classes

```tsx
import {Input, Label} from '@heroui/react';

function CustomInput() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="custom-input">Project name</Label>
      <Input
        id="custom-input"
        className="rounded-xl border border-border/70 bgsurface px-4 py-2 text-sm shadow-sm focus-visible:border-primary"
        placeholder="New web app"
      />
    </div>
  );
}

```

### Customizing the component classes

The base class `.input` powers every instance. Override it once with `@layer components`.

```css
@layer components {
  .input {
    @apply rounded-lg border border-border bgsurface px-4 py-2 text-sm shadow-sm transition-colors;

&:hover,
    &[data-hovered="true"] {
      @apply bg-surface-secondary border-border/80;
    }

&:focus-visible,
    &[data-focus-visible="true"] {
      @apply border-primary ring-2 ring-primary/20;
    }

&[data-invalid="true"] {
      @apply border-danger bg-danger-50/10 text-danger;
    }
  }
}

```

### CSS Classes

* `.input` – Native input element styling

### Interactive States

* **Hover**: `:hover` or `[data-hovered="true"]`
* **Focus Visible**: `:focus-visible` or `[data-focus-visible="true"]`
* **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`)
* **Disabled**: `:disabled` or `[aria-disabled="true"]`
* **Read Only**: `[aria-readonly="true"]`

## API Reference

### Input Props

Input accepts all standard HTML `<input>` attributes plus the following:

| Prop           | Type                                                   | Default  | Description                                                   |
| -------------- | ------------------------------------------------------ | -------- | ------------------------------------------------------------- |
| `className`    | `string`                                               | -        | Tailwind classes merged with the component styles.            |
| `type`         | `string`                                               | `"text"` | Input type (text, email, password, number, etc.).             |
| `value`        | `string`                                               | -        | Controlled value.                                             |
| `defaultValue` | `string`                                               | -        | Uncontrolled initial value.                                   |
| `onChange`     | `(event: React.ChangeEvent<HTMLInputElement>) => void` | -        | Change handler.                                               |
| `placeholder`  | `string`                                               | -        | Placeholder text.                                             |
| `disabled`     | `boolean`                                              | `false`  | Disables the input.                                           |
| `readOnly`     | `boolean`                                              | `false`  | Makes the input read-only.                                    |
| `required`     | `boolean`                                              | `false`  | Marks the input as required.                                  |
| `name`         | `string`                                               | -        | Name for form submission.                                     |
| `autoComplete` | `string`                                               | -        | Autocomplete hint for the browser.                            |
| `maxLength`    | `number`                                               | -        | Maximum number of characters.                                 |
| `minLength`    | `number`                                               | -        | Minimum number of characters.                                 |
| `pattern`      | `string`                                               | -        | Regex pattern for validation.                                 |
| `min`          | `number \| string`                                     | -        | Minimum value (for number/date inputs).                       |
| `max`          | `number \| string`                                     | -        | Maximum value (for number/date inputs).                       |
| `step`         | `number \| string`                                     | -        | Stepping interval (for number inputs).                        |
| `fullWidth`    | `boolean`                                              | `false`  | Whether the input should take full width of its container     |
| `isOnSurface`  | `boolean`                                              | `false`  | Whether the input is displayed on a surface (affects styling) |

> For validation props like `isInvalid`, `isRequired`, and error handling, use **[TextField](/docs/components/text-field)** with Input as a child component.

</page>

<page url="/docs/react/components/label">
# Label

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/label
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/label.mdx
> Renders an accessible label associated with form controls

## Import

```tsx
import { Label } from '@heroui/react';

```

## Usage

```tsx
import {Input, Label} from "@heroui/react";

```

## Related Components

* **Input**: Single-line text input built on React Aria
* **TextArea**: Multiline text input with focus management
* **Fieldset**: Group related form controls with legends

## API

### Label Props

| Prop         | Type        | Default | Description                                        |
| ------------ | ----------- | ------- | -------------------------------------------------- |
| `htmlFor`    | `string`    | -       | The id of the element the label is associated with |
| `isRequired` | `boolean`   | `false` | Whether to display a required indicator            |
| `isDisabled` | `boolean`   | `false` | Whether the label is in a disabled state           |
| `isInvalid`  | `boolean`   | `false` | Whether the label is in an invalid state           |
| `className`  | `string`    | -       | Additional CSS classes                             |
| `children`   | `ReactNode` | -       | The content of the label                           |

## Accessibility

The Label component is built on the native HTML `<label>` element ([MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)) and follows WAI-ARIA best practices:

* Associates with form controls using the `htmlFor` attribute
* Provides semantic HTML `<label>` element
* Supports keyboard navigation when associated with form controls
* Communicates required and invalid states to screen readers
* Clicking the label focuses/activates the associated form control

## Related Components

* **Input**: Single-line text input built on React Aria
* **TextArea**: Multiline text input with focus management
* **Fieldset**: Group related form controls with legends

## Styling

### CSS Classes

The Label component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/label.css)):

#### Base Classes

* `.label` - Base label styles with text styling

#### State Modifier Classes

* `.label--required` or `[data-required="true"] > .label` - Shows required asterisk indicator
* `.label--disabled` or `[data-disabled="true"] .label` - Disabled state styling
* `.label--invalid` or `[data-invalid="true"] .label` or `[aria-invalid="true"] .label` - Invalid state styling (danger/red text color)

**Note**: The required asterisk is smartly applied using role and data-slot detection. It excludes:

* Elements with `role="group"`, `role="radiogroup"`, or `role="checkboxgroup"`
* Elements with `data-slot="radio"` or `data-slot="checkbox"`

This prevents duplicate asterisks when using group components with required fields.

## Examples

### With Required Indicator

```tsx
<Label htmlFor="email" isRequired>
  Email Address
</Label>
<Input id="email" type="email" />

```

### With Disabled State

```tsx
<Label htmlFor="username" isDisabled>
  Username
</Label>
<Input id="username" isDisabled />

```

### With Invalid State

```tsx
<Label htmlFor="password" isInvalid>
  Password
</Label>
<Input id="password" isInvalid />
```

</page>

<page url="/docs/react/components/number-field">
# NumberField

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/number-field
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/number-field.mdx
> Number input fields with increment/decrement buttons, validation, and internationalized formatting

## Import

```tsx
import { NumberField } from '@heroui/react';

```

### Usage

```tsx
import {Label, NumberField} from "@heroui/react";

```

### Anatomy

```tsx
import {NumberField, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <NumberField>
    <Label />
    <NumberField.Group>
      <NumberField.DecrementButton />
      <NumberField.Input />
      <NumberField.IncrementButton />
    </NumberField.Group>
    <Description />
    <FieldError />
  </NumberField>
)

```

> **NumberField** allows users to enter numeric values with optional increment/decrement buttons. It supports internationalized formatting, validation, and keyboard navigation.

### With Description

```tsx
import {Description, Label, NumberField} from "@heroui/react";

export function WithDescription() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <NumberField defaultValue={1024} minValue={0} name="width">
        <Label>Width</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Enter the width in pixels</Description>
      </NumberField>
      <NumberField
        defaultValue={0.5}
        formatOptions={{style: "percent"}}
        maxValue={1}
        minValue={0}
        name="percentage"
        step={0.1}
      >
        <Label>Percentage</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Value must be between 0 and 100</Description>
      </NumberField>
    </div>
  );
}

```

### Required Field

```tsx
import {Description, Label, NumberField} from "@heroui/react";

export function Required() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <NumberField isRequired minValue={0} name="quantity">
        <Label>Quantity</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
      </NumberField>
      <NumberField isRequired defaultValue={1} maxValue={10} minValue={1} name="rating">
        <Label>Rating</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Rate from 1 to 10</Description>
      </NumberField>
    </div>
  );
}

```

### Validation

Use `isInvalid` together with `FieldError` to surface validation messages.

```tsx
import {FieldError, Label, NumberField} from "@heroui/react";

export function Validation() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <NumberField isInvalid isRequired minValue={0} name="quantity" value={-5}>
        <Label>Quantity</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <FieldError>Quantity must be greater than or equal to 0</FieldError>
      </NumberField>
      <NumberField
        isInvalid
        formatOptions={{style: "percent"}}
        maxValue={1}
        minValue={0}
        name="percentage"
        step={0.1}
        value={1.5}
      >
        <Label>Percentage</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <FieldError>Percentage must be between 0 and 100</FieldError>
      </NumberField>
    </div>
  );
}

```

### Controlled

Control the value to synchronize with other components or perform custom formatting.

```tsx
"use client";

import {Button, Description, Label, NumberField} from "@heroui/react";
import React from "react";

export function Controlled() {
  const [value, setValue] = React.useState(1024);

return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <NumberField minValue={0} name="width" value={value} onChange={setValue}>
        <Label>Width</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Current value: {value}</Description>
      </NumberField>
      <div className="flex gap-2">
        <Button variant="tertiary" onPress={() => setValue(0)}>
          Reset to 0
        </Button>
        <Button variant="tertiary" onPress={() => setValue(2048)}>
          Set to 2048
        </Button>
      </div>
    </div>
  );
}

```

### With Validation

Implement custom validation logic with controlled values.

```tsx
"use client";

import {Description, FieldError, Label, NumberField} from "@heroui/react";
import React from "react";

export function WithValidation() {
  const [value, setValue] = React.useState<number | undefined>(undefined);
  const isInvalid = value !== undefined && (value < 0 || value > 100);

return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <NumberField
        isRequired
        formatOptions={{style: "percent"}}
        isInvalid={isInvalid}
        maxValue={1}
        minValue={0}
        name="percentage"
        step={0.1}
        value={value}
        onChange={setValue}
      >
        <Label>Percentage</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        {isInvalid ? (
          <FieldError>Percentage must be between 0 and 100</FieldError>
        ) : (
          <Description>Enter a value between 0 and 100</Description>
        )}
      </NumberField>
    </div>
  );
}

```

### Step Values

Configure increment/decrement step values for precise control.

```tsx
import {Description, Label, NumberField} from "@heroui/react";

export function WithStep() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step1" step={1}>
        <Label>Step: 1</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Increments by 1</Description>
      </NumberField>
      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step5" step={5}>
        <Label>Step: 5</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Increments by 5</Description>
      </NumberField>
      <NumberField defaultValue={0} maxValue={100} minValue={0} name="step10" step={10}>
        <Label>Step: 10</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Increments by 10</Description>
      </NumberField>
    </div>
  );
}

```

### Format Options

Format numbers as currency, percentages, decimals, or units with internationalization support.

```tsx
import {Description, Label, NumberField} from "@heroui/react";

export function WithFormatOptions() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <NumberField
        defaultValue={99}
        minValue={0}
        name="currency-eur"
        formatOptions={{
          currency: "EUR",
          currencySign: "accounting",
          style: "currency",
        }}
      >
        <Label>Currency (EUR - Accounting)</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Accounting format with EUR currency</Description>
      </NumberField>
      <NumberField
        defaultValue={99.99}
        minValue={0}
        name="currency-usd"
        formatOptions={{
          currency: "USD",
          style: "currency",
        }}
      >
        <Label>Currency (USD)</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Standard USD currency format</Description>
      </NumberField>
      <NumberField
        defaultValue={0.5}
        formatOptions={{style: "percent"}}
        maxValue={1}
        minValue={0}
        name="percentage"
        step={0.01}
      >
        <Label>Percentage</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Percentage format (0-1, where 0.5 = 50%)</Description>
      </NumberField>
      <NumberField
        defaultValue={1234.56}
        minValue={0}
        name="decimal"
        formatOptions={{
          maximumFractionDigits: 2,
          minimumFractionDigits: 2,
          style: "decimal",
        }}
      >
        <Label>Decimal (2 decimal places)</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Decimal format with 2 decimal places</Description>
      </NumberField>
      <NumberField
        defaultValue={1000}
        minValue={0}
        name="unit"
        formatOptions={{
          style: "unit",
          unit: "kilogram",
          unitDisplay: "short",
        }}
      >
        <Label>Unit (Kilograms)</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Unit format with kilograms</Description>
      </NumberField>
    </div>
  );
}

```

### Custom Icons

Customize the increment and decrement button icons.

```tsx
import {Description, Label, NumberField} from "@heroui/react";

export function CustomIcons() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <NumberField defaultValue={1024} minValue={0} name="width">
        <Label>Width (Custom Icons)</Label>
        <NumberField.Group>
          <NumberField.DecrementButton>
            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
              <path
                clipRule="evenodd"
                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m-2-6.5a.75.75 0 0 0 0 1.5h4a.75.75 0 0 0 0-1.5z"
                fill="currentColor"
                fillRule="evenodd"
              />
            </svg>
          </NumberField.DecrementButton>
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton>
            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
              <path
                clipRule="evenodd"
                d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m.75-7.75a.75.75 0 0 0-1.5 0V6H4.75a.75.75 0 0 0 0 1.5H6v1.25a.75.75 0 0 0 1.5 0V7.5h1.25a.75.75 0 0 0 0-1.5H7.5z"
                fill="currentColor"
                fillRule="evenodd"
              />
            </svg>
          </NumberField.IncrementButton>
        </NumberField.Group>
        <Description>Custom icon children</Description>
      </NumberField>
    </div>
  );
}

```

### With Chevrons

Use chevron icons in a vertical layout for a different visual style.

```tsx
import {Label, NumberField} from "@heroui/react";

export function WithChevrons() {
  return (
    <NumberField
      className="w-full max-w-64"
      defaultValue={99}
      minValue={0}
      name="amount"
      formatOptions={{
        currency: "EUR",
        currencySign: "accounting",
        style: "currency",
      }}
    >
      <Label>Number field with chevrons</Label>
      <NumberField.Group>
        <NumberField.Input />
        <div className="flex h-[calc(100%+2px)] flex-col border-l border-field-placeholder/15">
          <NumberField.IncrementButton className="-ml-px flex h-1/2 w-6 flex-1 rounded-none border-r-0 border-l-0 pt-0.5 text-sm">
            <svg
              aria-hidden="true"
              height="11"
              viewBox="0 0 16 16"
              width="11"
              xmlns="http://www.w3.org/2000/svg"
            >
              <path
                clipRule="evenodd"
                d="M13.03 10.53a.75.75 0 0 1-1.06 0L8 6.56l-3.97 3.97a.75.75 0 1 1-1.06-1.06l4.5-4.5a.75.75 0 0 1 1.06 0l4.5 4.5a.75.75 0 0 1 0 1.06"
                fill="currentColor"
                fillRule="evenodd"
              />
            </svg>
          </NumberField.IncrementButton>
          <NumberField.DecrementButton className="-ml-px flex h-1/2 w-6 flex-1 rounded-none border-r-0 border-l-0 pb-0.5 text-sm">
            <svg
              aria-hidden="true"
              height="11"
              viewBox="0 0 16 16"
              width="11"
              xmlns="http://www.w3.org/2000/svg"
            >
              <path
                clipRule="evenodd"
                d="M2.97 5.47a.75.75 0 0 1 1.06 0L8 9.44l3.97-3.97a.75.75 0 1 1 1.06 1.06l-4.5 4.5a.75.75 0 0 1-1.06 0l-4.5-4.5a.75.75 0 0 1 0-1.06"
                fill="currentColor"
                fillRule="evenodd"
              />
            </svg>
          </NumberField.DecrementButton>
        </div>
      </NumberField.Group>
    </NumberField>
  );
}

```

### Disabled State

```tsx
import {Description, Label, NumberField} from "@heroui/react";

export function Disabled() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <NumberField isDisabled defaultValue={1024} minValue={0} name="width">
        <Label>Width</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Enter the width in pixels</Description>
      </NumberField>
      <NumberField
        isDisabled
        defaultValue={0.5}
        formatOptions={{style: "percent"}}
        maxValue={1}
        minValue={0}
        name="percentage"
        step={0.1}
      >
        <Label>Percentage</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Value must be between 0 and 100</Description>
      </NumberField>
    </div>
  );
}

```

### Full Width

```tsx
import {Label, NumberField} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-4">
      <NumberField fullWidth defaultValue={1024} minValue={0} name="width">
        <Label>Width</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input />
          <NumberField.IncrementButton />
        </NumberField.Group>
      </NumberField>
    </div>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, NumberField automatically applies on-surface styling.

```tsx
import {Description, Label, NumberField, Surface} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="flex w-full max-w-[280px] flex-col gap-4 rounded-3xl p-6">
      <NumberField defaultValue={1024} minValue={0} name="width">
        <Label>Width</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-full" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Enter the width in pixels</Description>
      </NumberField>
      <NumberField
        defaultValue={0.5}
        formatOptions={{style: "percent"}}
        maxValue={1}
        minValue={0}
        name="percentage"
        step={0.1}
      >
        <Label>Percentage</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-full" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        <Description>Value must be between 0 and 100</Description>
      </NumberField>
    </Surface>
  );
}

```

### Form Example

Complete form integration with validation and submission handling.

```tsx
"use client";

import {Button, Description, FieldError, Form, Label, NumberField, Spinner} from "@heroui/react";
import React from "react";

export function FormExample() {
  const [value, setValue] = React.useState<number | undefined>(undefined);
  const [isSubmitting, setIsSubmitting] = React.useState(false);
  const STOCK_AVAILABLE = 3;
  const isOutOfStock = value !== undefined && value > STOCK_AVAILABLE;

const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();

if (value === undefined || value === null || value < 1 || value > STOCK_AVAILABLE) {
      return;
    }

setIsSubmitting(true);

// Simulate API call
    setTimeout(() => {
      console.log("Order submitted:", {quantity: value});
      setValue(undefined);
      setIsSubmitting(false);
    }, 1500);
  };

return (
    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
      <NumberField
        isRequired
        isInvalid={isOutOfStock}
        maxValue={5}
        minValue={1}
        name="quantity"
        value={value}
        onChange={setValue}
      >
        <Label>Order quantity</Label>
        <NumberField.Group>
          <NumberField.DecrementButton />
          <NumberField.Input className="w-[120px]" />
          <NumberField.IncrementButton />
        </NumberField.Group>
        {isOutOfStock ? (
          <FieldError>Only {STOCK_AVAILABLE} items left in stock</FieldError>
        ) : (
          <Description>Only {STOCK_AVAILABLE} items available</Description>
        )}
      </NumberField>
      <Button
        className="w-full"
        isDisabled={value === undefined || value < 1 || value > STOCK_AVAILABLE}
        isPending={isSubmitting}
        type="submit"
        variant="primary"
      >
        {isSubmitting ? (
          <>
            <Spinner color="current" size="sm" />
            Processing...
          </>
        ) : (
          "Place Order"
        )}
      </Button>
    </Form>
  );
}

```

## Related Components

* **Label**: Accessible label for form controls
* **Description**: Helper text for form fields
* **FieldError**: Inline validation messages for form fields

## Styling

### Passing Tailwind CSS classes

```tsx
import {NumberField, Label} from '@heroui/react';

function CustomNumberField() {
  return (
    <NumberField className="gap-2">
      <Label className="text-sm font-semibold">Quantity</Label>
      <NumberField.Group className="rounded-xl border-2">
        <NumberField.DecrementButton className="bg-gray-100" />
        <NumberField.Input className="text-center font-bold" />
        <NumberField.IncrementButton className="bg-gray-100" />
      </NumberField.Group>
    </NumberField>
  );
}

```

### Customizing the component classes

NumberField uses CSS classes that can be customized. Override the component classes to match your design system.

```css
@layer components {
  .number-field {
    @apply flex flex-col gap-1;
  }

/* When invalid, the description is hidden automatically */
  .number-field[data-invalid="true"] [data-slot="description"],
  .number-field[aria-invalid="true"] [data-slot="description"] {
    @apply hidden;
  }

.number-field__group {
    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border;
  }

.number-field__input {
    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 tabular-nums;
  }

.number-field__increment-button,
  .number-field__decrement-button {
    @apply flex h-full w-10 items-center justify-center rounded-none bg-transparent;
  }
}

```

### CSS Classes

* `.number-field` – Root container with minimal styling (`flex flex-col gap-1`)
* `.number-field__group` – Container for input and buttons with border and background styling
* `.number-field__input` – The numeric input field
* `.number-field__increment-button` – Button to increment the value
* `.number-field__decrement-button` – Button to decrement the value
* `.number-field__group--on-surface` – Applied when used inside a Surface component

### Interactive States

NumberField automatically manages these data attributes based on its state:

* **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
* **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
* **Focus Within**: `[data-focus-within="true"]` - Applied when the input or buttons are focused
* **Focus Visible**: `[data-focus-visible="true"]` - Applied when focus is visible (keyboard navigation)
* **Hovered**: `[data-hovered="true"]` - Applied when hovering over buttons

Additional attributes are available through render props (see NumberFieldRenderProps below).

## API Reference

### NumberField Props

NumberField inherits all props from React Aria's [NumberField](https://react-spectrum.adobe.com/react-aria/NumberField.html) component.

#### Base Props

| Prop          | Type                                                                             | Default | Description                                                            |
| ------------- | -------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------- |
| `children`    | `React.ReactNode \| (values: NumberFieldRenderProps) => React.ReactNode`         | -       | Child components (Label, Group, Input, etc.) or render function.       |
| `className`   | `string \| (values: NumberFieldRenderProps) => string`                           | -       | CSS classes for styling, supports render props.                        |
| `style`       | `React.CSSProperties \| (values: NumberFieldRenderProps) => React.CSSProperties` | -       | Inline styles, supports render props.                                  |
| `fullWidth`   | `boolean`                                                                        | `false` | Whether the number field should take full width of its container       |
| `id`          | `string`                                                                         | -       | The element's unique identifier.                                       |
| `isOnSurface` | `boolean`                                                                        | -       | Whether the field is on a surface (auto-detected when inside Surface). |

#### Value Props

| Prop           | Type                                   | Default | Description                            |
| -------------- | -------------------------------------- | ------- | -------------------------------------- |
| `value`        | `number`                               | -       | Current value (controlled).            |
| `defaultValue` | `number`                               | -       | Default value (uncontrolled).          |
| `onChange`     | `(value: number \| undefined) => void` | -       | Handler called when the value changes. |

#### Formatting Props

| Prop            | Type                       | Default | Description                                                        |
| --------------- | -------------------------- | ------- | ------------------------------------------------------------------ |
| `formatOptions` | `Intl.NumberFormatOptions` | -       | Options for formatting numbers (currency, percent, decimal, unit). |
| `locale`        | `string`                   | -       | Locale for number formatting.                                      |

#### Validation Props

| Prop                 | Type                                                              | Default    | Description                                                    |
| -------------------- | ----------------------------------------------------------------- | ---------- | -------------------------------------------------------------- |
| `isRequired`         | `boolean`                                                         | `false`    | Whether user input is required before form submission.         |
| `isInvalid`          | `boolean`                                                         | -          | Whether the value is invalid.                                  |
| `validate`           | `(value: number) => ValidationError \| true \| null \| undefined` | -          | Custom validation function.                                    |
| `validationBehavior` | `'native' \| 'aria'`                                              | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
| `validationErrors`   | `string[]`                                                        | -          | Server-side validation errors.                                 |

#### Range Props

| Prop       | Type     | Default | Description                                    |
| ---------- | -------- | ------- | ---------------------------------------------- |
| `minValue` | `number` | -       | Minimum allowed value.                         |
| `maxValue` | `number` | -       | Maximum allowed value.                         |
| `step`     | `number` | `1`     | Step value for increment/decrement operations. |

#### State Props

#### Form Props

| Prop        | Type      | Default | Description                                          |
| ----------- | --------- | ------- | ---------------------------------------------------- |
| `name`      | `string`  | -       | Name of the input element, for HTML form submission. |
| `autoFocus` | `boolean` | -       | Whether the element should receive focus on render.  |

#### Accessibility Props

### Composition Components

NumberField works with these separate components that should be imported and used directly:

* **NumberField.Group** - Container for input and buttons
* **NumberField.Input** - The numeric input field
* **NumberField.IncrementButton** - Button to increment the value
* **NumberField.DecrementButton** - Button to decrement the value
* **Label** - Field label component from `@heroui/react`
* **Description** - Helper text component from `@heroui/react`
* **FieldError** - Validation error message from `@heroui/react`

Each of these components has its own props API. Use them directly within NumberField for composition:

```tsx
<NumberField isRequired isInvalid={hasError} minValue={0} maxValue={100}>
  <Label>Quantity</Label>
  <NumberField.Group>
    <NumberField.DecrementButton />
    <NumberField.Input />
    <NumberField.IncrementButton />
  </NumberField.Group>
  <Description>Enter a value between 0 and 100</Description>
  <FieldError>Value must be between 0 and 100</FieldError>
</NumberField>

```

#### NumberField.Group Props

NumberField.Group inherits props from React Aria's [Group](https://react-spectrum.adobe.com/react-aria/Group.html) component.

| Prop        | Type                                                               | Default | Description                                           |
| ----------- | ------------------------------------------------------------------ | ------- | ----------------------------------------------------- |
| `children`  | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | -       | Child components (Input, Buttons) or render function. |
| `className` | `string \| (values: GroupRenderProps) => string`                   | -       | CSS classes for styling.                              |

#### NumberField.Input Props

NumberField.Input inherits props from React Aria's [Input](https://react-spectrum.adobe.com/react-aria/Input.html) component.

| Prop          | Type      | Default | Description                                                            |
| ------------- | --------- | ------- | ---------------------------------------------------------------------- |
| `className`   | `string`  | -       | CSS classes for styling.                                               |
| `isOnSurface` | `boolean` | -       | Whether the input is on a surface (auto-detected when inside Surface). |

#### NumberField.IncrementButton Props

NumberField.IncrementButton inherits props from React Aria's [Button](https://react-spectrum.adobe.com/react-aria/Button.html) component.

| Prop        | Type              | Default        | Description                                            |
| ----------- | ----------------- | -------------- | ------------------------------------------------------ |
| `children`  | `React.ReactNode` | `<IconPlus />` | Icon or content for the button. Defaults to plus icon. |
| `className` | `string`          | -              | CSS classes for styling.                               |
| `slot`      | `"increment"`     | `"increment"`  | Must be set to "increment" (automatically set).        |

#### NumberField.DecrementButton Props

NumberField.DecrementButton inherits props from React Aria's [Button](https://react-spectrum.adobe.com/react-aria/Button.html) component.

| Prop        | Type              | Default         | Description                                             |
| ----------- | ----------------- | --------------- | ------------------------------------------------------- |
| `children`  | `React.ReactNode` | `<IconMinus />` | Icon or content for the button. Defaults to minus icon. |
| `className` | `string`          | -               | CSS classes for styling.                                |
| `slot`      | `"decrement"`     | `"decrement"`   | Must be set to "decrement" (automatically set).         |

### NumberFieldRenderProps

When using render props with `className`, `style`, or `children`, these values are available:

| Prop             | Type                  | Description                                                                |
| ---------------- | --------------------- | -------------------------------------------------------------------------- |
| `isDisabled`     | `boolean`             | Whether the field is disabled.                                             |
| `isInvalid`      | `boolean`             | Whether the field is currently invalid.                                    |
| `isReadOnly`     | `boolean`             | Whether the field is read-only.                                            |
| `isRequired`     | `boolean`             | Whether the field is required.                                             |
| `isFocused`      | `boolean`             | Whether the field is currently focused (DEPRECATED - use `isFocusWithin`). |
| `isFocusWithin`  | `boolean`             | Whether any child element is focused.                                      |
| `isFocusVisible` | `boolean`             | Whether focus is visible (keyboard navigation).                            |
| `value`          | `number \| undefined` | Current value.                                                             |
| `minValue`       | `number \| undefined` | Minimum allowed value.                                                     |
| `maxValue`       | `number \| undefined` | Maximum allowed value.                                                     |
| `step`           | `number`              | Step value for increment/decrement.                                        |

</page>

<page url="/docs/react/components/radio-group">
# RadioGroup

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/radio-group
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/radio-group.mdx
> Radio group for selecting a single option from a list

## Import

```tsx
import { RadioGroup, Radio } from '@heroui/react';

```

### Usage

```tsx
import {Description, Label, Radio, RadioGroup} from "@heroui/react";

```

### Anatomy

Import the RadioGroup component and access all parts using dot notation.

```tsx
import {RadioGroup, Radio, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <RadioGroup>
    <Label />
    <Description />
    <Radio value="option1">
      <Radio.Control>
        <Radio.Indicator>
          <span>✓</span> {/* Custom indicator (optional) */}
        </Radio.Indicator>
      </Radio.Control>
      <Radio.Content>
        <Label />
        <Description />
      </Radio.Content>
    </Radio>
    <FieldError />
  </RadioGroup>
)

```

### Custom Indicator

```tsx
"use client";

import {Description, Label, Radio, RadioGroup} from "@heroui/react";

export function CustomIndicator() {
  return (
    <RadioGroup defaultValue="premium" name="plan-custom-indicator">
      <Label>Plan selection</Label>
      <Description>Choose the plan that suits you best</Description>
      <Radio value="basic">
        <Radio.Control>
          <Radio.Indicator>
            {({isSelected}) =>
              isSelected ? <span className="text-xs leading-none text-background">✓</span> : null
            }
          </Radio.Indicator>
        </Radio.Control>
        <Radio.Content>
          <Label>Basic Plan</Label>
          <Description>Includes 100 messages per month</Description>
        </Radio.Content>
      </Radio>
      <Radio value="premium">
        <Radio.Control>
          <Radio.Indicator>
            {({isSelected}) =>
              isSelected ? <span className="text-xs leading-none text-background">✓</span> : null
            }
          </Radio.Indicator>
        </Radio.Control>
        <Radio.Content>
          <Label>Premium Plan</Label>
          <Description>Includes 200 messages per month</Description>
        </Radio.Content>
      </Radio>
      <Radio value="business">
        <Radio.Control>
          <Radio.Indicator>
            {({isSelected}) =>
              isSelected ? <span className="text-xs leading-none text-background">✓</span> : null
            }
          </Radio.Indicator>
        </Radio.Control>
        <Radio.Content>
          <Label>Business Plan</Label>
          <Description>Unlimited messages</Description>
        </Radio.Content>
      </Radio>
    </RadioGroup>
  );
}

```

### Horizontal Orientation

```tsx
import {Description, Label, Radio, RadioGroup} from "@heroui/react";

export function Horizontal() {
  return (
    <div className="flex flex-col gap-4">
      <Label>Subscription plan</Label>
      <RadioGroup defaultValue="pro" name="plan-orientation" orientation="horizontal">
        <Radio value="starter">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Starter</Label>
            <Description>For side projects</Description>
          </Radio.Content>
        </Radio>
        <Radio value="pro">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Pro</Label>
            <Description>Advanced reporting</Description>
          </Radio.Content>
        </Radio>
        <Radio value="teams">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Teams</Label>
            <Description>Up to 10 teammates</Description>
          </Radio.Content>
        </Radio>
      </RadioGroup>
    </div>
  );
}

```

### Controlled

```tsx
"use client";

import {Description, Label, Radio, RadioGroup} from "@heroui/react";
import React from "react";

export function Controlled() {
  const [value, setValue] = React.useState("pro");

return (
    <div className="flex flex-col gap-4">
      <RadioGroup name="plan-controlled" value={value} onChange={setValue}>
        <Label>Subscription plan</Label>
        <Radio value="starter">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Starter</Label>
            <Description>For side projects and small teams</Description>
          </Radio.Content>
        </Radio>
        <Radio value="pro">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Pro</Label>
            <Description>Advanced reporting and analytics</Description>
          </Radio.Content>
        </Radio>
        <Radio value="teams">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Teams</Label>
            <Description>Share access with up to 10 teammates</Description>
          </Radio.Content>
        </Radio>
      </RadioGroup>
      <p className="text-sm text-muted">
        Selected plan: <span className="font-medium">{value}</span>
      </p>
    </div>
  );
}

```

### Uncontrolled

Combine `defaultValue` with `onChange` when you only need to react to updates.

```tsx
"use client";

import {Description, Label, Radio, RadioGroup} from "@heroui/react";
import React from "react";

export function Uncontrolled() {
  const [selection, setSelection] = React.useState("pro");

return (
    <div className="flex flex-col gap-4">
      <RadioGroup
        defaultValue="pro"
        name="plan-uncontrolled"
        onChange={(nextValue) => setSelection(nextValue)}
      >
        <Label>Subscription plan</Label>
        <Radio value="starter">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Starter</Label>
            <Description>For side projects and small teams</Description>
          </Radio.Content>
        </Radio>
        <Radio value="pro">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Pro</Label>
            <Description>Advanced reporting and analytics</Description>
          </Radio.Content>
        </Radio>
        <Radio value="teams">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Teams</Label>
            <Description>Share access with up to 10 teammates</Description>
          </Radio.Content>
        </Radio>
      </RadioGroup>
      <p className="text-sm text-muted">
        Last chosen plan: <span className="font-medium">{selection}</span>
      </p>
    </div>
  );
}

```

### Validation

```tsx
"use client";

import {Button, Description, FieldError, Form, Label, Radio, RadioGroup} from "@heroui/react";
import React from "react";

export function Validation() {
  const [message, setMessage] = React.useState<string | null>(null);

return (
    <Form
      className="flex flex-col gap-4"
      onSubmit={(e) => {
        e.preventDefault();

const formData = new FormData(e.currentTarget);
        const value = formData.get("plan-validation");

setMessage(`Your chosen plan is: ${value}`);
      }}
    >
      <RadioGroup isRequired name="plan-validation">
        <Label>Subscription plan</Label>
        <Radio value="starter">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Starter</Label>
            <Description>For side projects and small teams</Description>
          </Radio.Content>
        </Radio>
        <Radio value="pro">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Pro</Label>
            <Description>Advanced reporting and analytics</Description>
          </Radio.Content>
        </Radio>
        <Radio value="teams">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Teams</Label>
            <Description>Share access with up to 10 teammates</Description>
          </Radio.Content>
        </Radio>
        <FieldError>Choose a subscription before continuing.</FieldError>
      </RadioGroup>
      <Button className="mt-2 w-fit" type="submit">
        Submit
      </Button>
      {!!message && <p className="text-sm text-muted">{message}</p>}
    </Form>
  );
}

```

### Disabled

```tsx
import {Description, Label, Radio, RadioGroup} from "@heroui/react";

export function Disabled() {
  return (
    <RadioGroup isDisabled defaultValue="pro" name="plan-disabled">
      <Label>Subscription plan</Label>
      <Description>Plan changes are temporarily paused while we roll out updates.</Description>
      <Radio value="starter">
        <Radio.Control>
          <Radio.Indicator />
        </Radio.Control>
        <Radio.Content>
          <Label>Starter</Label>
          <Description>For side projects and small teams</Description>
        </Radio.Content>
      </Radio>
      <Radio value="pro">
        <Radio.Control>
          <Radio.Indicator />
        </Radio.Control>
        <Radio.Content>
          <Label>Pro</Label>
          <Description>Advanced reporting and analytics</Description>
        </Radio.Content>
      </Radio>
      <Radio value="teams">
        <Radio.Control>
          <Radio.Indicator />
        </Radio.Control>
        <Radio.Content>
          <Label>Teams</Label>
          <Description>Share access with up to 10 teammates</Description>
        </Radio.Content>
      </Radio>
    </RadioGroup>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, RadioGroup automatically applies on-surface styling.

```tsx
import {Description, Label, Radio, RadioGroup, Surface} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="w-full rounded-3xl p-6">
      <RadioGroup defaultValue="premium" name="plan">
        <Label>Plan selection</Label>
        <Description>Choose the plan that suits you best</Description>
        <Radio value="basic">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Basic Plan</Label>
            <Description>Includes 100 messages per month</Description>
          </Radio.Content>
        </Radio>
        <Radio value="premium">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Premium Plan</Label>
            <Description>Includes 200 messages per month</Description>
          </Radio.Content>
        </Radio>
        <Radio value="business">
          <Radio.Control>
            <Radio.Indicator />
          </Radio.Control>
          <Radio.Content>
            <Label>Business Plan</Label>
            <Description>Unlimited messages</Description>
          </Radio.Content>
        </Radio>
      </RadioGroup>
    </Surface>
  );
}

```

### Delivery & Payment

## Related Components

* **Fieldset**: Group related form controls with legends
* **Surface**: Base container surface
* **Description**: Helper text for form fields

## Styling

### Passing Tailwind CSS classes

```tsx
import { RadioGroup, Radio } from '@heroui/react';

export default () => (
  <RadioGroup defaultValue="premium" name="plan">
    <Radio
      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-blue-300 data-[selected=true]:border-blue-500 data-[selected=true]:bg-blue-500/10"
      value="basic"
    >
      <Radio.Indicator className="border-border border-2 group-hover:border-blue-400 group-data-[selected=true]:border-blue-500 group-data-[selected=true]:bg-blue-500" />
      Basic Plan
    </Radio>
    <Radio
      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-purple-300 data-[selected=true]:border-purple-500 data-[selected=true]:bg-purple-500/10"
      value="premium"
    >
      <Radio.Indicator className="border-border border-2 group-hover:border-purple-400 group-data-[selected=true]:border-purple-500 group-data-[selected=true]:bg-purple-500" />
      Premium Plan
    </Radio>
    <Radio
      className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-emerald-300 data-[selected=true]:border-emerald-500 data-[selected=true]:bg-emerald-500/10"
      value="business"
    >
      <Radio.Indicator className="border-border border-2 group-hover:border-emerald-400 group-data-[selected=true]:border-emerald-500 group-data-[selected=true]:bg-emerald-500" />
      Business Plan
    </Radio>
  </RadioGroup>
);

```

### Customizing the component classes

To customize the RadioGroup component classes, you can use the `@layer components` directive.
<br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes).

```css
@layer components {
  .radio-group {
    @apply gap-2;
  }

.radio {
    @apply gap-4 rounded-lg border border-border p-3 hover:bg-surface-hovered;
  }

.radio__control {
    @apply border-2 border-primary;
  }

.radio__indicator {
    @apply bg-primary;
  }

.radio__content {
    @apply gap-1;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The RadioGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/radio-group.css)):

#### Base Classes

* `.radio-group` - Base radio group container
* `.radio` - Individual radio item
* `.radio__control` - Radio control (circular button)
* `.radio__indicator` - Radio indicator (inner dot)
* `.radio__content` - Radio content wrapper

#### Modifier Classes

* `.radio--disabled` - Disabled radio state

### Interactive States

The radio supports both CSS pseudo-classes and data attributes for flexibility:

* **Selected**: `[aria-checked="true"]` or `[data-selected="true"]` (indicator appears)
* **Hover**: `:hover` or `[data-hovered="true"]` (border color changes)
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring)
* **Pressed**: `:active` or `[data-pressed="true"]` (scale transform)
* **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events)
* **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` (error border color)

## API Reference

### RadioGroup Props

| Prop           | Type                                                                    | Default      | Description                                                         |
| -------------- | ----------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------- |
| `value`        | `string`                                                                | -            | The current value (controlled)                                      |
| `defaultValue` | `string`                                                                | -            | The default value (uncontrolled)                                    |
| `onChange`     | `(value: string) => void`                                               | -            | Handler called when the value changes                               |
| `isDisabled`   | `boolean`                                                               | `false`      | Whether the radio group is disabled                                 |
| `isRequired`   | `boolean`                                                               | `false`      | Whether the radio group is required                                 |
| `isReadOnly`   | `boolean`                                                               | `false`      | Whether the radio group is read only                                |
| `isInvalid`    | `boolean`                                                               | `false`      | Whether the radio group is in an invalid state                      |
| `isOnSurface`  | `boolean`                                                               | `false`      | Whether the radio group is displayed on a surface (affects styling) |
| `name`         | `string`                                                                | -            | The name of the radio group, used when submitting an HTML form      |
| `orientation`  | `'horizontal' \| 'vertical'`                                            | `'vertical'` | The orientation of the radio group                                  |
| `children`     | `React.ReactNode \| (values: RadioGroupRenderProps) => React.ReactNode` | -            | Radio group content or render prop                                  |

### Radio Props

| Prop         | Type                                                               | Default | Description                                                     |
| ------------ | ------------------------------------------------------------------ | ------- | --------------------------------------------------------------- |
| `value`      | `string`                                                           | -       | The value of the radio button                                   |
| `isDisabled` | `boolean`                                                          | `false` | Whether the radio button is disabled                            |
| `name`       | `string`                                                           | -       | The name of the radio button, used when submitting an HTML form |
| `children`   | `React.ReactNode \| (values: RadioRenderProps) => React.ReactNode` | -       | Radio content or render prop                                    |

### Radio.Control Props

Extends `React.HTMLAttributes<HTMLSpanElement>`.

| Prop       | Type              | Default | Description                                                                  |
| ---------- | ----------------- | ------- | ---------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | -       | The content to render inside the control wrapper (typically Radio.Indicator) |

### Radio.Indicator Props

Extends `React.HTMLAttributes<HTMLSpanElement>`.

| Prop       | Type                                                               | Default | Description                                                            |
| ---------- | ------------------------------------------------------------------ | ------- | ---------------------------------------------------------------------- |
| `children` | `React.ReactNode \| (values: RadioRenderProps) => React.ReactNode` | -       | Optional content or render prop that receives the current radio state. |

### Radio.Content Props

Extends `React.HTMLAttributes<HTMLDivElement>`.

| Prop       | Type              | Default | Description                                                                        |
| ---------- | ----------------- | ------- | ---------------------------------------------------------------------------------- |
| `children` | `React.ReactNode` | -       | The content to render inside the content wrapper (typically Label and Description) |

### RadioRenderProps

When using the render prop pattern, these values are provided:

| Prop             | Type      | Description                              |
| ---------------- | --------- | ---------------------------------------- |
| `isSelected`     | `boolean` | Whether the radio is currently selected  |
| `isHovered`      | `boolean` | Whether the radio is hovered             |
| `isPressed`      | `boolean` | Whether the radio is currently pressed   |
| `isFocused`      | `boolean` | Whether the radio is focused             |
| `isFocusVisible` | `boolean` | Whether the radio is keyboard focused    |
| `isDisabled`     | `boolean` | Whether the radio is disabled            |
| `isReadOnly`     | `boolean` | Whether the radio is read only           |
| `isInvalid`      | `boolean` | Whether the radio is in an invalid state |

</page>

<page url="/docs/react/components/search-field">
# SearchField

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/search-field
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/search-field.mdx
> Search input field with clear button and search icon

## Import

```tsx
import { SearchField } from '@heroui/react';

```

### Usage

```tsx
import {Label, SearchField} from "@heroui/react";

```

### Anatomy

```tsx
import {SearchField, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <SearchField>
    <Label />
    <SearchField.Group>
      <SearchField.SearchIcon />
      <SearchField.Input />
      <SearchField.ClearButton />
    </SearchField.Group>
    <Description />
    <FieldError />
  </SearchField>
)

```

> **SearchField** allows users to enter and clear a search query. It includes a search icon and an optional clear button for easy reset.

### With Description

```tsx
import {Description, Label, SearchField} from "@heroui/react";

export function WithDescription() {
  return (
    <div className="flex flex-col gap-4">
      <SearchField name="search">
        <Label>Search products</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-[280px]" placeholder="Search products..." />
          <SearchField.ClearButton />
        </SearchField.Group>
        <Description>Enter keywords to search for products</Description>
      </SearchField>
      <SearchField name="search-users">
        <Label>Search users</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-[280px]" placeholder="Search users..." />
          <SearchField.ClearButton />
        </SearchField.Group>
        <Description>Search by name, email, or username</Description>
      </SearchField>
    </div>
  );
}

```

### Required Field

```tsx
import {Description, Label, SearchField} from "@heroui/react";

export function Required() {
  return (
    <div className="flex flex-col gap-4">
      <SearchField isRequired name="search">
        <Label>Search</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-[280px]" placeholder="Search..." />
          <SearchField.ClearButton />
        </SearchField.Group>
      </SearchField>
      <SearchField isRequired name="search-query">
        <Label>Search query</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-[280px]" placeholder="Enter search query..." />
          <SearchField.ClearButton />
        </SearchField.Group>
        <Description>Minimum 3 characters required</Description>
      </SearchField>
    </div>
  );
}

```

### Validation

Use `isInvalid` together with `FieldError` to surface validation messages.

```tsx
import {FieldError, Label, SearchField} from "@heroui/react";

export function Validation() {
  return (
    <div className="flex flex-col gap-4">
      <SearchField isInvalid isRequired name="search" value="ab">
        <Label>Search</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-[280px]" placeholder="Search..." />
          <SearchField.ClearButton />
        </SearchField.Group>
        <FieldError>Search query must be at least 3 characters</FieldError>
      </SearchField>
      <SearchField isInvalid name="search-invalid">
        <Label>Search</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-[280px]" placeholder="Search..." value="invalid@query" />
          <SearchField.ClearButton />
        </SearchField.Group>
        <FieldError>Invalid characters in search query</FieldError>
      </SearchField>
    </div>
  );
}

```

### Disabled State

```tsx
import {Description, Label, SearchField} from "@heroui/react";

export function Disabled() {
  return (
    <div className="flex flex-col gap-4">
      <SearchField isDisabled name="search" value="Disabled search">
        <Label>Search</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-[280px]" placeholder="Search..." />
          <SearchField.ClearButton />
        </SearchField.Group>
        <Description>This search field is disabled</Description>
      </SearchField>
      <SearchField isDisabled name="search-empty">
        <Label>Search</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-[280px]" placeholder="Search..." />
          <SearchField.ClearButton />
        </SearchField.Group>
        <Description>This search field is disabled</Description>
      </SearchField>
    </div>
  );
}

```

### Controlled

Control the value to synchronize with other components or perform custom formatting.

```tsx
"use client";

import {Button, Description, Label, SearchField} from "@heroui/react";
import React from "react";

export function Controlled() {
  const [value, setValue] = React.useState("");

return (
    <div className="flex flex-col gap-4">
      <SearchField name="search" value={value} onChange={setValue}>
        <Label>Search</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-[280px]" placeholder="Search..." />
          <SearchField.ClearButton />
        </SearchField.Group>
        <Description>Current value: {value || "(empty)"}</Description>
      </SearchField>
      <div className="flex gap-2">
        <Button variant="tertiary" onPress={() => setValue("")}>
          Clear
        </Button>
        <Button variant="tertiary" onPress={() => setValue("example query")}>
          Set example
        </Button>
      </div>
    </div>
  );
}

```

### With Validation

Implement custom validation logic with controlled values.

```tsx
"use client";

import {Description, FieldError, Label, SearchField} from "@heroui/react";
import React from "react";

export function WithValidation() {
  const [value, setValue] = React.useState("");
  const isInvalid = value.length > 0 && value.length < 3;

return (
    <div className="flex flex-col gap-4">
      <SearchField isRequired isInvalid={isInvalid} name="search" value={value} onChange={setValue}>
        <Label>Search</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-[280px]" placeholder="Search..." />
          <SearchField.ClearButton />
        </SearchField.Group>
        {isInvalid ? (
          <FieldError>Search query must be at least 3 characters</FieldError>
        ) : (
          <Description>Enter at least 3 characters to search</Description>
        )}
      </SearchField>
    </div>
  );
}

```

### Custom Icons

Customize the search icon and clear button icons.

```tsx
import {Description, Label, SearchField} from "@heroui/react";

export function CustomIcons() {
  return (
    <div className="flex flex-col gap-4">
      <SearchField name="search-custom">
        <Label>Search (Custom Icons)</Label>
        <SearchField.Group>
          <SearchField.SearchIcon>
            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
              <path
                clipRule="evenodd"
                d="M12.5 4c0 .174-.071.513-.885.888S9.538 5.5 8 5.5s-2.799-.237-3.615-.612C3.57 4.513 3.5 4.174 3.5 4s.071-.513.885-.888S6.462 2.5 8 2.5s2.799.237 3.615.612c.814.375.885.714.885.888m-1.448 2.66C10.158 6.888 9.115 7 8 7s-2.158-.113-3.052-.34l1.98 2.905c.21.308.322.672.322 1.044v3.37q.088.02.25.021c.422 0 .749-.14.95-.316c.185-.162.3-.38.3-.684v-2.39c0-.373.112-.737.322-1.045zM8 1c3.314 0 6 1 6 3a3.24 3.24 0 0 1-.563 1.826l-3.125 4.584a.35.35 0 0 0-.062.2V13c0 1.5-1.25 2.5-2.75 2.5s-1.75-1-1.75-1v-3.89a.35.35 0 0 0-.061-.2L2.563 5.826A3.24 3.24 0 0 1 2 4c0-2 2.686-3 6-3m-.88 12.936q-.015-.008-.013-.01z"
                fill="currentColor"
                fillRule="evenodd"
              />
            </svg>
          </SearchField.SearchIcon>
          <SearchField.Input className="w-[280px]" placeholder="Search..." />
          <SearchField.ClearButton>
            <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg">
              <path
                clipRule="evenodd"
                d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14M6.53 5.47a.75.75 0 0 0-1.06 1.06L6.94 8L5.47 9.47a.75.75 0 1 0 1.06 1.06L8 9.06l1.47 1.47a.75.75 0 1 0 1.06-1.06L9.06 8l1.47-1.47a.75.75 0 1 0-1.06-1.06L8 6.94z"
                fill="currentColor"
                fillRule="evenodd"
              />
            </svg>
          </SearchField.ClearButton>
        </SearchField.Group>
        <Description>Custom icon children</Description>
      </SearchField>
    </div>
  );
}

```

### Full Width

```tsx
import {Label, SearchField} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-4">
      <SearchField fullWidth name="search">
        <Label>Search</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input placeholder="Search..." />
          <SearchField.ClearButton />
        </SearchField.Group>
      </SearchField>
    </div>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, SearchField automatically applies on-surface styling.

```tsx
import {Description, Label, SearchField, Surface} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6">
      <SearchField name="search">
        <Label>Search</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-full" placeholder="Search..." />
          <SearchField.ClearButton />
        </SearchField.Group>
        <Description>Enter keywords to search</Description>
      </SearchField>
      <SearchField name="search-2">
        <Label>Advanced search</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-full" placeholder="Advanced search..." />
          <SearchField.ClearButton />
        </SearchField.Group>
        <Description>Use filters to refine your search</Description>
      </SearchField>
    </Surface>
  );
}

```

### Form Example

Complete form integration with validation and submission handling.

```tsx
"use client";

import {Button, Description, FieldError, Form, Label, SearchField, Spinner} from "@heroui/react";
import React from "react";

export function FormExample() {
  const [value, setValue] = React.useState("");
  const [isSubmitting, setIsSubmitting] = React.useState(false);
  const MIN_LENGTH = 3;
  const isInvalid = value.length > 0 && value.length < MIN_LENGTH;

const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();

if (value.length < MIN_LENGTH) {
      return;
    }

setIsSubmitting(true);

// Simulate API call
    setTimeout(() => {
      console.log("Search submitted:", {query: value});
      setValue("");
      setIsSubmitting(false);
    }, 1500);
  };

return (
    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
      <SearchField isRequired isInvalid={isInvalid} name="search" value={value} onChange={setValue}>
        <Label>Search products</Label>
        <SearchField.Group>
          <SearchField.SearchIcon />
          <SearchField.Input className="w-full" placeholder="Search products..." />
          <SearchField.ClearButton />
        </SearchField.Group>
        {isInvalid ? (
          <FieldError>Search query must be at least {MIN_LENGTH} characters</FieldError>
        ) : (
          <Description>Enter at least {MIN_LENGTH} characters to search</Description>
        )}
      </SearchField>
      <Button
        className="w-full"
        isDisabled={value.length < MIN_LENGTH}
        isPending={isSubmitting}
        type="submit"
        variant="primary"
      >
        {isSubmitting ? (
          <>
            <Spinner color="current" size="sm" />
            Searching...
          </>
        ) : (
          "Search"
        )}
      </Button>
    </Form>
  );
}

```

### With Keyboard Shortcut

Add keyboard shortcuts to quickly focus the search field.

```tsx
"use client";

import {Description, Kbd, Label, SearchField} from "@heroui/react";
import React from "react";

export function WithKeyboardShortcut() {
  const inputRef = React.useRef<HTMLInputElement>(null);
  const [value, setValue] = React.useState("");

React.useEffect(() => {
    const handleKeyDown = (e: KeyboardEvent) => {
      // Check for Shift+S
      if (e.shiftKey && e.key === "S" && !e.metaKey && !e.ctrlKey && !e.altKey) {
        e.preventDefault();
        inputRef.current?.focus();
      }
      // Check for ESC key to blur the input
      if (e.key === "Escape" && document.activeElement === inputRef.current) {
        inputRef.current?.blur();
      }
    };

// Add global event listener
    window.addEventListener("keydown", handleKeyDown);

// Cleanup on unmount
    return () => {
      window.removeEventListener("keydown", handleKeyDown);
    };
  }, []);

return (
    <div className="flex flex-col gap-4">
      <div>
        <SearchField name="search" value={value} onChange={setValue}>
          <Label>Search</Label>
          <SearchField.Group>
            <SearchField.SearchIcon />
            <SearchField.Input ref={inputRef} className="w-[280px]" placeholder="Search..." />
            <SearchField.ClearButton />
          </SearchField.Group>
          <Description>Use keyboard shortcut to quickly focus this field</Description>
        </SearchField>
      </div>
      <div className="text-default-500 flex items-center gap-2 text-sm">
        <span>Press</span>
        <Kbd>
          <Kbd.Abbr keyValue="shift" />
          <Kbd.Content>S</Kbd.Content>
        </Kbd>
        <span>to focus the search field</span>
      </div>
    </div>
  );
}

```

## Related Components

* **Label**: Accessible label for form controls
* **Description**: Helper text for form fields
* **FieldError**: Inline validation messages for form fields

## Styling

### Passing Tailwind CSS classes

```tsx
import {SearchField, Label} from '@heroui/react';

function CustomSearchField() {
  return (
    <SearchField className="gap-2">
      <Label className="text-sm font-semibold">Search</Label>
      <SearchField.Group className="rounded-xl border-2">
        <SearchField.SearchIcon className="text-blue-500" />
        <SearchField.Input className="text-center font-bold" />
        <SearchField.ClearButton className="text-red-500" />
      </SearchField.Group>
    </SearchField>
  );
}

```

### Customizing the component classes

SearchField uses CSS classes that can be customized. Override the component classes to match your design system.

```css
@layer components {
  .search-field {
    @apply flex flex-col gap-1;
  }

/* When invalid, the description is hidden automatically */
  .search-field[data-invalid],
  .search-field[aria-invalid] {
    [data-slot="description"] {
      @apply hidden;
    }
  }

.search-field__group {
    @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border;
  }

.search-field__input {
    @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
  }

.search-field__search-icon {
    @apply text-field-placeholder pointer-events-none shrink-0 ml-3 mr-0 size-4;
  }

.search-field__clear-button {
    @apply mr-1 shrink-0;
  }
}

```

### CSS Classes

* `.search-field` – Root container with minimal styling (`flex flex-col gap-1`)
* `.search-field__group` – Container for search icon, input, and clear button with border and background styling
* `.search-field__input` – The search input field
* `.search-field__search-icon` – The search icon displayed on the left
* `.search-field__clear-button` – Button to clear the search field
* `.search-field__group--on-surface` – Applied when used inside a Surface component

### Interactive States

SearchField automatically manages these data attributes based on its state:

* **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
* **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
* **Focus Within**: `[data-focus-within="true"]` - Applied when the input is focused
* **Focus Visible**: `[data-focus-visible="true"]` - Applied when focus is visible (keyboard navigation)
* **Hovered**: `[data-hovered="true"]` - Applied when hovering over the group
* **Empty**: `[data-empty="true"]` - Applied when the field is empty (hides clear button)

Additional attributes are available through render props (see SearchFieldRenderProps below).

## API Reference

### SearchField Props

SearchField inherits all props from React Aria's [SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html) component.

#### Base Props

| Prop          | Type                                                                             | Default | Description                                                            |
| ------------- | -------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------- |
| `children`    | `React.ReactNode \| (values: SearchFieldRenderProps) => React.ReactNode`         | -       | Child components (Label, Group, Input, etc.) or render function.       |
| `className`   | `string \| (values: SearchFieldRenderProps) => string`                           | -       | CSS classes for styling, supports render props.                        |
| `style`       | `React.CSSProperties \| (values: SearchFieldRenderProps) => React.CSSProperties` | -       | Inline styles, supports render props.                                  |
| `fullWidth`   | `boolean`                                                                        | `false` | Whether the search field should take full width of its container       |
| `id`          | `string`                                                                         | -       | The element's unique identifier.                                       |
| `isOnSurface` | `boolean`                                                                        | -       | Whether the field is on a surface (auto-detected when inside Surface). |

#### Value Props

| Prop           | Type                      | Default | Description                            |
| -------------- | ------------------------- | ------- | -------------------------------------- |
| `value`        | `string`                  | -       | Current value (controlled).            |
| `defaultValue` | `string`                  | -       | Default value (uncontrolled).          |
| `onChange`     | `(value: string) => void` | -       | Handler called when the value changes. |

#### Validation Props

| Prop                 | Type                                                              | Default    | Description                                                    |
| -------------------- | ----------------------------------------------------------------- | ---------- | -------------------------------------------------------------- |
| `isRequired`         | `boolean`                                                         | `false`    | Whether user input is required before form submission.         |
| `isInvalid`          | `boolean`                                                         | -          | Whether the value is invalid.                                  |
| `validate`           | `(value: string) => ValidationError \| true \| null \| undefined` | -          | Custom validation function.                                    |
| `validationBehavior` | `'native' \| 'aria'`                                              | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
| `validationErrors`   | `string[]`                                                        | -          | Server-side validation errors.                                 |

#### State Props

#### Form Props

#### Event Props

| Prop       | Type                      | Default | Description                                                  |
| ---------- | ------------------------- | ------- | ------------------------------------------------------------ |
| `onSubmit` | `(value: string) => void` | -       | Handler called when the user submits the search (Enter key). |
| `onClear`  | `() => void`              | -       | Handler called when the clear button is pressed.             |

#### Accessibility Props

### Composition Components

SearchField works with these separate components that should be imported and used directly:

* **SearchField.Group** - Container for search icon, input, and clear button
* **SearchField.Input** - The search input field
* **SearchField.SearchIcon** - The search icon displayed on the left
* **SearchField.ClearButton** - Button to clear the search field
* **Label** - Field label component from `@heroui/react`
* **Description** - Helper text component from `@heroui/react`
* **FieldError** - Validation error message from `@heroui/react`

Each of these components has its own props API. Use them directly within SearchField for composition:

```tsx
<SearchField isRequired isInvalid={hasError} value={value} onChange={setValue}>
  <Label>Search</Label>
  <SearchField.Group>
    <SearchField.SearchIcon />
    <SearchField.Input placeholder="Search..." />
    <SearchField.ClearButton />
  </SearchField.Group>
  <Description>Enter keywords to search</Description>
  <FieldError>Search query is required</FieldError>
</SearchField>

```

#### SearchField.Group Props

SearchField.Group inherits props from React Aria's [Group](https://react-spectrum.adobe.com/react-aria/Group.html) component.

| Prop        | Type                                                               | Default | Description                                                           |
| ----------- | ------------------------------------------------------------------ | ------- | --------------------------------------------------------------------- |
| `children`  | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | -       | Child components (SearchIcon, Input, ClearButton) or render function. |
| `className` | `string \| (values: GroupRenderProps) => string`                   | -       | CSS classes for styling.                                              |

#### SearchField.Input Props

SearchField.Input inherits props from React Aria's [Input](https://react-spectrum.adobe.com/react-aria/Input.html) component.

| Prop          | Type      | Default    | Description                                                            |
| ------------- | --------- | ---------- | ---------------------------------------------------------------------- |
| `className`   | `string`  | -          | CSS classes for styling.                                               |
| `isOnSurface` | `boolean` | -          | Whether the input is on a surface (auto-detected when inside Surface). |
| `placeholder` | `string`  | -          | Placeholder text displayed when the input is empty.                    |
| `type`        | `string`  | `"search"` | Input type (automatically set to "search").                            |

#### SearchField.SearchIcon Props

SearchField.SearchIcon is a custom component that renders the search icon.

| Prop        | Type              | Default          | Description                                   |
| ----------- | ----------------- | ---------------- | --------------------------------------------- |
| `children`  | `React.ReactNode` | `<IconSearch />` | Custom icon element. Defaults to search icon. |
| `className` | `string`          | -                | CSS classes for styling.                      |

#### SearchField.ClearButton Props

SearchField.ClearButton inherits props from React Aria's [Button](https://react-spectrum.adobe.com/react-aria/Button.html) component.

| Prop        | Type              | Default                | Description                                             |
| ----------- | ----------------- | ---------------------- | ------------------------------------------------------- |
| `children`  | `React.ReactNode` | `<CloseButton icon />` | Icon or content for the button. Defaults to close icon. |
| `className` | `string`          | -                      | CSS classes for styling.                                |
| `slot`      | `"clear"`         | `"clear"`              | Must be set to "clear" (automatically set).             |

### SearchFieldRenderProps

When using render props with `className`, `style`, or `children`, these values are available:

| Prop             | Type      | Description                                                                |
| ---------------- | --------- | -------------------------------------------------------------------------- |
| `isDisabled`     | `boolean` | Whether the field is disabled.                                             |
| `isInvalid`      | `boolean` | Whether the field is currently invalid.                                    |
| `isReadOnly`     | `boolean` | Whether the field is read-only.                                            |
| `isRequired`     | `boolean` | Whether the field is required.                                             |
| `isFocused`      | `boolean` | Whether the field is currently focused (DEPRECATED - use `isFocusWithin`). |
| `isFocusWithin`  | `boolean` | Whether any child element is focused.                                      |
| `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation).                            |
| `value`          | `string`  | Current value.                                                             |
| `isEmpty`        | `boolean` | Whether the field is empty.                                                |

</page>

<page url="/docs/react/components/text-field">
# TextField

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/text-field
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/text-field.mdx
> Composition-friendly text fields with labels, descriptions, and inline validation

## Import

```tsx
import { TextField } from '@heroui/react';

```

### Usage

```tsx
import {Input, Label, TextField} from "@heroui/react";

```

### Anatomy

```tsx
import {TextField, Label, Input, Description, FieldError} from '@heroui/react';

export default () => (
  <TextField>
    <Label />
    <Input />
    <Description />
    <FieldError />
  </TextField>
)

```

> **TextField** combines label, input, description, and error into a single accessible component.
> For standalone inputs, use **[Input](/docs/components/input)** or **[TextArea](/docs/components/textarea)**.

### With Description

```tsx
import {Description, Input, Label, TextField} from "@heroui/react";

export function WithDescription() {
  return (
    <TextField className="w-full max-w-64" name="username">
      <Label>Username</Label>
      <Input placeholder="Enter username" />
      <Description>Choose a unique username for your account</Description>
    </TextField>
  );
}

```

### Required Field

```tsx
import {Description, Input, Label, TextField} from "@heroui/react";

export function Required() {
  return (
    <TextField isRequired className="w-full max-w-64" name="fullName">
      <Label>Full Name</Label>
      <Input placeholder="John Doe" />
      <Description>This field is required</Description>
    </TextField>
  );
}

```

### Validation

Use `isInvalid` together with `FieldError` to surface validation messages.

```tsx
"use client";

import {Description, FieldError, Input, Label, TextArea, TextField} from "@heroui/react";
import React from "react";

export function Validation() {
  const [username, setUsername] = React.useState("");
  const [bio, setBio] = React.useState("");

const isUsernameInvalid = username.length > 0 && username.length < 3;
  const isBioInvalid = bio.length > 0 && bio.length < 20;

return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <TextField isRequired isInvalid={isUsernameInvalid} name="username" onChange={setUsername}>
        <Label>Username</Label>
        <Input placeholder="jane_doe" value={username} />
        {isUsernameInvalid ? (
          <FieldError>Username must be at least 3 characters.</FieldError>
        ) : (
          <Description>Choose a unique username for your profile.</Description>
        )}
      </TextField>

<TextField isRequired isInvalid={isBioInvalid} name="bio" onChange={setBio}>
        <Label>Bio</Label>
        <TextArea placeholder="Tell us about yourself..." value={bio} />
        {isBioInvalid ? (
          <FieldError>Bio must contain at least 20 characters.</FieldError>
        ) : (
          <Description>Minimum 20 characters ({bio.length}/20).</Description>
        )}
      </TextField>
    </div>
  );
}

```

### Controlled

Control the value to synchronize counters, previews, or formatting.

```tsx
"use client";

import {Description, Input, Label, TextArea, TextField} from "@heroui/react";
import React from "react";

export function Controlled() {
  const [name, setName] = React.useState("");
  const [bio, setBio] = React.useState("");

return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <TextField name="name" onChange={setName}>
        <Label>Display name</Label>
        <Input placeholder="Jane" value={name} />
        <Description>Characters: {name.length}</Description>
      </TextField>
      <TextField name="bio" onChange={setBio}>
        <Label>Bio</Label>
        <TextArea placeholder="Tell us about yourself..." value={bio} />
        <Description>Characters: {bio.length} / 200</Description>
      </TextField>
    </div>
  );
}

```

### Error Message

```tsx
import {FieldError, Input, Label, TextField} from "@heroui/react";

export function WithError() {
  return (
    <TextField isInvalid className="w-full max-w-64" name="email" type="email">
      <Label>Email</Label>
      <Input placeholder="user@example.com" />
      <FieldError>Please enter a valid email address</FieldError>
    </TextField>
  );
}

```

### Disabled State

```tsx
import {Description, Input, Label, TextField} from "@heroui/react";

export function Disabled() {
  return (
    <TextField isDisabled className="w-full max-w-64" name="accountId">
      <Label>Account ID</Label>
      <Input placeholder="Auto-generated" value="USR-12345" />
      <Description>This field cannot be edited</Description>
    </TextField>
  );
}

```

### TextArea

Use [TextArea](/docs/components/textarea) instead of [Input](/docs/components/input) for multiline content.

```tsx
import {Description, Label, TextArea, TextField} from "@heroui/react";

export function TextAreaExample() {
  return (
    <TextField className="w-full max-w-64" name="message">
      <Label>Message</Label>
      <TextArea placeholder="Write your message here..." rows={4} />
      <Description>Maximum 500 characters</Description>
    </TextField>
  );
}

```

### Input Types

```tsx
import {Input, Label, TextField} from "@heroui/react";

export function InputTypes() {
  return (
    <div className="flex w-full max-w-64 flex-col gap-4">
      <TextField name="password" type="password">
        <Label>Password</Label>
        <Input placeholder="••••••••" />
      </TextField>

<TextField name="email" type="email">
        <Label>Email</Label>
        <Input placeholder="user@example.com" />
      </TextField>

<TextField name="website" type="url">
        <Label>Website</Label>
        <Input placeholder="https://example.com" />
      </TextField>

<TextField name="phone" type="tel">
        <Label>Phone</Label>
        <Input placeholder="+1 (555) 000-0000" />
      </TextField>
    </div>
  );
}

```

### Full Width

```tsx
import {FieldError, Input, Label, TextField} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-4">
      <TextField fullWidth name="name">
        <Label>Your name</Label>
        <Input placeholder="John" />
      </TextField>
      <TextField fullWidth isInvalid isRequired name="password" type="password">
        <Label>Password</Label>
        <Input />
        <FieldError>Password must be longer than 8 characters</FieldError>
      </TextField>
    </div>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, TextField and its child Input/TextArea components automatically apply on-surface styling.

```tsx
import {Description, Input, Label, Surface, TextArea, TextField} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="flex w-full min-w-[340px] flex-col gap-4 rounded-3xl p-6">
      <TextField name="name">
        <Label>Your name</Label>
        <Input className="w-full" placeholder="John" />
        <Description>We'll never share this with anyone else</Description>
      </TextField>
      <TextField name="email" type="email">
        <Label>Email</Label>
        <Input className="w-full" placeholder="john@example.com" />
      </TextField>
      <TextField name="bio">
        <Label>Bio</Label>
        <TextArea className="w-full" placeholder="Tell us about yourself..." rows={4} />
        <Description>Minimum 4 rows</Description>
      </TextField>
    </Surface>
  );
}

```

## Related Components

* **Input**: Single-line text input built on React Aria
* **TextArea**: Multiline text input with focus management
* **Fieldset**: Group related form controls with legends

## Styling

### Passing Tailwind CSS classes

```tsx
import {TextField, Label, Input, Description} from '@heroui/react';

function CustomTextField() {
  return (
    <TextField className="gap-2 rounded-xl border border-border/60 bgsurface p-4 shadow-sm">
      <Label className="text-sm font-semibold text-default-700">
        Project name
      </Label>
      <Input className="rounded-lg border border-border/60 bgsurface px-3 py-2" />
      <Description className="text-xs text-default-500">
        Keep it short and memorable.
      </Description>
    </TextField>
  );
}

```

### Customizing the component classes

TextField has minimal default styling. Override the `.text-field` class to customize the container styling.

```css
@layer components {
  .text-field {
    @apply flex flex-col gap-1;
  }

/* When invalid, the description is hidden automatically */
  .text-field[data-invalid="true"] [data-slot="description"],
  .text-field[aria-invalid="true"] [data-slot="description"] {
    @apply hidden;
  }

/* Description has default padding */
  .text-field [data-slot="description"] {
    @apply px-1;
  }
}

```

### CSS Classes

* `.text-field` – Root container with minimal styling (`flex flex-col gap-1`)

> **Note:** Child components ([Label](/docs/components/label), [Input](/docs/components/input), [TextArea](/docs/components/textarea), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options.

### Interactive States

TextField automatically manages these data attributes based on its state:

* **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid
* **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true
* **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused
* **Focus Visible**: `[data-focus-visible="true"]` - Applied when focus is visible (keyboard navigation)

Additional attributes are available through render props (see TextFieldRenderProps below).

## API Reference

### TextField Props

TextField inherits all props from React Aria's [TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) component.

#### Base Props

| Prop        | Type                                                                           | Default | Description                                                    |
| ----------- | ------------------------------------------------------------------------------ | ------- | -------------------------------------------------------------- |
| `children`  | `React.ReactNode \| (values: TextFieldRenderProps) => React.ReactNode`         | -       | Child components (Label, Input, etc.) or render function.      |
| `className` | `string \| (values: TextFieldRenderProps) => string`                           | -       | CSS classes for styling, supports render props.                |
| `style`     | `React.CSSProperties \| (values: TextFieldRenderProps) => React.CSSProperties` | -       | Inline styles, supports render props.                          |
| `fullWidth` | `boolean`                                                                      | `false` | Whether the text field should take full width of its container |
| `id`        | `string`                                                                       | -       | The element's unique identifier.                               |

#### Validation Props

| Prop                 | Type                                                              | Default    | Description                                                    |
| -------------------- | ----------------------------------------------------------------- | ---------- | -------------------------------------------------------------- |
| `isRequired`         | `boolean`                                                         | `false`    | Whether user input is required before form submission.         |
| `isInvalid`          | `boolean`                                                         | -          | Whether the value is invalid.                                  |
| `validate`           | `(value: string) => ValidationError \| true \| null \| undefined` | -          | Custom validation function.                                    |
| `validationBehavior` | `'native' \| 'aria'`                                              | `'native'` | Whether to use native HTML form validation or ARIA attributes. |
| `validationErrors`   | `string[]`                                                        | -          | Server-side validation errors.                                 |

#### Value Props

#### State Props

#### Form Props

#### Accessibility Props

### Composition Components

TextField works with these separate components that should be imported and used directly:

* **Label** - Field label component from `@heroui/react`
* **Input** - Single-line text input from `@heroui/react`
* **TextArea** - Multi-line text input from `@heroui/react`
* **Description** - Helper text component from `@heroui/react`
* **FieldError** - Validation error message from `@heroui/react`

Each of these components has its own props API. Use them directly within TextField for composition:

```tsx
<TextField isRequired isInvalid={hasError}>
  <Label>Email Address</Label>
  <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} />
  <Description>We'll never share your email.</Description>
  <FieldError>Please enter a valid email address.</FieldError>
</TextField>

```

### TextFieldRenderProps

When using render props with `className`, `style`, or `children`, these values are available:

</page>

<page url="/docs/react/components/textarea">
# TextArea

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/textarea
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/textarea.mdx
> Primitive multiline text input component that accepts standard HTML attributes

## Import

```tsx
import { TextArea } from '@heroui/react';

```

<Callout>
  For validation, labels, and error messages, see **[TextField](/docs/components/text-field)**.
</Callout>

### Usage

```tsx
import {TextArea} from "@heroui/react";

export function Basic() {
  return (
    <TextArea
      aria-label="Quick project update"
      className="h-32 w-96"
      placeholder="Share a quick project update..."
    />
  );
}

```

### Controlled

```tsx
"use client";

import {Description, TextArea} from "@heroui/react";
import React from "react";

export function Controlled() {
  const [value, setValue] = React.useState("");

return (
    <div className="flex w-96 flex-col gap-2">
      <TextArea
        aria-describedby="textarea-controlled-description"
        aria-label="Announcement"
        placeholder="Compose an announcement..."
        value={value}
        onChange={(event) => setValue(event.target.value)}
      />
      <Description id="textarea-controlled-description">
        Characters: {value.length} / 280
      </Description>
    </div>
  );
}

```

### Rows and Resizing

```tsx
import {Label, TextArea} from "@heroui/react";

export function Rows() {
  return (
    <div className="flex w-96 flex-col gap-4">
      <div className="flex flex-col gap-2">
        <Label htmlFor="textarea-rows-3">Short feedback</Label>
        <TextArea
          aria-label="Short feedback"
          id="textarea-rows-3"
          placeholder="This week's highlights..."
          rows={3}
        />
      </div>
      <div className="flex flex-col gap-2">
        <Label htmlFor="textarea-rows-6">Detailed notes</Label>
        <TextArea
          aria-label="Detailed notes"
          id="textarea-rows-6"
          placeholder="Write out the full meeting notes..."
          rows={6}
          style={{resize: "vertical"}}
        />
      </div>
    </div>
  );
}

```

### Full Width

```tsx
import {TextArea} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-3">
      <TextArea fullWidth placeholder="Full width textarea" />
    </div>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, TextArea automatically applies on-surface styling.

```tsx
import {Surface, TextArea} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="w-full rounded-3xl p-6">
      <TextArea className="w-full min-w-[280px]" placeholder="Describe your product" />
    </Surface>
  );
}

```

## Related Components

* **TextField**: Composition-friendly fields with labels and validation
* **Input**: Single-line text input built on React Aria
* **Label**: Accessible label for form controls

## Styling

### Passing Tailwind CSS classes

```tsx
import {Label, TextArea} from '@heroui/react';

function CustomTextArea() {
  return (
    <div className="flex flex-col gap-2">
      <Label htmlFor="custom-textarea">Message</Label>
      <TextArea
        id="custom-textarea"
        className="rounded-xl border border-border/70 bgsurface px-4 py-3 text-sm leading-6 shadow-sm"
        placeholder="Let us know how we can help..."
        rows={5}
        style={{resize: "vertical"}}
      />
    </div>
  );
}

```

### Customizing the component classes

Override the shared `.textarea` class once with Tailwind's `@layer components`.

```css
@layer components {
  .textarea {
    @apply rounded-xl border border-border bgsurface px-4 py-3 text-sm leading-6 shadow-sm;

&:hover,
    &[data-hovered="true"] {
      @apply bg-surface-secondary border-border/80;
    }

&:focus-visible,
    &[data-focus-visible="true"] {
      @apply border-primary ring-2 ring-primary/20;
    }

&[data-invalid="true"] {
      @apply border-danger bg-danger-50/10 text-danger;
    }
  }
}

```

### CSS Classes

* `.textarea` – Underlying `<textarea>` element styling

### Interactive States

* **Hover**: `:hover` or `[data-hovered="true"]`
* **Focus Visible**: `:focus-visible` or `[data-focus-visible="true"]`
* **Invalid**: `[data-invalid="true"]`
* **Disabled**: `:disabled` or `[aria-disabled="true"]`

## API Reference

### TextArea Props

TextArea accepts all standard HTML `<textarea>` attributes plus the following:

| Prop           | Type                                                      | Default | Description                                                      |
| -------------- | --------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `className`    | `string`                                                  | -       | Tailwind classes merged with the base styles.                    |
| `rows`         | `number`                                                  | `3`     | Number of visible text lines.                                    |
| `cols`         | `number`                                                  | -       | Visible width of the text control.                               |
| `value`        | `string`                                                  | -       | Controlled value for the textarea.                               |
| `defaultValue` | `string`                                                  | -       | Initial uncontrolled value.                                      |
| `onChange`     | `(event: React.ChangeEvent<HTMLTextAreaElement>) => void` | -       | Change handler.                                                  |
| `placeholder`  | `string`                                                  | -       | Placeholder text.                                                |
| `disabled`     | `boolean`                                                 | `false` | Disables the textarea.                                           |
| `readOnly`     | `boolean`                                                 | `false` | Makes the textarea read-only.                                    |
| `required`     | `boolean`                                                 | `false` | Marks the textarea as required.                                  |
| `name`         | `string`                                                  | -       | Name for form submission.                                        |
| `autoComplete` | `string`                                                  | -       | Autocomplete hint for the browser.                               |
| `maxLength`    | `number`                                                  | -       | Maximum number of characters.                                    |
| `minLength`    | `number`                                                  | -       | Minimum number of characters.                                    |
| `wrap`         | `'soft' \| 'hard'`                                        | -       | How text wraps when submitted.                                   |
| `fullWidth`    | `boolean`                                                 | `false` | Whether the textarea should take full width of its container     |
| `isOnSurface`  | `boolean`                                                 | `false` | Whether the textarea is displayed on a surface (affects styling) |

> For validation props like `isInvalid`, `isRequired`, and error handling, use **[TextField](/docs/components/text-field)** with TextArea as a child component.

</page>

<page url="/docs/react/components/time-field">
# TimeField

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/time-field
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/time-field.mdx
> Time input field with labels, descriptions, and validation built on React Aria TimeField

## Import

```tsx
import { TimeField } from '@heroui/react';

```

### Usage

```tsx
"use client";

import {DateInputGroup, Label, TimeField} from "@heroui/react";

```

### Anatomy

```tsx
import {TimeField, Label, DateInputGroup, Description, FieldError} from '@heroui/react';

export default () => (
  <TimeField>
    <Label />
    <DateInputGroup>
      <DateInputGroup.Input>
        {(segment) => <DateInputGroup.Segment segment={segment} />}
      </DateInputGroup.Input>
    </DateInputGroup>
    <Description />
    <FieldError />
  </TimeField>
)

```

> **TimeField** combines label, time input, description, and error into a single accessible component.

### With Description

```tsx
"use client";

import {DateInputGroup, Description, Label, TimeField} from "@heroui/react";

export function WithDescription() {
  return (
    <div className="flex flex-col gap-4">
      <TimeField className="w-[256px]" name="time">
        <Label>Start time</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Enter the start time</Description>
      </TimeField>
      <TimeField className="w-[256px]" name="end-time">
        <Label>End time</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Enter the end time</Description>
      </TimeField>
    </div>
  );
}

```

### Required Field

```tsx
"use client";

import {DateInputGroup, Description, Label, TimeField} from "@heroui/react";

export function Required() {
  return (
    <div className="flex flex-col gap-4">
      <TimeField isRequired className="w-[256px]" name="time">
        <Label>Time</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
      </TimeField>
      <TimeField isRequired className="w-[256px]" name="appointment-time">
        <Label>Appointment time</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Required field</Description>
      </TimeField>
    </div>
  );
}

```

### Validation

Use `isInvalid` together with `FieldError` to surface validation messages.

```tsx
"use client";

import {DateInputGroup, FieldError, Label, TimeField} from "@heroui/react";

export function Invalid() {
  return (
    <div className="flex flex-col gap-4">
      <TimeField isInvalid isRequired className="w-[256px]" name="time">
        <Label>Time</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <FieldError>Please enter a valid time</FieldError>
      </TimeField>
      <TimeField isInvalid className="w-[256px]" name="invalid-time">
        <Label>Time</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <FieldError>Time must be within business hours</FieldError>
      </TimeField>
    </div>
  );
}

```

### With Validation

TimeField supports validation with `minValue`, `maxValue`, and custom validation logic.

```tsx
"use client";

import type {Time} from "@internationalized/date";

import {DateInputGroup, Description, FieldError, Label, TimeField} from "@heroui/react";
import {parseTime} from "@internationalized/date";
import {useState} from "react";

export function WithValidation() {
  const [value, setValue] = useState<Time | null>(null);
  const minTime = parseTime("09:00");
  const maxTime = parseTime("17:00");
  const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0);

return (
    <div className="flex flex-col gap-4">
      <TimeField
        isRequired
        className="w-[256px]"
        isInvalid={isInvalid}
        maxValue={maxTime}
        minValue={minTime}
        name="time"
        value={value}
        onChange={setValue}
      >
        <Label>Time</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        {isInvalid ? (
          <FieldError>Time must be between 9:00 AM and 5:00 PM</FieldError>
        ) : (
          <Description>Enter a time between 9:00 AM and 5:00 PM</Description>
        )}
      </TimeField>
    </div>
  );
}

```

### Controlled

Control the value to synchronize with other components or state management.

```tsx
"use client";

import type {TimeValue} from "@heroui/react";

import {Button, DateInputGroup, Description, Label, TimeField} from "@heroui/react";
import {Time, getLocalTimeZone, now} from "@internationalized/date";
import {useState} from "react";

export function Controlled() {
  const [value, setValue] = useState<TimeValue | null>(null);

return (
    <div className="flex flex-col gap-4">
      <TimeField className="w-[256px]" name="time" value={value} onChange={setValue}>
        <Label>Time</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Current value: {value ? value.toString() : "(empty)"}</Description>
      </TimeField>
      <div className="flex gap-2">
        <Button
          variant="tertiary"
          onPress={() => {
            const currentTime = now(getLocalTimeZone());

setValue(new Time(currentTime.hour, currentTime.minute, currentTime.second));
          }}
        >
          Set now
        </Button>
        <Button variant="tertiary" onPress={() => setValue(null)}>
          Clear
        </Button>
      </div>
    </div>
  );
}

```

### Disabled State

```tsx
"use client";

import {DateInputGroup, Description, Label, TimeField} from "@heroui/react";
import {Time, getLocalTimeZone, now} from "@internationalized/date";

export function Disabled() {
  const currentTime = now(getLocalTimeZone());
  const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second);

return (
    <div className="flex flex-col gap-4">
      <TimeField isDisabled className="w-[256px]" name="time" value={timeValue}>
        <Label>Time</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>This time field is disabled</Description>
      </TimeField>
      <TimeField isDisabled className="w-[256px]" name="time-empty">
        <Label>Time</Label>
        <DateInputGroup>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>This time field is disabled</Description>
      </TimeField>
    </div>
  );
}

```

### With Icons

Add prefix or suffix icons to enhance the time field.

```tsx
"use client";

import {Clock} from "@gravity-ui/icons";
import {DateInputGroup, Label, TimeField} from "@heroui/react";

export function WithPrefixIcon() {
  return (
    <TimeField className="w-[256px]" name="time">
      <Label>Time</Label>
      <DateInputGroup>
        <DateInputGroup.Prefix>
          <Clock className="size-4 text-muted" />
        </DateInputGroup.Prefix>
        <DateInputGroup.Input>
          {(segment) => <DateInputGroup.Segment segment={segment} />}
        </DateInputGroup.Input>
      </DateInputGroup>
    </TimeField>
  );
}

```

```tsx
"use client";

import {Clock} from "@gravity-ui/icons";
import {DateInputGroup, Label, TimeField} from "@heroui/react";

export function WithSuffixIcon() {
  return (
    <TimeField className="w-[256px]" name="time">
      <Label>Time</Label>
      <DateInputGroup>
        <DateInputGroup.Input>
          {(segment) => <DateInputGroup.Segment segment={segment} />}
        </DateInputGroup.Input>
        <DateInputGroup.Suffix>
          <Clock className="size-4 text-muted" />
        </DateInputGroup.Suffix>
      </DateInputGroup>
    </TimeField>
  );
}

```

```tsx
"use client";

import {ChevronDown, Clock} from "@gravity-ui/icons";
import {DateInputGroup, Description, Label, TimeField} from "@heroui/react";

export function WithPrefixAndSuffix() {
  return (
    <TimeField className="w-[256px]" name="time">
      <Label>Time</Label>
      <DateInputGroup>
        <DateInputGroup.Prefix>
          <Clock className="size-4 text-muted" />
        </DateInputGroup.Prefix>
        <DateInputGroup.Input>
          {(segment) => <DateInputGroup.Segment segment={segment} />}
        </DateInputGroup.Input>
        <DateInputGroup.Suffix>
          <ChevronDown className="size-4 text-muted" />
        </DateInputGroup.Suffix>
      </DateInputGroup>
      <Description>Enter a time</Description>
    </TimeField>
  );
}

```

### Full Width

```tsx
"use client";

import {ChevronDown, Clock} from "@gravity-ui/icons";
import {DateInputGroup, Label, TimeField} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-4">
      <TimeField fullWidth name="time">
        <Label>Time</Label>
        <DateInputGroup fullWidth>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
      </TimeField>
      <TimeField fullWidth name="time-icons">
        <Label>Time</Label>
        <DateInputGroup fullWidth>
          <DateInputGroup.Prefix>
            <Clock className="size-4 text-muted" />
          </DateInputGroup.Prefix>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
          <DateInputGroup.Suffix>
            <ChevronDown className="size-4 text-muted" />
          </DateInputGroup.Suffix>
        </DateInputGroup>
      </TimeField>
    </div>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, TimeField and its child DateInputGroup automatically apply on-surface styling.

```tsx
"use client";

import {Clock} from "@gravity-ui/icons";
import {DateInputGroup, Description, Label, Surface, TimeField} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6">
      <TimeField className="w-full" name="time">
        <Label>Time</Label>
        <DateInputGroup isOnSurface>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Enter a time</Description>
      </TimeField>
      <TimeField className="w-full" name="time-2">
        <Label>Appointment time</Label>
        <DateInputGroup isOnSurface>
          <DateInputGroup.Prefix>
            <Clock className="size-4 text-muted" />
          </DateInputGroup.Prefix>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        <Description>Enter a time for your appointment</Description>
      </TimeField>
    </Surface>
  );
}

```

### Form Example

Complete form example with validation and submission handling.

```tsx
"use client";

import type {Time} from "@internationalized/date";

import {Clock} from "@gravity-ui/icons";
import {
  Button,
  DateInputGroup,
  Description,
  FieldError,
  Form,
  Label,
  TimeField,
} from "@heroui/react";
import {parseTime} from "@internationalized/date";
import {useState} from "react";

export function FormExample() {
  const [value, setValue] = useState<Time | null>(null);
  const [isSubmitting, setIsSubmitting] = useState(false);
  const minTime = parseTime("09:00");
  const maxTime = parseTime("17:00");
  const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0);

const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();

if (!value || isInvalid) {
      return;
    }

setIsSubmitting(true);

// Simulate API call
    setTimeout(() => {
      console.log("Time submitted:", {time: value});
      setValue(null);
      setIsSubmitting(false);
    }, 1500);
  };

return (
    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
      <TimeField
        isRequired
        className="w-full"
        isInvalid={isInvalid}
        maxValue={maxTime}
        minValue={minTime}
        name="time"
        value={value}
        onChange={setValue}
      >
        <Label>Appointment time</Label>
        <DateInputGroup>
          <DateInputGroup.Prefix>
            <Clock className="size-4 text-muted" />
          </DateInputGroup.Prefix>
          <DateInputGroup.Input>
            {(segment) => <DateInputGroup.Segment segment={segment} />}
          </DateInputGroup.Input>
        </DateInputGroup>
        {isInvalid ? (
          <FieldError>Time must be between 9:00 AM and 5:00 PM</FieldError>
        ) : (
          <Description>Enter a time between 9:00 AM and 5:00 PM</Description>
        )}
      </TimeField>
      <Button
        className="w-full"
        isDisabled={!value || isInvalid}
        isPending={isSubmitting}
        type="submit"
        variant="primary"
      >
        {isSubmitting ? "Submitting..." : "Submit"}
      </Button>
    </Form>
  );
}

```

## Related Components

* **Label**: Accessible label for form controls
* **FieldError**: Inline validation messages for form fields
* **Description**: Helper text for form fields

## Styling

### Passing Tailwind CSS classes

```tsx
import {TimeField, Label, DateInputGroup, Description} from '@heroui/react';

function CustomTimeField() {
  return (
    <TimeField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
      <Label className="text-sm font-semibold text-default-700">
        Appointment time
      </Label>
      <DateInputGroup className="rounded-lg border border-border/60 bg-surface px-3 py-2">
        <DateInputGroup.Input>
          {(segment) => <DateInputGroup.Segment segment={segment} />}
        </DateInputGroup.Input>
      </DateInputGroup>
      <Description className="text-xs text-default-500">
        Select a time for your appointment.
      </Description>
    </TimeField>
  );
}

```

### Customizing the component classes

TimeField has minimal default styling. Override the `.time-field` class to customize the container styling.

```css
@layer components {
  .time-field {
    @apply flex flex-col gap-1;

&[data-invalid="true"],
    &[aria-invalid="true"] {
      [data-slot="description"] {
        @apply hidden;
      }
    }

[data-slot="label"] {
      @apply w-fit;
    }

[data-slot="description"] {
      @apply px-1;
    }
  }
}

```

### CSS Classes

* `.time-field` – Root container with minimal styling (`flex flex-col gap-1`)

### Interactive States

TimeField automatically manages these data attributes based on its state:

## API Reference

### TimeField Props

TimeField inherits all props from React Aria's [TimeField](https://react-aria.adobe.com/TimeField) component.

#### Base Props

| Prop        | Type                                                                           | Default | Description                                                        |
| ----------- | ------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------ |
| `children`  | `React.ReactNode \| (values: TimeFieldRenderProps) => React.ReactNode`         | -       | Child components (Label, DateInputGroup, etc.) or render function. |
| `className` | `string \| (values: TimeFieldRenderProps) => string`                           | -       | CSS classes for styling, supports render props.                    |
| `style`     | `React.CSSProperties \| (values: TimeFieldRenderProps) => React.CSSProperties` | -       | Inline styles, supports render props.                              |
| `fullWidth` | `boolean`                                                                      | `false` | Whether the time field should take full width of its container     |
| `id`        | `string`                                                                       | -       | The element's unique identifier.                                   |

#### Value Props

| Prop               | Type                                 | Default | Description                                                                                                                 |
| ------------------ | ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------- |
| `value`            | `TimeValue \| null`                  | -       | Current value (controlled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types.   |
| `defaultValue`     | `TimeValue \| null`                  | -       | Default value (uncontrolled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
| `onChange`         | `(value: TimeValue \| null) => void` | -       | Handler called when the value changes.                                                                                      |
| `placeholderValue` | `TimeValue \| null`                  | -       | Placeholder time that influences the format of the placeholder. Defaults to 12:00 AM or 00:00 depending on the hour cycle.  |

#### Validation Props

| Prop                 | Type                                                                 | Default    | Description                                                                                                                                    |
| -------------------- | -------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `isRequired`         | `boolean`                                                            | `false`    | Whether user input is required before form submission.                                                                                         |
| `isInvalid`          | `boolean`                                                            | -          | Whether the value is invalid.                                                                                                                  |
| `minValue`           | `TimeValue \| null`                                                  | -          | The minimum allowed time that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
| `maxValue`           | `TimeValue \| null`                                                  | -          | The maximum allowed time that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. |
| `validate`           | `(value: TimeValue) => ValidationError \| true \| null \| undefined` | -          | Custom validation function.                                                                                                                    |
| `validationBehavior` | `'native' \| 'aria'`                                                 | `'native'` | Whether to use native HTML form validation or ARIA attributes.                                                                                 |

#### Format Props

| Prop                      | Type                             | Default    | Description                                                                               |
| ------------------------- | -------------------------------- | ---------- | ----------------------------------------------------------------------------------------- |
| `granularity`             | `'hour' \| 'minute' \| 'second'` | `'minute'` | Determines the smallest unit displayed in the time picker.                                |
| `hourCycle`               | `12 \| 24`                       | -          | Whether to display time in 12 or 24 hour format. By default, determined by locale.        |
| `hideTimeZone`            | `boolean`                        | `false`    | Whether to hide the time zone abbreviation.                                               |
| `shouldForceLeadingZeros` | `boolean`                        | -          | Whether to always show leading zeros in the hour field. By default, determined by locale. |

#### State Props

#### Form Props

| Prop        | Type      | Default | Description                                                                      |
| ----------- | --------- | ------- | -------------------------------------------------------------------------------- |
| `name`      | `string`  | -       | Name of the input element, for HTML form submission. Submits as ISO 8601 string. |
| `autoFocus` | `boolean` | -       | Whether the element should receive focus on render.                              |

#### Accessibility Props

### Composition Components

TimeField works with these separate components that should be imported and used directly:

Each of these components has its own props API. Use them directly within TimeField for composition:

```tsx
import {parseTime} from '@internationalized/date';
import {TimeField, Label, DateInputGroup, Description, FieldError} from '@heroui/react';

<TimeField
  isRequired
  isInvalid={hasError}
  minValue={parseTime('09:00')}
  maxValue={parseTime('17:00')}
  value={time}
  onChange={setTime}
>
  <Label>Appointment Time</Label>
  <DateInputGroup>
    <DateInputGroup.Input>
      {(segment) => <DateInputGroup.Segment segment={segment} />}
    </DateInputGroup.Input>
  </DateInputGroup>
  <Description>Select a time between 9:00 AM and 5:00 PM.</Description>
  <FieldError>Please select a valid time.</FieldError>
</TimeField>

```

### TimeValue Types

TimeField uses types from [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/):

* `Time` - Time only (hour, minute, second)
* `CalendarDateTime` - Date with time but no timezone (TimeField displays only the time portion)
* `ZonedDateTime` - Date with time and timezone (TimeField displays only the time portion)

Example:

```tsx
import {parseTime, Time, getLocalTimeZone, now} from '@internationalized/date';

// Parse from string
const time = parseTime('14:30');

// Create from current time
const currentTime = now(getLocalTimeZone());
const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second);

// Use in TimeField
<TimeField value={time} onChange={setTime}>
  {/* ... */}
</TimeField>

```

> **Note:** TimeField uses the [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) package for time manipulation, parsing, and type definitions. See the [Internationalized Date documentation](https://react-aria.adobe.com/internationalized/date/) for more information about available types and functions.

### TimeFieldRenderProps

When using render props with `className`, `style`, or `children`, these values are available:

### DateInputGroup Props

DateInputGroup accepts all props from React Aria's `Group` component plus the following:

### DateInputGroup.Input Props

DateInputGroup.Input accepts all props from React Aria's `DateInput` component plus the following:

The `DateInput` component accepts a render prop function that receives date segments. Each segment represents a part of the time (hour, minute, second, etc.).