# 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**: 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 ``` ### With Compound Parts Use Button.Label for explicit control over the label component. ```tsx ``` ### With Icons Combine icons with labels for enhanced visual communication. ```tsx ``` ### Icon Only Create square icon-only buttons using the isIconOnly prop. ```tsx ``` ### Sizes Control button dimensions with three size options. ```tsx ``` ### Variants Choose from seven visual variants for different emphasis levels. ```tsx ``` ### Feedback Variants Choose between highlight, ripple, or no feedback effects for press interactions. ```tsx { /* Highlight feedback (default) */ } ; { /* Ripple feedback */ } ; { /* No feedback overlay (only scale animation) */ } ; { /* Customize highlight animation */ } ; { /* Customize ripple animation */ } ; ``` ### Loading State with Spinner Transform button to loading state with spinner animation. ```tsx const themeColorAccentForeground = useThemeColor('accent-foreground'); ; ``` ### Custom Background with LinearGradient Add gradient backgrounds using absolute positioned elements. Use `pressableFeedbackVariant="none"` to disable the default highlight overlay, or add a custom ripple effect. ```tsx import { Button, PressableFeedback } from 'heroui-native'; import { LinearGradient } from 'expo-linear-gradient'; import { StyleSheet } from 'react-native'; { /* Gradient with no feedback overlay */ } ; { /* Gradient with custom ripple effect */ } ; ``` ## 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, themeColorAccentSoftForeground, themeColorDangerForeground, themeColorDefaultForeground, ] = useThemeColor([ 'accent-foreground', 'accent-soft-foreground', 'danger-foreground', 'default-foreground', ]); return ( ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/button.tsx). ## 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' \| 'outline' \| '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) | | `pressableFeedbackVariant` | `'highlight' \| 'ripple' \| 'none'` | `'highlight'` | Variant of pressable feedback effect | | `pressableFeedbackHighlightProps` | `PressableFeedbackHighlightProps` | - | Props for PressableFeedback.Highlight component | | `pressableFeedbackRippleProps` | `PressableFeedbackRippleProps` | - | Props for PressableFeedback.Ripple component | For inherited props including `animation` (for root scale 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' \| 'outline' \| '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. # CloseButton **Category**: native **URL**: https://v3.heroui.com/docs/native/components/close-button **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(buttons)/close-button.mdx > Button component for closing dialogs, modals, or dismissing content. ## Import ```tsx import { CloseButton } from 'heroui-native'; ``` ## Usage ### Basic Usage The CloseButton component renders a close icon button with default styling. ```tsx ``` ### Custom Icon Color Customize the icon color using the `iconProps` prop. ```tsx ``` ### Custom Icon Size Adjust the icon size using the `iconProps` prop. ```tsx ``` ### Custom Children Replace the default close icon with custom content. ```tsx ``` ### Disabled State Disable the button to prevent interactions. ```tsx ``` ## Example ```tsx import { CloseButton, useThemeColor } from 'heroui-native'; import { Ionicons } from '@expo/vector-icons'; import { View } from 'react-native'; import { withUniwind } from 'uniwind'; const StyledIonicons = withUniwind(Ionicons); export default function CloseButtonExample() { const themeColorForeground = useThemeColor('foreground'); const themeColorDanger = useThemeColor('danger'); return ( ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/close-button.tsx). ## API Reference ### CloseButton CloseButton extends all props from [Button](./button) component. It defaults to `variant='tertiary'`, `size='sm'`, and `isIconOnly=true`. | prop | type | default | description | | ----------- | ---------------------- | ------- | ------------------------------------------------ | | `iconProps` | `CloseButtonIconProps` | - | Props for customizing the close icon | | `children` | `React.ReactNode` | - | Custom content to replace the default close icon | For inherited props including `isDisabled`, `className`, `animation`, `pressableFeedbackVariant`, `pressableFeedbackHighlightProps`, `pressableFeedbackRippleProps`, and all Pressable props, see [Button API Reference](./button#api-reference). #### CloseButtonIconProps | prop | type | default | description | | ------- | -------- | ---------------------- | ----------------- | | `size` | `number` | `20` | Size of the icon | | `color` | `string` | Uses theme muted color | Color of the icon | # 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**: 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 Basic Chip ``` ### Sizes Control the chip size with the `size` prop. ```tsx Small Medium Large ``` ### Variants Choose between different visual styles with the `variant` prop. ```tsx Primary Secondary Tertiary Soft ``` ### Colors Apply different color themes with the `color` prop. ```tsx Accent Default Success Warning Danger ``` ### With Icons Add icons or custom content alongside text using compound components. ```tsx Featured Close ``` ### Custom Styling Apply custom styles using className or style props. ```tsx Custom ``` ### Disable All Animations Disable all animations including children by using the `"disable-all"` value for the `animation` prop. ```tsx { /* Disable all animations including children */ } No Animations; ``` ## Example ```tsx import { Chip } from 'heroui-native'; import { View, Text } from 'react-native'; import { Ionicons } from '@expo/vector-icons'; export default function ChipExample() { return ( Small Medium Large Primary Success Premium Remove Custom ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/chip.tsx). ## 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. # Alert **Category**: native **URL**: https://v3.heroui.com/docs/native/components/alert **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(feedback)/alert.mdx > Displays important messages and notifications to users with status indicators. ## Import ```tsx import { Alert } from 'heroui-native'; ``` ## Anatomy ```tsx ... ... ``` * **Alert**: Main container with `role="alert"` and status-based styling. Provides status context to sub-components via a primitive context. * **Alert.Indicator**: Renders a status-appropriate icon by default. Accepts custom children to override the default icon. Supports `iconProps` for customising size and color. * **Alert.Content**: Wrapper for the title and description. Provides layout structure for text content. * **Alert.Title**: Heading text with status-based color. Connected to root via `aria-labelledby`. * **Alert.Description**: Body text rendered with muted color. Connected to root via `aria-describedby`. ## Usage ### Basic Usage The Alert component uses compound parts to display a notification with an icon, title, and description. ```tsx New features available Check out our latest updates including dark mode support and improved accessibility features. ``` ### Status Variants Set the `status` prop to control the icon and title color. Available statuses are `default`, `accent`, `success`, `warning`, and `danger`. ```tsx Success ... Scheduled maintenance ... Unable to connect ... ``` ### Title Only Omit `Alert.Description` for a compact single-line alert. ```tsx Profile updated successfully ``` ### With Action Buttons Place additional elements like buttons alongside the content. ```tsx Update available A new version of the application is available. ``` ### Custom Indicator Replace the default status icon by passing custom children to `Alert.Indicator`. ```tsx Processing your request Please wait while we sync your data. ``` ### Custom Styling Apply custom styles using the `className` prop on the root and compound parts. ```tsx ... ... ``` ## Example ```tsx import { Alert, Button, CloseButton } from 'heroui-native'; import { View } from 'react-native'; export default function AlertExample() { return ( Update available A new version of the application is available. Please refresh to get the latest features and bug fixes. Unable to connect to server Unable to connect to the server. Check your internet connection and try again. Profile updated successfully ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/alert.tsx). ## API Reference ### Alert | prop | type | default | description | | -------------- | ------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to render inside the alert | | `status` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Status controlling the icon and color treatment | | `id` | `string \| number` | - | Unique identifier for the alert. Auto-generated when not provided | | `className` | `string` | - | Additional CSS classes | | `style` | `ViewStyle` | - | Additional styles applied to the root container | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Alert.Indicator | prop | type | default | description | | -------------- | ----------------- | ------- | ------------------------------------------------------------------ | | `children` | `React.ReactNode` | - | Custom children to render instead of the default status icon | | `className` | `string` | - | Additional CSS classes | | `iconProps` | `AlertIconProps` | - | Props passed to the default status icon (size and color overrides) | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | #### AlertIconProps | prop | type | default | description | | ------- | -------- | ------------ | ---------------------- | | `size` | `number` | `18` | Icon size in pixels | | `color` | `string` | status color | Icon color as a string | ### Alert.Content | prop | type | default | description | | -------------- | ----------------- | ------- | --------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements (typically Alert.Title and Alert.Description) | | `className` | `string` | - | Additional CSS classes | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Alert.Title | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Title text content | | `className` | `string` | - | Additional CSS classes | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### Alert.Description | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Description text content | | `className` | `string` | - | Additional CSS classes | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ## Hooks ### useAlert Hook to access the alert root context. Must be used within an `Alert` component. ```tsx import { useAlert } from 'heroui-native'; const { status, nativeID } = useAlert(); ``` #### Returns | property | type | description | | ---------- | ------------------------------------------------------------- | ------------------------------------------------------------ | | `status` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | Current alert status for sub-component styling | | `nativeID` | `string` | Unique identifier used for accessibility and ARIA attributes | # 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**: 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 ``` ### With Container Layout Use className on the group to control layout of skeleton items. ```tsx ``` ### 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 {/* This View is only for layout, no content */} ``` ### With Animation Variants Control animation style for all items in the group. ```tsx ``` ### With Custom Animation Configuration Configure shimmer or pulse animations for the entire group. ```tsx ``` ### With Enter/Exit Animations Apply Reanimated transitions when the group appears or disappears. ```tsx ``` ## 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 ( John Doe @johndoe This is the first line of the post content. Second line with more interesting content to read. Last line is shorter. ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/skeleton-group.tsx). ## 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` | - | Custom styles for the group container | | `...Animated.ViewProps` | `AnimatedProps` | - | All Reanimated Animated.View props are supported | #### SkeletonRootAnimation Animation configuration for SkeletonGroup 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 | | ------------------------ | ---------------------------------------- | --------------------------- | ----------------------------------------------- | | `state` | `'disabled' \| 'disable-all' \| boolean` | - | Disable animations while customizing properties | | `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` | - | 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. # 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 ``` ## Usage ### Basic Usage The Skeleton component creates an animated placeholder while content is loading. ```tsx ``` ### With Content Show skeleton while loading, then display content when ready. ```tsx Loaded Content ``` ### Animation Variants Control the animation style with the `variant` prop. ```tsx ``` ### Custom Shimmer Configuration Customize the shimmer effect with duration, speed, and highlight color. ```tsx ... ``` ### Custom Pulse Configuration Configure pulse animation with duration and opacity range. ```tsx ... ``` ### Shape Variations Create different skeleton shapes using className for styling. ```tsx ``` ### Custom Enter/Exit Animations Apply custom Reanimated transitions when skeleton appears or disappears. ```tsx ... ``` ## 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 ( John Doe @johndoe ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/skeleton.tsx). ## 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 | | `isAnimatedStyleActive` | `boolean` | `true` | Whether animated styles (react-native-reanimated) are active | | `className` | `string` | - | Additional CSS classes for styling | | `...Animated.ViewProps` | `AnimatedProps` | - | All Reanimated Animated.View props are supported | #### SkeletonRootAnimation Animation configuration for Skeleton 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 | | ------------------------ | ---------------------------------------- | --------------------------- | ----------------------------------------------- | | `state` | `'disabled' \| 'disable-all' \| boolean` | - | Disable animations while customizing properties | | `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 | # 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**: 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 ``` ### Sizes Control the spinner size with the `size` prop. ```tsx ``` ### Colors Use predefined color variants or custom colors. ```tsx ``` ### Loading State Control the visibility of the spinner with the `isLoading` prop. ```tsx ``` ### Animation Speed Customize the rotation speed using the `animation` prop on the Indicator component. ```tsx ``` ### 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 ( Loading content... Processing... setIsLoading(!isLoading)}> {isLoading ? 'Tap to stop' : 'Tap to start'} ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/spinner.tsx). ## 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: * `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 | | ---------------- | ---------------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------- | | `state` | `'disabled' \| 'disable-all' \| boolean` | - | Disable animations while customizing properties | | `entering.value` | `EntryOrExitLayoutType` | `FadeIn`
`.duration(200)`
`.easing(Easing.out(Easing.ease))` | Custom entering animation | | `exiting.value` | `EntryOrExitLayoutType` | `FadeOut`
`.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 | | `isAnimatedStyleActive` | `boolean` | `true` | Whether animated styles (react-native-reanimated) are active | | `...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 | | ----------------- | ---------------------------- | --------------- | ----------------------------------------------- | | `state` | `'disabled' \| boolean` | - | Disable animations while customizing properties | | `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 | # 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**: 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 ``` ### With Custom Indicator Use a render function in the Indicator to show/hide custom icons based on state. ```tsx {({ isSelected }) => (isSelected ? : null)} ``` ### Invalid State Show validation errors with the `isInvalid` prop, which applies danger color styling. ```tsx ``` ### Custom Animations Customize or disable animations for both the root checkbox and indicator. ```tsx { /* Disable all animations (root and indicator) */ } ; { /* Disable only root animation */ } ; { /* Disable only indicator animation */ } ; { /* Custom animation configuration */ } ; ``` ## Example ```tsx import { Checkbox, Description, ControlField, Label, Separator, 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 = ({ isSelected, onSelectedChange, title, description, }) => { return ( {title} {description} ); }; 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; return ( {fieldKeys.map((key, index) => ( {index > 0 && } ))} ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/checkbox.tsx). ## 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) | | `variant` | `'primary' \| 'secondary'` | `'primary'` | Variant style for the checkbox | | `hitSlop` | `number` | `6` | Hit slop for the pressable area | | `animation` | `CheckboxRootAnimation` | - | Animation configuration | | `isAnimatedStyleActive` | `boolean` | `true` | Whether animated styles (react-native-reanimated) are active | | `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: * `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 | | -------------------- | ---------------------------------------- | ------------------- | ----------------------------------------------- | | `state` | `'disabled' \| 'disable-all' \| boolean` | - | Disable animations while customizing properties | | `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 | | `isAnimatedStyleActive` | `boolean` | `true` | Whether animated styles (react-native-reanimated) are active | | `...AnimatedViewProps` | `AnimatedProps` | - | 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 | | --------------------------- | ----------------------- | ------------------- | ----------------------------------------------- | | `state` | `'disabled' \| boolean` | - | Disable animations while customizing properties | | `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) | | `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. # ControlField **Category**: native **URL**: https://v3.heroui.com/docs/native/components/control-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/control-field.mdx > A field component that combines a label, description (or other content), and a control component (Switch or Checkbox) into a single pressable area. ## Import ```tsx import { ControlField } from 'heroui-native'; ``` ## Anatomy ```tsx ... ... ... ... ``` * **ControlField**: Root container that manages layout and state propagation * **Label**: Primary text label for the control (from [Label](./label) component) * **Description**: Secondary descriptive helper text (from [Description](./description) component) * **ControlField.Indicator**: Container for the form control component ([Switch](./switch), [Checkbox](./checkbox), [Radio](./radio)) * **FieldError**: Validation error message display (from [FieldError](./field-error) component) ## Usage ### Basic Usage ControlField wraps form controls to provide consistent layout and state management. ```tsx Label text ``` ### With Description Add helper text below the label using the Description component. ```tsx Enable notifications Receive push notifications about your account activity ``` ### With Error Message Display validation errors using the ErrorMessage component. ```tsx I agree to the terms By checking this box, you agree to our Terms of Service This field is required ``` ### Disabled State Control interactivity with the disabled prop. ```tsx Disabled field This field is disabled ``` ### Disabling All Animations Disable all animations including children by using `"disable-all"`. This cascades down to all child components. ```tsx Label text Description text ``` ## Example ```tsx import { Checkbox, Description, FieldError, ControlField, Label, Switch, } from 'heroui-native'; import React from 'react'; import { ScrollView, View } from 'react-native'; export default function ControlFieldExample() { const [notifications, setNotifications] = React.useState(false); const [terms, setTerms] = React.useState(false); const [newsletter, setNewsletter] = React.useState(true); return ( Enable notifications Receive push notifications about your account activity I agree to the terms and conditions By checking this box, you agree to our Terms of Service This field is required Subscribe to newsletter ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/control-field.tsx). ## API Reference ### ControlField | prop | type | default | description | | ----------------- | -------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- | | children | `React.ReactNode \| ((props: ControlFieldRenderProps) => 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 | | isRequired | `boolean` | `false` | Whether the form control is required | | 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 | ### Label The `Label` component automatically consumes form state (`isDisabled`, `isInvalid`) from the ControlField context. **Note**: For complete prop documentation, see the [Label component documentation](./label). ### Description The `Description` component automatically consumes form state (`isDisabled`, `isInvalid`) from the ControlField context. **Note**: For complete prop documentation, see the [Description component documentation](./description). ### ControlField.Indicator | prop | type | default | description | | ------------ | ----------------------------------- | ---------- | ---------------------------------------------------------- | | children | `React.ReactNode` | - | Control component to render (Switch, Checkbox, Radio) | | variant | `'checkbox' \| 'radio' \| '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 ControlField context if they are not already present on the child component. When using the `radio` variant, the Radio component renders in standalone mode (outside of a RadioGroup). ### FieldError The `FieldError` component automatically consumes form state (`isInvalid`) from the ControlField context. **Note**: For complete prop documentation, see the [FieldError component documentation](./field-error). The error message visibility is controlled by the `isInvalid` state of the parent ControlField. ## Hooks ### useControlField **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` | Reanimated shared value indicating press state | # Description **Category**: native **URL**: https://v3.heroui.com/docs/native/components/description **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/description.mdx > Text component for providing accessible descriptions and helper text for form fields and other UI elements. ## Import ```tsx import { Description } from 'heroui-native'; ``` ## Anatomy ```tsx ... ``` * **Description**: Text component that displays description or helper text with muted styling. Can be linked to form fields via `nativeID` for accessibility support. ## Usage ### Basic Usage Display description text with default muted styling. ```tsx This is a helpful description. ``` ### With Form Fields Provide accessible descriptions for form fields using the `nativeID` prop. ```tsx Email address We'll never share your email with anyone else. ``` ### Accessibility Linking Link descriptions to form fields for screen reader support by using `nativeID` and `aria-describedby`. ```tsx Password Use at least 8 characters with a mix of letters, numbers, and symbols. ``` ### Hiding on Invalid State Control whether the description should be hidden when the form field is invalid using the `hideOnInvalid` prop. ```tsx Email We'll never share your email with anyone else. Please enter a valid email address ``` When `hideOnInvalid` is `true`, the description will be hidden when the field is invalid. When `false` (default), the description remains visible even when invalid. ## Example ```tsx import { Description, TextField } from 'heroui-native'; import { View } from 'react-native'; export default function DescriptionExample() { return ( Email address We'll never share your email with anyone else. Password Use at least 8 characters with a mix of letters, numbers, and symbols. ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/description.tsx). ## API Reference ### Description | prop | type | default | description | | --------------- | ----------------------------------- | ------- | ------------------------------------------------------------------------------------------ | | `children` | `React.ReactNode` | - | Description text content | | `className` | `string` | - | Additional CSS classes to apply | | `nativeID` | `string` | - | Native ID for accessibility. Used to link description to form fields via aria-describedby. | | `isInvalid` | `boolean` | - | Whether the description is in an invalid state (overrides context) | | `isDisabled` | `boolean` | - | Whether the description is disabled (overrides context) | | `hideOnInvalid` | `boolean` | `false` | Whether to hide the description when invalid | | `animation` | `DescriptionAnimation \| undefined` | - | Animation configuration for description transitions | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | # FieldError **Category**: native **URL**: https://v3.heroui.com/docs/native/components/field-error **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/field-error.mdx > Displays validation error message content with smooth animations. ## Import ```tsx import { FieldError } from 'heroui-native'; ``` ## Anatomy ```tsx Error message content ``` * **FieldError**: 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 FieldError component displays error messages when validation fails. ```tsx This field is required ``` ### Controlled Visibility Control when the error appears using the `isInvalid` prop. When used inside a form field component (like TextField), FieldError automatically consumes the form-item-state context. ```tsx const [isInvalid, setIsInvalid] = useState(false); Please enter a valid email address; ``` ### With Form Fields FieldError automatically consumes form state from TextField via the form-item-state context. ```tsx import { FieldError, Label, TextField } from 'heroui-native'; Email Please enter a valid email address ``` ### Custom Content Pass custom React components as children instead of strings. ```tsx Invalid input ``` ### Custom Animations Override default entering and exiting animations using the `animation` prop. ```tsx import { SlideInDown, SlideOutUp } from 'react-native-reanimated'; Field validation failed ; ``` Disable animations entirely: ```tsx Field validation failed ``` ### Custom Styling Apply custom styles to the container and text elements. ```tsx Password must be at least 8 characters ``` ### Custom Text Props Pass additional props to the Text component when children is a string. ```tsx This is a very long error message that might need to be truncated ``` ## Example ```tsx import { Description, FieldError, Label, TextField } from 'heroui-native'; import { useState } from 'react'; import { View } from 'react-native'; export default function FieldErrorExample() { const [email, setEmail] = useState(''); const [isInvalid, setIsInvalid] = useState(false); const isValidEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email); const handleBlur = () => { setIsInvalid(email !== '' && !isValidEmail); }; return ( Email Address We'll use this to contact you Please enter a valid email address ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/field-error.tsx). ## API Reference ### FieldError | prop | type | default | description | | ---------------------- | --------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `children` | `React.ReactNode` | `undefined` | The content of the error field. String children are wrapped with Text | | `isInvalid` | `boolean` | `undefined` | Controls the visibility of the error field (overrides form-item-state context). When used inside TextField, automatically consumes form state | | `animation` | `FieldErrorRootAnimation` | - | Animation configuration | | `className` | `string` | `undefined` | Additional CSS classes for the container | | `classNames` | `ElementSlots` | `undefined` | Additional CSS classes for different parts of the component | | `styles` | `{ container?: ViewStyle; text?: TextStyle }` | `undefined` | Styles for different parts of the field error | | `textProps` | `TextProps` | `undefined` | Additional props to pass to the Text component when children is a string | | `...AnimatedViewProps` | `AnimatedProps` | - | All Reanimated Animated.View props are supported | **classNames prop:** `ElementSlots` provides type-safe CSS classes for different parts of the field error component. Available slots: `container`, `text`. #### `styles` | prop | type | description | | ----------- | ----------- | --------------------------- | | `container` | `ViewStyle` | Styles for the container | | `text` | `TextStyle` | Styles for the text content | #### FieldErrorRootAnimation Animation configuration for field error 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 | | ---------------- | ---------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------- | | `state` | `'disabled' \| 'disable-all' \| boolean` | - | Disable animations while customizing properties | | `entering.value` | `EntryOrExitLayoutType` | `FadeIn`
`.duration(150)`
`.easing(Easing.out(Easing.ease))` | Custom entering animation for field error | | `exiting.value` | `EntryOrExitLayoutType` | `FadeOut`
`.duration(100)`
`.easing(Easing.out(Easing.ease))` | Custom exiting animation for field error | # InputOTP **Category**: native **URL**: https://v3.heroui.com/docs/native/components/input-otp **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/input-otp.mdx > Input component for entering one-time passwords (OTP) with individual character slots, animations, and validation support. ## Import ```tsx import { InputOTP } from 'heroui-native'; ``` ## Anatomy ```tsx ``` * **InputOTP**: Main container that manages OTP input state, handles text changes, and provides context to child components. Manages focus, validation, and character input. * **InputOTP.Group**: Container for grouping multiple slots together. Use this to visually group related slots (e.g., groups of 3 digits). * **InputOTP.Slot**: Individual slot that displays a single character or placeholder. Each slot must have a unique index matching its position in the OTP sequence. When no children are provided, automatically renders SlotPlaceholder, SlotValue, and SlotCaret. * **InputOTP.SlotPlaceholder**: Text component that displays the placeholder character for a slot when it's empty. Used by default in Slot if no children provided. * **InputOTP.SlotValue**: Text component that displays the actual character value for a slot with animations. Used by default in Slot if no children provided. * **InputOTP.SlotCaret**: Animated caret indicator that shows the current input position. Place this inside a Slot to show where the user is currently typing. * **InputOTP.Separator**: Visual separator between groups of slots. Use this to visually separate different groups of OTP digits. ## Usage ### Basic Usage Create a 6-digit OTP input with grouped slots and separator. ```tsx console.log(code)}> ``` ### Four Digits Create a simple 4-digit PIN input. ```tsx console.log(code)}> ``` ### With Placeholder Provide custom placeholder characters for each slot position. ```tsx console.log(code)} > {({ slots }) => ( <> {slots.map((slot) => ( ))} )} ``` ### Controlled Value Control the OTP value programmatically. ```tsx const [value, setValue] = useState(''); ; ``` ### With Validation Display validation errors when the OTP is invalid. ```tsx ``` ### With Pattern Restrict input to specific character patterns using regex. Three predefined patterns are available: `REGEXP_ONLY_DIGITS` (matches digits 0-9), `REGEXP_ONLY_CHARS` (matches alphabetic characters a-z, A-Z), and `REGEXP_ONLY_DIGITS_AND_CHARS` (matches both digits and alphabetic characters). ```tsx import { InputOTP, REGEXP_ONLY_CHARS } from 'heroui-native'; console.log(code)} > ; ``` ### Custom Layout Use render props in Group to create custom slot layouts. ```tsx {({ slots, isFocused, isInvalid }) => ( <> {slots.map((slot) => ( ))} )} ``` ## Example ```tsx import { InputOTP, Label, Description, type InputOTPRef } from 'heroui-native'; import { View } from 'react-native'; import { useRef } from 'react'; export default function InputOTPExample() { const ref = useRef(null); const onComplete = (code: string) => { console.log('OTP completed:', code); setTimeout(() => { ref.current?.clear(); }, 1000); }; return ( Verify account We've sent a code to a****@gmail.com ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/input-otp.tsx). ## API Reference ### InputOTP | prop | type | default | description | | -------------------------- | ----------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------- | | `maxLength` | `number` | - | Maximum length of the OTP (required) | | `value` | `string` | - | Controlled value for the OTP input | | `defaultValue` | `string` | - | Default value for uncontrolled usage | | `onChange` | `(value: string) => void` | - | Callback when value changes | | `onComplete` | `(value: string) => void` | - | Handler called when all slots are filled | | `isDisabled` | `boolean` | `false` | Whether the input is disabled | | `isInvalid` | `boolean` | `false` | Whether the input is in an invalid state | | `pattern` | `string` | - | Regex pattern for allowed characters (e.g., REGEXP\_ONLY\_DIGITS, REGEXP\_ONLY\_CHARS) | | `inputMode` | `TextInputProps['inputMode']` | `'numeric'` | Input mode for the input | | `placeholder` | `string` | - | Placeholder text for the input. Each character corresponds to a slot position | | `placeholderTextColor` | `string` | - | Placeholder text color for all slots | | `placeholderTextClassName` | `string` | - | Placeholder text class name for all slots | | `pasteTransformer` | `(text: string) => string` | - | Transform pasted text (e.g., remove hyphens). Defaults to removing non-matching characters | | `onFocus` | `(e: FocusEvent) => void` | - | Handler for focus events | | `onBlur` | `(e: BlurEvent) => void` | - | Handler for blur events | | `textInputProps` | `Omit` | - | Additional props to pass to the underlying TextInput component | | `children` | `React.ReactNode` | - | Children elements to be rendered inside the InputOTP | | `className` | `string` | - | Additional CSS classes to apply | | `style` | `PressableProps['style']` | - | Style to pass to the container Pressable component | | `isBottomSheetAware` | `boolean` | `true` | Whether the InputOTP automatically handles keyboard state when rendered inside a BottomSheet. Set to `false` to disable | | `animation` | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children | ### InputOTP.Group | prop | type | default | description | | -------------- | --------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | `children` | `React.ReactNode \| ((props: InputOTPGroupRenderProps) => React.ReactNode)` | - | Children elements to be rendered inside the group, or a render function that receives slot data and other context values | | `className` | `string` | - | Additional CSS classes to apply | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | #### InputOTPGroupRenderProps | prop | type | description | | ------------ | ------------ | ---------------------------------------- | | `slots` | `SlotData[]` | Array of slot data for each position | | `maxLength` | `number` | Maximum length of the OTP | | `value` | `string` | Current OTP value | | `isFocused` | `boolean` | Whether the input is currently focused | | `isDisabled` | `boolean` | Whether the input is disabled | | `isInvalid` | `boolean` | Whether the input is in an invalid state | ### InputOTP.Slot | prop | type | default | description | | -------------- | ----------------- | ------- | ------------------------------------------------------------------------------------------- | | `index` | `number` | - | Zero-based index of the slot (required). Must be between 0 and maxLength - 1 | | `children` | `React.ReactNode` | - | Custom slot content. If not provided, defaults to SlotPlaceholder, SlotValue, and SlotCaret | | `className` | `string` | - | Additional CSS classes to apply | | `style` | `ViewStyle` | - | Additional styles to apply | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### InputOTP.SlotPlaceholder | prop | type | default | description | | -------------- | ----------- | ------- | -------------------------------------------------------------------- | | `children` | `string` | - | Text content to display (optional, defaults to slot.placeholderChar) | | `className` | `string` | - | Additional CSS classes to apply | | `style` | `TextStyle` | - | Additional styles to apply | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### InputOTP.SlotValue | prop | type | default | description | | -------------- | ---------------------------- | ------- | --------------------------------------------------------- | | `children` | `string` | - | Text content to display (optional, defaults to slot.char) | | `className` | `string` | - | Additional CSS classes to apply | | `animation` | `InputOTPSlotValueAnimation` | - | Animation configuration for SlotValue | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | #### InputOTPSlotValueAnimation Animation configuration for InputOTP.SlotValue component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ------------------ | ----------------------- | ---------------------------------------- | ----------------------------------------------- | | `state` | `'disabled' \| boolean` | - | Disable animations while customizing properties | | `wrapper.entering` | `EntryOrExitLayoutType` | `FadeIn.duration(250)` | Entering animation for wrapper | | `wrapper.exiting` | `EntryOrExitLayoutType` | `FadeOut.duration(100)` | Exiting animation for wrapper | | `text.entering` | `EntryOrExitLayoutType` | `FlipInXDown.duration(250).easing(...)` | Entering animation for text | | `text.exiting` | `EntryOrExitLayoutType` | `FlipOutXDown.duration(250).easing(...)` | Exiting animation for text | ### InputOTP.SlotCaret | prop | type | default | description | | ----------------------- | ---------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `className` | `string` | - | Additional CSS classes to apply | | `style` | `ViewStyle` | - | Additional styles to apply | | `animation` | `InputOTPSlotCaretAnimation` | - | Animation configuration for SlotCaret | | `isAnimatedStyleActive` | `boolean` | `true` | Whether animated styles (react-native-reanimated) are active. When `false`, the animated style is removed and you can implement custom logic | | `pointerEvents` | `'none' \| 'auto' \| ...` | `'none'` | Pointer events configuration | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | #### InputOTPSlotCaretAnimation Animation configuration for InputOTP.SlotCaret component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ------------------ | ----------------------- | ---------- | ----------------------------------------------- | | `state` | `'disabled' \| boolean` | - | Disable animations while customizing properties | | `opacity.value` | `[number, number]` | `[0, 1]` | Opacity values \[min, max] | | `opacity.duration` | `number` | `500` | Animation duration in milliseconds | | `height.value` | `[number, number]` | `[16, 18]` | Height values \[min, max] in pixels | | `height.duration` | `number` | `500` | Animation duration in milliseconds | ### InputOTP.Separator | prop | type | default | description | | -------------- | ----------- | ------- | -------------------------------------------------- | | `className` | `string` | - | Additional CSS classes to apply | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ## Hooks ### useInputOTP Hook to access the InputOTP root context. Must be used within an `InputOTP` component. ```tsx const { value, maxLength, isFocused, isDisabled, isInvalid, slots } = useInputOTP(); ``` ### useInputOTPSlot Hook to access the InputOTP.Slot context. Must be used within an `InputOTP.Slot` component. ```tsx const { slot, isActive, isCaretVisible } = useInputOTPSlot(); ``` # Input **Category**: native **URL**: https://v3.heroui.com/docs/native/components/input **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/input.mdx > A text input component with styled border and background for collecting user input. ## Import ```tsx import { Input } from 'heroui-native'; ``` ## Usage ### Basic Usage Input can be used standalone or within a TextField component. ```tsx import { Input } from 'heroui-native'; ; ``` ### Within TextField Input works seamlessly with TextField for complete form structure. ```tsx import { Input, Label, TextField } from 'heroui-native'; Email ; ``` ### With Validation Display error state when the input is invalid. ```tsx import { FieldError, Input, Label, TextField } from 'heroui-native'; Email Please enter a valid email ; ``` ### With Local Invalid State Override Override the context's invalid state for the input. ```tsx import { FieldError, Input, Label, TextField } from 'heroui-native'; Email Email format is incorrect ; ``` ### Disabled State Disable the input to prevent interaction. ```tsx import { Input, Label, TextField } from 'heroui-native'; Disabled Field ; ``` ### With Variant Use different variants to style the input based on context. ```tsx import { Input, Label, TextField } from 'heroui-native'; Primary Variant Secondary Variant ``` ### Custom Styling Customize the input appearance using className. ```tsx import { Input, Label, TextField } from 'heroui-native'; Custom Styled ; ``` ## Example ```tsx import { Ionicons } from '@expo/vector-icons'; import { Description, Input, Label, TextField } from 'heroui-native'; import { useState } from 'react'; import { Pressable, View } from 'react-native'; import { withUniwind } from 'uniwind'; const StyledIonicons = withUniwind(Ionicons); export const TextInputContent = () => { const [email, setEmail] = useState(''); const [password, setPassword] = useState(''); const [isPasswordVisible, setIsPasswordVisible] = useState(false); return ( Email We'll never share your email with anyone else. New password setIsPasswordVisible(!isPasswordVisible)} > Password must be at least 6 characters ); }; ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/input.tsx). ## API Reference ### Input | prop | type | default | description | | ------------------------- | -------------------------- | --------------------- | -------------------------------------------------------------------------------------------------------------------- | | isInvalid | `boolean` | `undefined` | Whether the input is in an invalid state (overrides context) | | variant | `'primary' \| 'secondary'` | `'primary'` | Variant style for the input | | className | `string` | - | Custom class name for the input | | selectionColorClassName | `string` | `"accent-accent"` | Custom className for the selection color | | placeholderColorClassName | `string` | `"field-placeholder"` | Custom className for the placeholder text color | | isBottomSheetAware | `boolean` | `true` | Whether the input automatically handles keyboard state when rendered inside a BottomSheet. Set to `false` to disable | | animation | `AnimationRoot` | `undefined` | Animation configuration for the input | | ...TextInputProps | `TextInputProps` | - | All standard React Native TextInput props are supported | > **Note**: When used within a TextField component, Input automatically consumes form state (isDisabled, isInvalid) from TextField via the form-item-state context. # Label **Category**: native **URL**: https://v3.heroui.com/docs/native/components/label **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/label.mdx > Text component for labeling form fields and other UI elements with support for required indicators and validation states. ## Import ```tsx import { Label } from 'heroui-native'; ``` ## Anatomy ```tsx ... ``` * **Label**: Root container that manages label state and provides context to child components. When string children are provided, automatically renders as Label.Text. Supports disabled, required, and invalid states. * **Label.Text**: Text content of the label. Displays the label text and automatically shows an asterisk when the label is required. Changes color when invalid or disabled. ## Usage ### Basic Usage Display a label with text content. String children are automatically rendered as Label.Text. ```tsx Username ``` ### With Form Fields Use Label with form fields to provide accessible labels. ```tsx Username ``` ### Required Fields Show an asterisk indicator for required fields using the `isRequired` prop. ```tsx Password ``` ### Invalid State Display labels in an invalid state to indicate validation errors. ```tsx import { FieldError, Label, TextField } from 'heroui-native'; Confirm password Passwords do not match ``` ### Disabled State Disable labels to indicate non-interactive fields. ```tsx Subscription plan ``` ### Custom Layout Use compound components for custom label layouts. ```tsx Custom label ``` ### Custom Styling Apply custom styles using className, classNames, or styles props. ```tsx Custom styled label ``` ## Example ```tsx import { FieldError, Label, TextField } from 'heroui-native'; import { View } from 'react-native'; export default function LabelExample() { return ( Username Password Confirm password Passwords do not match Subscription plan ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/label.tsx). ## API Reference ### Label | prop | type | default | description | | ------------------- | ---------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Label content. When string is provided, automatically renders as Label.Text. Otherwise renders children as-is | | `isRequired` | `boolean` | `false` | Whether the label is required. Shows asterisk indicator when true | | `isInvalid` | `boolean` | `false` | Whether the label is in an invalid state. Changes text color to danger | | `isDisabled` | `boolean` | `false` | Whether the label is disabled. Applies disabled styling and prevents interaction | | `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 standard React Native Pressable props are supported | ### Label.Text | prop | type | default | description | | -------------- | ---------------------------------------- | ------- | ---------------------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Label text content | | `className` | `string` | - | Additional CSS classes to apply to the text element | | `classNames` | `ElementSlots` | - | Additional CSS classes for different parts of the label | | `styles` | `Partial>` | - | Styles for different parts of the label | | `nativeID` | `string` | - | Native ID for accessibility. Used to link label to form fields via aria-labelledby | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | #### `ElementSlots` | prop | type | description | | ---------- | -------- | ------------------------------ | | `text` | `string` | CSS classes for the label text | | `asterisk` | `string` | CSS classes for the asterisk | #### `styles` | prop | type | description | | ---------- | ----------- | ------------------------- | | `text` | `TextStyle` | Styles for the label text | | `asterisk` | `TextStyle` | Styles for the asterisk | # 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**: 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 a default `` indicator when text children are provided. Supports render function children to access state (`isSelected`, `isInvalid`, `isDisabled`). * **Label**: Optional clickable text label for the radio option. Linked to the radio for accessibility. Use the [Label](./label) component directly. * **Description**: Optional secondary text below the label. Provides additional context about the radio option. Use the [Description](./description) component directly. * **Radio**: The [Radio](./radio) component used inside `RadioGroup.Item` to render the radio indicator. Automatically detects the `RadioGroupItem` context and derives `isSelected`, `isDisabled`, `isInvalid`, and `variant` from it. * **Radio.Indicator**: Optional container for the radio circle. Renders default thumb if no children provided. Manages the visual selection state. See [Radio](./radio) for full API. * **Radio.IndicatorThumb**: Optional inner circle that appears when selected. Animates scale based on selection. Can be replaced with custom content. See [Radio](./radio) for full API. * **FieldError**: Error message displayed when radio group is invalid. Shown with animation below the radio group content. Use the [FieldError](./field-error) component directly. ## Usage ### Basic Usage RadioGroup with simple string children automatically renders title and indicator. ```tsx Option 1 Option 2 Option 3 ``` ### With Descriptions Add descriptive text below each radio option for additional context. ```tsx import { RadioGroup, Radio, Label, Description } from 'heroui-native'; import { View } from 'react-native'; Standard Shipping Delivered in 5-7 business days Express Shipping Delivered in 2-3 business days ; ``` ### Custom Indicator Replace the default indicator thumb with custom content using `Radio` sub-components. ```tsx import { RadioGroup, Radio, Label } from 'heroui-native'; {({ isSelected }) => ( <> Custom Option {isSelected && ( )} )} ; ``` ### With Render Function Use a render function on RadioGroup.Item to access state and customize the entire content. ```tsx import { RadioGroup, Radio, Label } from 'heroui-native'; {({ isSelected, isInvalid, isDisabled }) => ( <> Option 1 {isSelected && } )} ; ``` ### With Error Message Display validation errors below the radio group. ```tsx import { RadioGroup, FieldError } from 'heroui-native'; function RadioGroupWithError() { const [value, setValue] = React.useState(undefined); return ( I agree to the terms I do not agree Please select an option to continue ); } ``` ## Example ```tsx import { Description, Label, Radio, RadioGroup, Separator, Surface, } from 'heroui-native'; import React from 'react'; import { View } from 'react-native'; export default function RadioGroupExample() { const [selection, setSelection] = React.useState('desc1'); return ( Standard Shipping Delivered in 5-7 business days Express Shipping Delivered in 2-3 business days Overnight Shipping Delivered next business day ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/radio-group.tsx). ## 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 | | `variant` | `'primary' \| 'secondary'` | `undefined` | Variant style for the radio group (inherited by items if not set on item) | | `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 | | `variant` | `'primary' \| 'secondary'` | `'primary'` | Variant style for the radio item | | `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 | ### Radio (inside RadioGroup.Item) The [Radio](./radio) component is used inside `RadioGroup.Item` to render the radio indicator. When placed inside a `RadioGroup.Item`, the Radio component automatically detects the `RadioGroupItem` context and derives `isSelected`, `isDisabled`, `isInvalid`, and `variant` from it — no manual prop passing is needed. Use `` for the default indicator, or compose with `Radio.Indicator` and `Radio.IndicatorThumb` for custom styling. **Note:** For complete Radio prop documentation (including `Radio.Indicator` and `Radio.IndicatorThumb`), see the [Radio component documentation](./radio). **Note:** For labels, descriptions, and error messages, use the base components directly: * Use [Label](./label) component for labels * Use [Description](./description) component for descriptions * Use [FieldError](./field-error) component for error messages ## 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 | | `variant` | `'primary' \| 'secondary'` | Variant style for the radio group | | `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 \| undefined` | Whether the radio item is disabled | | `isInvalid` | `boolean \| undefined` | Whether the radio item is invalid | | `variant` | `'primary' \| 'secondary' \| undefined` | Variant style for the radio item | | `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | Callback to change the selection state (selects this item in the group) | # 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**: 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. Supports `variant` prop (`'default'` or `'unstyled'`). * **Select.Value**: Displays the selected value or placeholder text. Automatically updates when selection changes. Styling changes based on selection state. * **Select.TriggerIndicator**: Optional visual indicator showing open/close state. Renders an animated chevron icon by default that rotates when the select opens/closes. * **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 for the select. Can accept custom children or uses default close icon. * **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 ``` ### With Value Display Display the selected value in the trigger using the Value component. ```tsx ``` ### Popover Presentation Use popover presentation for floating content with automatic positioning. ```tsx ``` ### Width Control Control the width of the select content using the `width` prop. This only works with popover presentation. ```tsx { /* Fixed width in pixels */ } ; { /* Match trigger width */ } ; { /* Full width (100%) */ } ; { /* Auto-size to content (default) */ } ; ``` ### Bottom Sheet Presentation Use bottom sheet for mobile-optimized selection experience. ```tsx ``` ### Dialog Presentation Use dialog presentation for centered modal-style selection. ```tsx ``` ### Custom Item Content Customize item appearance with custom content and indicators. ```tsx ``` ### With Render Function Use a render function on `Select.Item` to access state and customize content based on selection. ```tsx ``` ### With Item Description Add descriptions to items for additional context. ```tsx ``` ### With Trigger Indicator Add a visual indicator to show the open/close state of the select. The indicator rotates when the select opens/closes. ```tsx ``` ### Custom Trigger with Unstyled Variant Use the `unstyled` variant when composing a custom trigger with other components like Button. ```tsx ``` ### Controlled Mode Control the select state programmatically. ```tsx const [value, setValue] = useState(); const [isOpen, setIsOpen] = useState(false); ; ``` ## Example ```tsx import { Select, Separator } from 'heroui-native'; import React, { useState } from 'react'; type SelectOption = { value: string; label: string; }; const US_STATES: SelectOption[] = [ { value: 'CA', label: 'California' }, { value: 'NY', label: 'New York' }, { value: 'TX', label: 'Texas' }, { value: 'FL', label: 'Florida' }, ]; export default function SelectExample() { const [value, setValue] = useState(); return ( ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/select.tsx). ## 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 | | `isDisabled` | `boolean` | `false` | Whether the select is disabled | | `presentation` | `'popover' \| 'bottom-sheet' \| 'dialog'` | `'popover'` | Presentation mode for the select content | | `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: * `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 | | ---------------- | ------------------------------------------------ | ------- | ----------------------------------------------- | | `state` | `'disabled' \| 'disable-all' \| boolean` | - | Disable animations while customizing properties | | `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 | | ------------------- | ------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------- | | `variant` | `'default' \| 'unstyled'` | `'default'` | The variant of the trigger. `'default'` applies pre-styled container styles, `'unstyled'` removes default styling | | `children` | `ReactNode` | - | The trigger element content | | `className` | `string` | - | Additional CSS classes for the trigger | | `asChild` | `boolean` | `true` | Whether to render as a child element | | `isDisabled` | `boolean` | - | Whether the trigger is disabled | | `...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 | **Note:** The value component automatically applies different text colors based on selection state: * When a value is selected: `text-foreground` * When no value is selected (placeholder): `text-field-placeholder` ### Select.TriggerIndicator | prop | type | default | description | | ----------------------- | --------------------------------- | ------- | ------------------------------------------------------------ | | `children` | `ReactNode` | - | Custom indicator content. Defaults to animated chevron icon | | `className` | `string` | - | Additional CSS classes for the trigger indicator | | `style` | `ViewStyle` | - | Custom styles for the trigger indicator | | `iconProps` | `SelectTriggerIndicatorIconProps` | - | Chevron icon configuration | | `animation` | `SelectTriggerIndicatorAnimation` | - | Animation configuration | | `isAnimatedStyleActive` | `boolean` | `true` | Whether animated styles (react-native-reanimated) are active | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | **Note:** The following style properties are occupied by animations and cannot be set via className: * `transform` (specifically `rotate`) - Animated for open/close rotation transitions To customize this property, use the `animation` prop. To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`. #### SelectTriggerIndicatorIconProps | prop | type | default | description | | ------- | -------- | ------- | ------------------------------------------------------ | | `size` | `number` | `16` | Size of the icon | | `color` | `string` | - | Color of the icon (defaults to foreground theme color) | #### SelectTriggerIndicatorAnimation Animation configuration for Select.TriggerIndicator component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations (rotation from 0° to -180°) * `object`: Custom animation configuration | prop | type | default | description | | ----------------------- | ----------------------- | -------------------------------------------- | ----------------------------------------------- | | `state` | `'disabled' \| boolean` | - | Disable animations while customizing properties | | `rotation.value` | `[number, number]` | `[0, -180]` | Rotation values \[closed, open] in degrees | | `rotation.springConfig` | `WithSpringConfig` | `{ damping: 140, stiffness: 1000, mass: 4 }` | Spring animation configuration for rotation | ### Select.Portal | prop | type | default | description | | -------------------------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- | | `children` | `ReactNode` | - | The portal content (required) | | `disableFullWindowOverlay` | `boolean` | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; overlay won't appear above native modals | | `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 | | `isAnimatedStyleActive` | `boolean` | `true` | Whether animated styles (react-native-reanimated) are active | | `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 (progress-based opacity for bottom-sheet/dialog, Keyframe animations for popover) * `object`: Custom animation configuration | prop | type | default | description | | --------------- | -------------------------- | ----------- | ---------------------------------------------------------------------------- | | `state` | `'disabled' \| boolean` | - | Disable animations while customizing properties | | `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values \[idle, open, close] (for bottom-sheet/dialog presentation) | | `entering` | `EntryOrExitLayoutType` | - | Custom Keyframe animation for entering transition (for popover presentation) | | `exiting` | `EntryOrExitLayoutType` | - | Custom Keyframe animation for exiting transition (for popover presentation) | ### 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 Keyframe animations (translateY/translateX, scale, opacity based on placement) * `object`: Custom animation configuration with `entering` and/or `exiting` Keyframe animations | prop | type | default | description | | ---------- | ----------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `state` | `'disabled' \| boolean` | - | Disable animations while customizing properties | | `entering` | `EntryOrExitLayoutType` | - | Custom Keyframe animation for entering transition (default: Keyframe with translateY/translateX, scale, opacity based on placement, 200ms) | | `exiting` | `EntryOrExitLayoutType` | - | Custom Keyframe animation for exiting transition (default: Keyframe mirroring entering animation, 150ms) | ### Select.Content (Bottom Sheet Presentation) | prop | type | default | description | | --------------------------- | ------------------ | ------- | ------------------------------------------------ | | `children` | `ReactNode` | - | The bottom sheet content | | `presentation` | `'bottom-sheet'` | - | Presentation mode for the select | | `contentContainerClassName` | `string` | - | Additional CSS classes for the content container | | `...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 | | `styles` | `Partial>` | - | Styles for different parts of the dialog 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 | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | #### `styles` | prop | type | description | | --------- | ----------- | -------------------------------- | | `wrapper` | `ViewStyle` | Styles for the wrapper container | | `content` | `ViewStyle` | Styles for the dialog content | #### SelectContentAnimation Animation configuration for Select.Content component (dialog presentation). Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default Keyframe animations (scale and opacity transitions) * `object`: Custom animation configuration with `entering` and/or `exiting` Keyframe animations | prop | type | default | description | | ---------- | ----------------------- | ------- | -------------------------------------------------------------------------------------------------------- | | `state` | `'disabled' \| boolean` | - | Disable animations while customizing properties | | `entering` | `EntryOrExitLayoutType` | - | Custom Keyframe animation for entering transition (default: Keyframe with scale and opacity, 200ms) | | `exiting` | `EntryOrExitLayoutType` | - | Custom Keyframe animation for exiting transition (default: Keyframe mirroring entering animation, 150ms) | ### Select.Close Select.Close extends [CloseButton](./close-button) and automatically handles select dismissal when pressed. ### 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, presentation, triggerPosition, setTriggerPosition, contentLayout, setContentLayout, nativeID, 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 | | `presentation` | `'popover' \| 'bottom-sheet' \| 'dialog'` | Presentation mode for the select content | | `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 | | `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 | | ---------------------------------- | ---------------------- | ---------------------------------------------------------- | | `progress` | `SharedValue` | Progress value for animations (0=idle, 1=open, 2=close) | | `isDragging` | `SharedValue` | Whether the select content is currently being dragged | | `isGestureReleaseAnimationRunning` | `SharedValue` | 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 | ## Special Notes ### Element Inspector (iOS) Select uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set `disableFullWindowOverlay={true}` on `Select.Portal`. Tradeoff: the select dropdown will not appear above native modals when disabled. # 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**: 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 ``` ### With Custom Thumb Replace the default thumb with custom content using the Thumb component. ```tsx ... ``` ### With Start and End Content Add icons or text that appear on each side of the switch. ```tsx ... ... ``` ### With Render Function Use render functions for dynamic content based on switch state. ```tsx {({ isSelected, isDisabled }) => ( <> {({ isSelected }) => (isSelected ? : )} )} ``` ### With Custom Animations Customize animations for the switch root and thumb components. ```tsx ``` ### Disable Animations Disable animations entirely or only for specific components. ```tsx { /* Disable all animations including children */ } ; { /* Disable only root animations, thumb can still animate */ } ; ``` ## 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 ( {darkMode && ( )} {!darkMode && ( )} ); } ``` You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/switch.tsx). ## 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 | | `isAnimatedStyleActive` | `boolean` | `true` | Whether animated styles (react-native-reanimated) are active | | `onSelectedChange` | `(isSelected: boolean) => void` | - | Callback fired when the switch selection state changes | | `...AnimatedPressableProps` | `AnimatedProps` | - | 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: * `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 | | ------------------------------ | ---------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------- | | `state` | `'disabled' \| 'disable-all' \| boolean` | - | Disable animations while customizing properties | | `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 | | `isAnimatedStyleActive` | `boolean` | `true` | Whether animated styles (react-native-reanimated) are active | | `...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 | | ------------------------------ | ----------------------- | -------------------------------------------------------------- | ----------------------------------------------------------------------- | | `state` | `'disabled' \| boolean` | - | Disable animations while customizing properties | | `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 | 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 | ## 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 ( Status: {isSelected ? 'On' : 'Off'} {isDisabled && Disabled} ); } // Usage ; ``` ## 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 ``` Using `outline` keeps the border visual without impacting the switch's internal width calculations, ensuring the thumb animates correctly. ### Integration with ControlField The Switch component integrates seamlessly with ControlField for press state sharing: ```tsx import { Description, ControlField, Label } from 'heroui-native'; Enable notifications Receive push notifications ``` When wrapped in ControlField, the Switch will automatically respond to press events on the entire ControlField container, creating a larger touch target and better user experience. # TextArea **Category**: native **URL**: https://v3.heroui.com/docs/native/components/text-area **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/text-area.mdx > A multiline text input component with styled border and background for collecting longer user input. ## Import ```tsx import { TextArea } from 'heroui-native'; ``` ## Usage ### Basic Usage TextArea can be used standalone or within a TextField component. ```tsx import { TextArea } from 'heroui-native';

```

### Within TextField

TextArea works seamlessly with TextField for complete form structure.

```tsx
import { Description, Label, TextArea, TextField } from 'heroui-native';

<TextField>
  <Label>Message</Label>
  <TextArea placeholder="Enter your message here..." />
  <Description>Please provide as much detail as possible.</Description>
</TextField>

```

### With Validation

Display error state when the text area is invalid.

```tsx
import { FieldError, Label, TextArea, TextField } from 'heroui-native';

<TextField isRequired isInvalid={true}>
  <Label>Message</Label>
  <TextArea placeholder="Enter your message" />
  <FieldError>Please enter a valid message</FieldError>
</TextField>

```

### Disabled State

Disable the text area to prevent interaction.

```tsx
import { Label, TextArea, TextField } from 'heroui-native';

<TextField isDisabled>
  <Label>Disabled Field</Label>
  <TextArea placeholder="Cannot edit" value="Read only value" />
</TextField>

```

### With Variant

Use different variants to style the text area based on context.

```tsx
import { Label, TextArea, TextField } from 'heroui-native';

<TextField>
  <Label>Primary Variant</Label>
  <TextArea placeholder="Primary style text area" variant="primary" />
</TextField>

<TextField>
  <Label>Secondary Variant</Label>
  <TextArea placeholder="Secondary style text area" variant="secondary" />
</TextField>

```

### Custom Styling

Customize the text area appearance using className.

```tsx
import { Label, TextArea, TextField } from 'heroui-native';

<TextField>
  <Label>Custom Styled</Label>
  <TextArea
    placeholder="Custom colors"
    className="bg-blue-50 border-blue-500 focus:border-blue-700"
  />
</TextField>

```

## Example

```tsx
import { Description, FieldError, Label, TextArea, TextField } from 'heroui-native';
import { View } from 'react-native';

export default function TextAreaExample() {
  return (
    <View className="gap-8">
      <TextField>
        <Label>Primary Variant</Label>
        <TextArea placeholder="Primary style text area" variant="primary" />
        <Description>Default variant with primary styling</Description>
      </TextField>

<TextField>
        <Label>Secondary Variant</Label>
        <TextArea
          placeholder="Secondary style text area"
          variant="secondary"
        />
        <Description>Secondary variant for surfaces</Description>
      </TextField>
    </View>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/text-area.tsx).

## API Reference

TextArea extends [Input](./input) component and inherits all its props. The only differences are default values: `multiline` defaults to `true` and `textAlignVertical` defaults to `'top'`.

</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>
  <Label>...</Label>
  <Input />
  <Description>...</Description>
  <FieldError>...</FieldError>
</TextField>

```

* **TextField**: Root container that provides spacing and state management
* **Label**: Label with optional asterisk for required fields (from [Label](./label) component)
* **Input**: Input container with animated border and background (from [Input](./input) component)
* **Description**: Secondary descriptive helper text (from [Description](./description) component)
* **FieldError**: Validation error message display (from [FieldError](./field-error) component)

## Usage

### Basic Usage

TextField provides a complete form input structure with label and description.

```tsx
<TextField>
  <Label>Email</Label>
  <Input placeholder="Enter your email" />
  <Description>We'll never share your email</Description>
</TextField>

```

### With Required Field

Mark fields as required to show an asterisk in the label.

```tsx
<TextField isRequired>
  <Label>Username</Label>
  <Input placeholder="Choose a username" />
</TextField>

```

### With Validation

Display error messages when the field is invalid.

```tsx
import { FieldError, Input, Label, TextField } from 'heroui-native';

<TextField isRequired isInvalid={true}>
  <Label>Email</Label>
  <Input placeholder="Enter your email" />
  <FieldError>Please enter a valid email</FieldError>
</TextField>;

```

### With Local Invalid State Override

Override the context's invalid state for individual components.

```tsx
import {
  Description,
  FieldError,
  Input,
  Label,
  TextField,
} from 'heroui-native';

<TextField isInvalid={true}>
  <Label isInvalid={false}>Email</Label>
  <Input placeholder="Enter your email" isInvalid={false} />
  <Description isInvalid={false}>
    This shows despite input being invalid
  </Description>
  <FieldError>Email format is incorrect</FieldError>
</TextField>;

```

### Multiline Input

Create text areas for longer content.

```tsx
<TextField>
  <Label>Message</Label>
  <Input placeholder="Type your message..." multiline numberOfLines={4} />
  <Description>Maximum 500 characters</Description>
</TextField>

```

### Disabled State

Disable the entire field to prevent interaction.

```tsx
<TextField isDisabled>
  <Label>Disabled Field</Label>
  <Input placeholder="Cannot edit" value="Read only value" />
</TextField>

```

### With Variant

Use different variants to style the input based on context.

```tsx
<TextField>
  <Label>Primary Variant</Label>
  <Input placeholder="Primary style" variant="primary" />
</TextField>

<TextField>
  <Label>Secondary Variant</Label>
  <Input placeholder="Secondary style" variant="secondary" />
</TextField>

```

### Custom Styling

Customize the input appearance using className.

```tsx
<TextField>
  <Label>Custom Styled</Label>
  <Input
    placeholder="Custom colors"
    className="bg-blue-50 border-blue-500 focus:border-blue-700"
  />
</TextField>

```

## Example

```tsx
import { Ionicons } from '@expo/vector-icons';
import { Description, Input, Label, TextField } from 'heroui-native';
import { useState } from 'react';
import { Pressable, View } from 'react-native';
import { withUniwind } from 'uniwind';

const StyledIonicons = withUniwind(Ionicons);

export const TextInputContent = () => {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [isPasswordVisible, setIsPasswordVisible] = useState(false);

return (
    <View className="gap-4">
      <TextField isRequired>
        <Label>Email</Label>
        <Input
          placeholder="Enter your email"
          keyboardType="email-address"
          autoCapitalize="none"
          value={email}
          onChangeText={setEmail}
        />
        <Description>
          We'll never share your email with anyone else.
        </Description>
      </TextField>

<TextField isRequired>
        <Label>New password</Label>
        <View className="w-full flex-row items-center">
          <Input
            value={password}
            onChangeText={setPassword}
            className="flex-1 px-10"
            placeholder="Enter your password"
            secureTextEntry={!isPasswordVisible}
          />
          <StyledIonicons
            name="lock-closed-outline"
            size={16}
            className="absolute left-3.5 text-muted"
            pointerEvents="none"
          />
          <Pressable
            className="absolute right-4"
            onPress={() => setIsPasswordVisible(!isPasswordVisible)}
          >
            <StyledIonicons
              name={isPasswordVisible ? 'eye-off-outline' : 'eye-outline'}
              size={16}
              className="text-muted"
            />
          </Pressable>
        </View>
        <Description>Password must be at least 6 characters</Description>
      </TextField>
    </View>
  );
};

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/text-field.tsx).

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

> **Note**: For Label, Input, Description, and FieldError components, see their respective documentation:
>
> * [Label documentation](./label)
> * [Input documentation](./input)
> * [Description documentation](./description)
> * [FieldError documentation](./field-error)
>
> These components automatically consume form state from TextField via the form-item-state context.

## 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="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>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/card.tsx).

## API Reference

### Card

| prop           | type                                                      | default     | description                                                                               |
| -------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children`     | `React.ReactNode`                                         | -           | Content to be rendered inside the card                                                    |
| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| '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/separator">
# Separator

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/separator
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(layout)/separator.mdx
> A simple line to separate content visually.

## Import

```tsx
import { Separator } from "heroui-native";

```

## Anatomy

```tsx
<Separator />

```

* **Separator**: A simple line component that separates content visually. Can be oriented horizontally or vertically, with customizable thickness and variant styles.

## Usage

### Basic Usage

The Separator component creates a visual separation between content sections.

```tsx
<Separator />

```

### Orientation

Control the direction of the separator with the `orientation` prop.

```tsx
<View>
  <Text>Horizontal separator</Text>
  <Separator orientation="horizontal" />
  <Text>Content below</Text>
</View>

<View className="h-24 flex-row">
  <Text>Left</Text>
  <Separator orientation="vertical" />
  <Text>Right</Text>
</View>

```

### Variants

Choose between thin and thick variants for different visual emphasis.

```tsx
<Separator variant="thin" />
<Separator variant="thick" />

```

### Custom Thickness

Set a specific thickness value for precise control.

```tsx
<Separator thickness={1} />
<Separator thickness={5} />
<Separator thickness={10} />

```

## Example

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

export default function SeparatorExample() {
  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>
      <Separator className="my-4" />
      <View className="flex-row items-center h-5">
        <Text className="text-sm text-foreground">Components</Text>
        <Separator orientation="vertical" className="mx-3" />
        <Text className="text-sm text-foreground">Themes</Text>
        <Separator orientation="vertical" className="mx-3" />
        <Text className="text-sm text-foreground">Examples</Text>
      </View>
    </Surface>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/separator.tsx).

## API Reference

### Separator

| prop           | type                         | default        | description                                                                                  |
| -------------- | ---------------------------- | -------------- | -------------------------------------------------------------------------------------------- |
| `variant`      | `'thin' \| 'thick'`          | `'thin'`       | Variant style of the separator                                                               |
| `orientation`  | `'horizontal' \| 'vertical'` | `'horizontal'` | Orientation of the separator                                                                 |
| `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>
  </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>
    </View>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/surface.tsx).

## API Reference

### Surface

| prop           | type                                                      | default     | description                                                                               |
| -------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `variant`      | `'default' \| 'secondary' \| 'tertiary' \| '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>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/avatar.tsx).

## 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                                      |
| `isAnimatedStyleActive` | `boolean`                                      | `true`  | Whether animated styles (react-native-reanimated) are active |
| `...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                                           |
| ---------------------- | ----------------------- | --------------------------------------------------- | ----------------------------------------------------- |
| `state`                | `'disabled' \| boolean` | -                                                   | Disable animations while customizing properties       |
| `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                                        |
| `styles`                | `{ container?: ViewStyle; text?: TextStyle }`                 | -                     | Styles for different parts of the avatar fallback                                 |
| `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`.

#### `styles`

| prop        | type        | description                 |
| ----------- | ----------- | --------------------------- |
| `container` | `ViewStyle` | Styles for the container    |
| `text`      | `TextStyle` | Styles for the text content |

#### 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                                     |
| ---------------- | ----------------------- | -------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `state`          | `'disabled' \| boolean` | -                                                                                      | Disable animations while customizing properties |
| `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 Separators

Hide the separators between accordion items.

```tsx
<Accordion selectionMode="single" hideSeparator>
  <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>

```

### Custom Styling

Apply custom styles using className, classNames, or styles props.

```tsx
<Accordion
  className="rounded-lg"
  classNames={{
    container: 'bg-surface',
    separator: 'bg-separator/50',
  }}
  styles={{
    container: { padding: 16 },
    separator: { height: 2 },
  }}
>
  <Accordion.Item value="1">
    <Accordion.Trigger>...</Accordion.Trigger>
    <Accordion.Content>...</Accordion.Content>
  </Accordion.Item>
</Accordion>

```

### With PressableFeedback

Use `Accordion.Trigger` with `asChild` prop and wrap content with `PressableFeedback` to add custom press feedback animations.

```tsx
import { Accordion, PressableFeedback } from 'heroui-native';
import { View } from 'react-native';

<Accordion>
  <Accordion.Item value="1">
    <Accordion.Trigger asChild>
      <PressableFeedback>
        <View className="flex-row items-center flex-1 gap-3">
          <Text>Item Title</Text>
        </View>
        <Accordion.Indicator />
        <PressableFeedback.Highlight
          animation={{ opacity: { value: [0, 0.05] } }}
        />
      </PressableFeedback>
    </Accordion.Trigger>
    <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>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/accordion.tsx).

## 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                                |
| `hideSeparator`         | `boolean`                                          | `false`     | Whether to hide the separator between accordion items          |
| `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                           |
| `styles`                | `Partial<Record<RootSlots, ViewStyle>>`            | -           | Styles for different parts of the accordion root               |
| `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     |
| `separator` | `string` | Custom class name for the separator between items |

#### `styles`

| prop        | type        | description                            |
| ----------- | ----------- | -------------------------------------- |
| `container` | `ViewStyle` | Styles for the accordion container     |
| `separator` | `ViewStyle` | Styles for the separator between items |

#### AccordionRootAnimation

Animation configuration for accordion 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                                       |
| -------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
| `state`        | `'disabled' \| 'disable-all' \| boolean` | -                                                                                                   | Disable animations while customizing properties   |
| `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                                  |
| `isAnimatedStyleActive` | `boolean`                     | `true`  | Whether animated styles (react-native-reanimated) are active           |
| `...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                                       |
| ----------------------- | ----------------------- | -------------------------------------------- | ------------------------------------------------- |
| `state`                 | `'disabled' \| boolean` | -                                            | Disable animations while customizing properties   |
| `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                                     |
| ---------------- | ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------- |
| `state`          | `'disabled' \| boolean` | -                                                                      | Disable animations while customizing properties |
| `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.Separator />
      <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 (primary or secondary).
* **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.Separator**: Visual separator between tabs. Shows when the current tab value is not in the `betweenValues` array, with animated opacity transitions.
* **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>

```

### Primary Variant

Default rounded primary style for tab triggers.

```tsx
<Tabs value={activeTab} onValueChange={setActiveTab} variant="primary">
  <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>

```

### Secondary Variant

Underline style indicator for a more minimal appearance.

```tsx
<Tabs value={activeTab} onValueChange={setActiveTab} variant="secondary">
  <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>

```

### With Separators

Add visual separators between tabs that show when the active tab is not between specified values.

```tsx
<Tabs value={activeTab} onValueChange={setActiveTab}>
  <Tabs.List>
    <Tabs.ScrollView>
      <Tabs.Indicator />
      <Tabs.Trigger value="general">
        <Tabs.Label>General</Tabs.Label>
      </Tabs.Trigger>
      <Tabs.Separator betweenValues={['general', 'notifications']} />
      <Tabs.Trigger value="notifications">
        <Tabs.Label>Notifications</Tabs.Label>
      </Tabs.Trigger>
      <Tabs.Separator betweenValues={['notifications', 'profile']} />
      <Tabs.Trigger value="profile">
        <Tabs.Label>Profile</Tabs.Label>
      </Tabs.Trigger>
    </Tabs.ScrollView>
  </Tabs.List>
  <Tabs.Content value="general">...</Tabs.Content>
  <Tabs.Content value="notifications">...</Tabs.Content>
  <Tabs.Content value="profile">...</Tabs.Content>
</Tabs>

```

## Example

```tsx
import {
  Button,
  Checkbox,
  Description,
  ControlField,
  Label,
  Tabs,
  TextField,
} 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="primary">
      <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>
            <ControlField
              isSelected={showSidebar}
              onSelectedChange={setShowSidebar}
            >
              <ControlField.Indicator variant="checkbox" />
              <View className="flex-1">
                <Label>Show sidebar</Label>
                <Description>Display the sidebar navigation panel</Description>
              </View>
            </ControlField>
          </AnimatedContentContainer>
        </Tabs.Content>

<Tabs.Content value="notifications">
          <AnimatedContentContainer>
            <ControlField
              isSelected={accountActivity}
              onSelectedChange={setAccountActivity}
            >
              <ControlField.Indicator variant="checkbox" />
              <View className="flex-1">
                <Label>Account activity</Label>
                <Description>
                  Notifications about your account activity
                </Description>
              </View>
            </ControlField>
          </AnimatedContentContainer>
        </Tabs.Content>

<Tabs.Content value="profile">
          <AnimatedContentContainer>
            <TextField isRequired>
              <Label>Name</Label>
              <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>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/tabs.tsx).

## API Reference

### Tabs

| prop            | type                         | default     | description                                                                               |
| --------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- |
| `children`      | `React.ReactNode`            | -           | Children elements to be rendered inside tabs                                              |
| `value`         | `string`                     | -           | Currently active tab value                                                                |
| `variant`       | `'primary' \| 'secondary'`   | `'primary'` | 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

#### 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                                     |
| ------------------- | -------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------- |
| `state`             | `'disabled' \| boolean`                | -                                                                            | Disable animations while customizing properties |
| `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              |
| `translateX.type`   | `'spring' \| 'timing'`                 | `'spring'`                                                                   | Type of animation to use                        |
| `translateX.config` | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration              |

### Tabs.Separator

| prop                    | type                     | default | description                                                                                                                            |
| ----------------------- | ------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `betweenValues`         | `string[]`               | -       | Array of tab values between which the separator should be visible. The separator shows when the current tab value is NOT in this array |
| `isAlwaysVisible`       | `boolean`                | `false` | If true, opacity is always 1 regardless of the current tab value                                                                       |
| `className`             | `string`                 | -       | Additional CSS classes                                                                                                                 |
| `animation`             | `TabsSeparatorAnimation` | -       | Animation configuration                                                                                                                |
| `isAnimatedStyleActive` | `boolean`                | `true`  | Whether animated styles (react-native-reanimated) are active                                                                           |
| `children`              | `React.ReactNode`        | -       | Custom separator content                                                                                                               |
| `...Animated.ViewProps` | `Animated.ViewProps`     | -       | All Reanimated Animated.View props are supported                                                                                       |

**Note:** The following style properties are occupied by animations and cannot be set via className:

* `opacity` - Animated for separator visibility transitions (0 when current tab is in `betweenValues`, 1 when not)

To customize these properties, use the `animation` prop. To completely disable animated styles and use your own via className or style prop, set `isAnimatedStyleActive={false}`.

#### TabsSeparatorAnimation

Animation configuration for Tabs.Separator component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop                   | type                    | default             | description                                     |
| ---------------------- | ----------------------- | ------------------- | ----------------------------------------------- |
| `state`                | `'disabled' \| boolean` | -                   | Disable animations while customizing properties |
| `opacity.value`        | `[number, number]`      | `[0, 1]`            | Opacity values \[hidden, visible]               |
| `opacity.timingConfig` | `WithTimingConfig`      | `{ duration: 200 }` | Animation timing 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`         | `'primary' \| 'secondary'`                              | 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/bottom-sheet">
# Bottom Sheet

**Category**: native
**URL**: https://v3.heroui.com/docs/native/components/bottom-sheet
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(overlays)/bottom-sheet.mdx
> Displays a bottom sheet that slides up from the bottom with animated transitions and swipe-to-dismiss gestures.

## Import

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

```

## Anatomy

```tsx
<BottomSheet>
  <BottomSheet.Trigger>...</BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheet.Overlay>...</BottomSheet.Overlay>
    <BottomSheet.Content>
      <BottomSheet.Close />
      <BottomSheet.Title>...</BottomSheet.Title>
      <BottomSheet.Description>...</BottomSheet.Description>
    </BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>

```

* **BottomSheet**: Root component that manages open state and provides context to child components.
* **BottomSheet.Trigger**: Pressable element that opens the bottom sheet when pressed.
* **BottomSheet.Portal**: Renders bottom sheet content in a portal with full window overlay.
* **BottomSheet.Overlay**: Background overlay that covers the screen, typically closes bottom sheet when pressed.
* **BottomSheet.Content**: Main bottom sheet container using @gorhom/bottom-sheet for rendering with gesture support.
* **BottomSheet.Close**: Close button for the bottom sheet. Can accept custom children or uses default close icon.
* **BottomSheet.Title**: Bottom sheet title text with semantic heading role and accessibility linking.
* **BottomSheet.Description**: Bottom sheet description text that provides additional context with accessibility linking.

## Usage

### Basic Bottom Sheet

Simple bottom sheet with title, description, and close button.

```tsx
<BottomSheet>
  <BottomSheet.Trigger asChild>
    <Button>Open Bottom Sheet</Button>
  </BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheet.Overlay />
    <BottomSheet.Content>
      <BottomSheet.Close />
      <BottomSheet.Title>...</BottomSheet.Title>
      <BottomSheet.Description>...</BottomSheet.Description>
    </BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>

```

### Detached Bottom Sheet

Bottom sheet that appears detached from the bottom edge with custom spacing.

```tsx
<BottomSheet>
  <BottomSheet.Trigger>...</BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheet.Overlay />
    <BottomSheet.Content
      detached={true}
      bottomInset={insets.bottom + 12}
      className="mx-4"
      backgroundClassName="rounded-[32px]"
    >
      ...
    </BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>

```

### Scrollable with Snap Points

Bottom sheet with multiple snap points and scrollable content.

```tsx
<BottomSheet>
  <BottomSheet.Trigger>...</BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheet.Overlay />
    <BottomSheet.Content snapPoints={['25%', '50%', '90%']}>
      <ScrollView>...</ScrollView>
    </BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>

```

### Custom Overlay

Replace the default overlay with custom content like blur effects.

```tsx
import { useBottomSheet, useBottomSheetAnimation } from 'heroui-native';
import { StyleSheet, Pressable } from 'react-native';
import { interpolate, useDerivedValue } from 'react-native-reanimated';
import { AnimatedBlurView } from './animated-blur-view';
import { useUniwind } from 'uniwind';

export const BottomSheetBlurOverlay = () => {
  const { theme } = useUniwind();
  const { onOpenChange } = useBottomSheet();
  const { progress } = useBottomSheetAnimation();

const blurIntensity = useDerivedValue(() => {
    return interpolate(progress.get(), [0, 1, 2], [0, 40, 0]);
  });

return (
    <Pressable
      style={StyleSheet.absoluteFill}
      onPress={() => onOpenChange(false)}
    >
      <AnimatedBlurView
        blurIntensity={blurIntensity}
        tint={theme === 'dark' ? 'dark' : 'systemUltraThinMaterialDark'}
        style={StyleSheet.absoluteFill}
      />
    </Pressable>
  );
};

```

```tsx
<BottomSheet>
  <BottomSheet.Trigger>...</BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheetBlurOverlay />
    <BottomSheet.Content>...</BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>

```

## Example

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

const StyledIonicons = withUniwind(Ionicons);

export default function BottomSheetExample() {
  const [isOpen, setIsOpen] = useState(false);

return (
    <BottomSheet isOpen={isOpen} onOpenChange={setIsOpen}>
      <BottomSheet.Trigger asChild>
        <Button variant="secondary">Open Bottom Sheet</Button>
      </BottomSheet.Trigger>
      <BottomSheet.Portal>
        <BottomSheet.Overlay />
        <BottomSheet.Content>
          <View className="items-center mb-5">
            <View className="size-20 items-center justify-center rounded-full bg-green-500/10">
              <StyledIonicons
                name="shield-checkmark"
                size={40}
                className="text-green-500"
              />
            </View>
          </View>
          <View className="mb-8 gap-2 items-center">
            <BottomSheet.Title className="text-center">
              Keep yourself safe
            </BottomSheet.Title>
            <BottomSheet.Description className="text-center">
              Update your software to the latest version for better security and
              performance.
            </BottomSheet.Description>
          </View>
          <View className="gap-3">
            <Button onPress={() => setIsOpen(false)}>Update Now</Button>
            <Button variant="tertiary" onPress={() => setIsOpen(false)}>
              Later
            </Button>
          </View>
        </BottomSheet.Content>
      </BottomSheet.Portal>
    </BottomSheet>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/bottom-sheet.tsx).

## API Reference

### BottomSheet

| prop            | type                       | default | description                                        |
| --------------- | -------------------------- | ------- | -------------------------------------------------- |
| `children`      | `React.ReactNode`          | -       | Bottom sheet content and trigger elements          |
| `isOpen`        | `boolean`                  | -       | Controlled open state of the bottom sheet          |
| `isDefaultOpen` | `boolean`                  | `false` | Initial open state when uncontrolled               |
| `animation`     | `AnimationRootDisableAll`  | -       | Animation configuration                            |
| `onOpenChange`  | `(value: boolean) => void` | -       | Callback when open state changes                   |
| `...ViewProps`  | `ViewProps`                | -       | All standard React Native View props are supported |

#### Animation Configuration

Animation configuration for bottom sheet root component. Can be:

* `"disable-all"`: Disable all animations including children
* `undefined`: Use default animations

### BottomSheet.Trigger

| prop                       | type                    | default | description                                                    |
| -------------------------- | ----------------------- | ------- | -------------------------------------------------------------- |
| `children`                 | `React.ReactNode`       | -       | Trigger element content                                        |
| `asChild`                  | `boolean`               | -       | Render as child element without wrapper                        |
| `...TouchableOpacityProps` | `TouchableOpacityProps` | -       | All standard React Native TouchableOpacity props are supported |

### BottomSheet.Portal

| prop                       | type                   | default | description                                                                                                                   |
| -------------------------- | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `children`                 | `React.ReactNode`      | -       | Portal content (overlay and bottom sheet)                                                                                     |
| `disableFullWindowOverlay` | `boolean`              | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; overlay won't appear above native modals |
| `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                                                                                |

### BottomSheet.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`             | `Omit<PopupOverlayAnimation, 'entering' \| 'exiting'>` | -       | Animation configuration                                      |
| `isAnimatedStyleActive` | `boolean`                                              | `true`  | Whether animated styles (react-native-reanimated) are active |
| `isCloseOnPress`        | `boolean`                                              | `true`  | Whether pressing overlay closes bottom sheet                 |
| `...PressableProps`     | `PressableProps`                                       | -       | All standard React Native Pressable props are supported      |

#### Animation Configuration

Animation configuration for bottom sheet overlay component. Can be:

* `false` or `"disabled"`: Disable all animations
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration (excluding `entering` and `exiting` properties)

| prop            | type                       | default     | description                                     |
| --------------- | -------------------------- | ----------- | ----------------------------------------------- |
| `state`         | `'disabled' \| boolean`    | -           | Disable animations while customizing properties |
| `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values \[idle, open, close]             |

### BottomSheet.Content

| prop                        | type                                     | default | description                                                                                        |
| --------------------------- | ---------------------------------------- | ------- | -------------------------------------------------------------------------------------------------- |
| `children`                  | `React.ReactNode`                        | -       | Bottom sheet content                                                                               |
| `className`                 | `string`                                 | -       | Additional CSS classes for bottom sheet container                                                  |
| `containerClassName`        | `string`                                 | -       | Additional CSS classes for container                                                               |
| `contentContainerClassName` | `string`                                 | -       | Additional CSS classes for content container                                                       |
| `backgroundClassName`       | `string`                                 | -       | Additional CSS classes for background                                                              |
| `handleClassName`           | `string`                                 | -       | Additional CSS classes for handle                                                                  |
| `handleIndicatorClassName`  | `string`                                 | -       | Additional CSS classes for handle indicator                                                        |
| `contentContainerProps`     | `Omit<BottomSheetViewProps, 'children'>` | -       | Props for the content container                                                                    |
| `animation`                 | `AnimationDisabled`                      | -       | Animation configuration                                                                            |
| `...GorhomBottomSheetProps` | `Partial<GorhomBottomSheetProps>`        | -       | All [@gorhom/bottom-sheet props](https://gorhom.dev/react-native-bottom-sheet/props) are supported |

**Note**: You can use all components from [@gorhom/bottom-sheet](https://gorhom.dev/react-native-bottom-sheet/components/bottomsheetview) inside the content, such as `BottomSheetView`, `BottomSheetScrollView`, `BottomSheetFlatList`, etc.

### BottomSheet.Close

BottomSheet.Close extends [CloseButton](./close-button) and automatically handles bottom sheet dismissal when pressed.

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

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

### useBottomSheet

Hook to access bottom sheet primitive context.

```tsx
const { isOpen, onOpenChange } = useBottomSheet();

```

| property       | type                       | description                   |
| -------------- | -------------------------- | ----------------------------- |
| `isOpen`       | `boolean`                  | Current open state            |
| `onOpenChange` | `(value: boolean) => void` | Function to change open state |

### useBottomSheetAnimation

Hook to access bottom sheet animation context for advanced customization.

```tsx
const { progress } = useBottomSheetAnimation();

```

| property   | type                  | description                                  |
| ---------- | --------------------- | -------------------------------------------- |
| `progress` | `SharedValue<number>` | Animation progress (0=idle, 1=open, 2=close) |

## Special Notes

### Element Inspector (iOS)

BottomSheet uses FullWindowOverlay on iOS, which renders in a separate native window. This breaks the React Native element inspector. To enable the inspector during development, set `disableFullWindowOverlay={true}` on `BottomSheet.Portal`. Tradeoff: the bottom sheet will not appear above native modals when disabled.

### Handling Close Callbacks

It's recommended to use `BottomSheet`'s `onOpenChange` prop for handling close callbacks, as it reliably fires for all close scenarios (swiping down, pressing overlay, pressing close button, programmatic close, etc.).

```tsx
<BottomSheet
  isOpen={isOpen}
  onOpenChange={(value) => {
    setIsOpen(value);
    if (!value) {
      // This callback runs whenever the bottom sheet closes
      // regardless of how it was closed
      yourCallbackOnClose();
    }
  }}
>
  ...
</BottomSheet>

```

**Note**: `BottomSheet.Content`'s `onClose` prop (from @gorhom/bottom-sheet) has limitations and will only fire when the bottom sheet is closed by swiping down. It won't fire when closing via overlay press, close button, or programmatic close. For reliable close callbacks, always use `BottomSheet`'s `onOpenChange` prop instead.

</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 } 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 for the dialog. Can accept custom children or uses default close icon.
* **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>

```

### 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 variant="ghost" />
          <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">
            <Button variant="ghost" size="sm" onPress={() => setIsOpen(false)}>
              Cancel
            </Button>
            <Button size="sm">Confirm</Button>
          </View>
        </Dialog.Content>
      </Dialog.Portal>
    </Dialog>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/dialog.tsx).

## 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               |
| `animation`     | `AnimationRootDisableAll`  | -       | Animation configuration                            |
| `onOpenChange`  | `(value: boolean) => void` | -       | Callback when open state changes                   |
| `...ViewProps`  | `ViewProps`                | -       | All standard React Native View props are supported |

#### AnimationRootDisableAll

Animation configuration for dialog root component. Can be:

* `false` or `"disabled"`: Disable only root animations
* `"disable-all"`: Disable all animations including children
* `true` or `undefined`: Use default animations

### Dialog.Trigger

### Dialog.Portal

| prop                       | type                   | default | description                                                                                                                   |
| -------------------------- | ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `children`                 | `React.ReactNode`      | -       | Portal content (overlay and dialog)                                                                                           |
| `disableFullWindowOverlay` | `boolean`              | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; overlay won't appear above native modals |
| `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                                      |
| `isAnimatedStyleActive` | `boolean`                | `true`  | Whether animated styles (react-native-reanimated) are active |
| `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

| prop            | type                       | default                 | description                                                                   |
| --------------- | -------------------------- | ----------------------- | ----------------------------------------------------------------------------- |
| `state`         | `'disabled' \| boolean`    | -                       | Disable animations while customizing properties                               |
| `opacity.value` | `[number, number, number]` | `[0, 1, 0]`             | Opacity values \[idle, open, close] (progress-based, for dialog presentation) |
| `entering`      | `EntryOrExitLayoutType`    | `FadeIn.duration(200)`  | Custom entering animation (for popover presentation)                          |
| `exiting`       | `EntryOrExitLayoutType`    | `FadeOut.duration(150)` | Custom exiting animation (for popover presentation)                           |

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

| prop       | type                    | default                                                                                     | description                                     |
| ---------- | ----------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| `state`    | `'disabled' \| boolean` | -                                                                                           | Disable animations while customizing properties |
| `entering` | `EntryOrExitLayoutType` | Keyframe with `scale: 0.96→1` and `opacity: 0→1` (200ms, easing: `Easing.out(Easing.ease)`) | Custom entering animation                       |
| `exiting`  | `EntryOrExitLayoutType` | Keyframe with `scale: 1→0.96` and `opacity: 1→0` (150ms, easing: `Easing.in(Easing.ease)`)  | Custom exiting animation                        |

### Dialog.Close

Dialog.Close extends [CloseButton](./close-button) and automatically handles dialog dismissal when pressed.

### 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();

```

### useDialogAnimation

Hook to access dialog animation context for advanced customization.

```tsx
const { progress, isDragging, isGestureReleaseAnimationRunning } =
  useDialogAnimation();

```

| property                           | type                   | description                                  |
| ---------------------------------- | ---------------------- | -------------------------------------------- |
| `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 |

## Special Notes

### Element Inspector (iOS)

Dialog uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set `disableFullWindowOverlay={true}` on `Dialog.Portal`. Tradeoff: the dialog will not appear above native modals when disabled.

</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 for the popover. Can accept custom children or uses default close icon.
* **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 presentation="popover">...</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 presentation="popover">
      <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 presentation="popover" placement="top">
      <Popover.Arrow />
      ...
    </Popover.Content>
  </Popover.Portal>
</Popover>

```

> **Note:** When using `<Popover.Arrow />`, you need to apply a border to `Popover.Content`, for instance using the `border border-border` class. This ensures the arrow visually connects properly with the content border.

### 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 presentation="popover" width={320}>
      ...
    </Popover.Content>
  </Popover.Portal>
</Popover>;

{
  /* Match trigger width */
}
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content presentation="popover" width="trigger">
      ...
    </Popover.Content>
  </Popover.Portal>
</Popover>;

{
  /* Full width (100%) */
}
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content presentation="popover" width="full">
      ...
    </Popover.Content>
  </Popover.Portal>
</Popover>;

{
  /* Auto-size to content (default) */
}
<Popover>
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content presentation="popover" width="content-fit">
      ...
    </Popover.Content>
  </Popover.Portal>
</Popover>;

```

### Bottom Sheet Presentation

Use bottom sheet presentation for mobile-optimized interaction patterns.

> **Important:** The `presentation` prop on `Popover.Content` must match the `presentation` prop on `Popover.Root`. In development mode, a mismatch will throw an error.

```tsx
<Popover presentation="bottom-sheet">
  <Popover.Trigger>...</Popover.Trigger>
  <Popover.Portal>
    <Popover.Overlay />
    <Popover.Content presentation="bottom-sheet">
      <Popover.Title>...</Popover.Title>
      <Popover.Description>...</Popover.Description>
      <Button>Close</Button>
    </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 presentation="popover" 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 presentation="popover" 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 presentation="popover">...</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 presentation="popover">
      <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
          presentation="popover"
          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>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/popover.tsx).

## 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                                                   |
| `animation`     | `AnimationRootDisableAll`     | -           | Animation configuration. Can be `false`, `"disabled"`, `"disable-all"`, `true`, or `undefined` |
| `presentation`  | `'popover' \| 'bottom-sheet'` | `'popover'` | Presentation mode for the popover content                                                      |
| `asChild`       | `boolean`                     | `false`     | Whether to render as a child element                                                           |
| `...ViewProps`  | `ViewProps`                   | -           | All standard React Native View props are supported                                             |

#### AnimationRootDisableAll

Animation configuration for popover root component. Can be:

* `false` or `"disabled"`: Disable only root animations
* `"disable-all"`: Disable all animations including children
* `true` or `undefined`: Use default animations

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

### Popover.Portal

| prop                       | type        | default | description                                                                                                                   |
| -------------------------- | ----------- | ------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `children`                 | `ReactNode` | -       | The portal content (required)                                                                                                 |
| `disableFullWindowOverlay` | `boolean`   | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; overlay won't appear above native modals |
| `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                                      |
| `isAnimatedStyleActive` | `boolean`                 | `true`  | Whether animated styles (react-native-reanimated) are active |
| `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

| prop            | type                       | default                     | description                                                                               |
| --------------- | -------------------------- | --------------------------- | ----------------------------------------------------------------------------------------- |
| `state`         | `'disabled' \| boolean`    | -                           | Disable animations while customizing properties                                           |
| `opacity.value` | `[number, number, number]` | `[0, 1, 0]`                 | Opacity values \[idle, open, close] - Takes effect for bottom-sheet/dialog presentation   |
| `entering`      | `EntryOrExitLayoutType`    | FadeIn with duration 200ms  | Custom Keyframe animation for entering transition - Takes effect for popover presentation |
| `exiting`       | `EntryOrExitLayoutType`    | FadeOut with duration 150ms | Custom Keyframe animation for exiting transition - Takes effect for popover presentation  |

### Popover.Content (Popover Presentation)

| prop                      | type                                             | default         | description                                                                                             |
| ------------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------- |
| `children`                | `ReactNode`                                      | -               | The popover content                                                                                     |
| `presentation`            | `'popover'`                                      | `'popover'`     | Presentation mode - must match Popover.Root presentation prop. When not provided, defaults to 'popover' |
| `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`                                         | `9`             | 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                                                        |
| `animation`               | `PopupPopoverContentAnimation`                   | -               | Animation configuration                                                                                 |
| `isAnimatedStyleActive`   | `boolean`                                        | `true`          | Whether animated styles (react-native-reanimated) are active                                            |
| `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 - must be 'bottom-sheet' and match Popover.Root presentation prop (required) |
| `contentContainerClassName` | `string`               | -       | Additional CSS classes for the content container                                               |
| `contentContainerProps`     | `BottomSheetViewProps` | -       | Props for the content container                                                                |
| `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                                       |
| ---------- | ----------------------- | --------------------------------------------------------------- | ------------------------------------------------- |
| `state`    | `'disabled' \| boolean` | -                                                               | Disable animations while customizing properties   |
| `entering` | `EntryOrExitLayoutType` | Keyframe with translateY/translateX, scale, and opacity (200ms) | Custom Keyframe animation for entering transition |
| `exiting`  | `EntryOrExitLayoutType` | Keyframe mirroring entering animation (150ms)                   | Custom Keyframe animation for exiting transition  |

### Popover.Arrow

| prop                  | type                                     | default | description                                                           |
| --------------------- | ---------------------------------------- | ------- | --------------------------------------------------------------------- |
| `className`           | `string`                                 | -       | Additional CSS classes for the arrow                                  |
| `height`              | `number`                                 | `12`    | Height of the arrow in pixels                                         |
| `width`               | `number`                                 | `20`    | 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

Popover.Close extends [CloseButton](./close-button) and automatically handles popover dismissal when pressed.

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

**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 { progress, isDragging } = usePopoverAnimation();
  // ... your implementation
};

```

**Returns:** `UsePopoverAnimationReturn`

| property     | type                   | description                                                        |
| ------------ | ---------------------- | ------------------------------------------------------------------ |
| `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.

## Special Notes

### Element Inspector (iOS)

Popover uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set `disableFullWindowOverlay={true}` on `Popover.Portal`. Tradeoff: the popover will not appear above native modals when disabled.

</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>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/toast.tsx).

## 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                                                   |
| `isAnimatedStyleActive` | `boolean`                                                     | `true`      | Whether animated styles (react-native-reanimated) are active              |
| `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                                                                      |
| ------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| `state`                   | `'disabled' \| 'disable-all' \| boolean` | -                                                                                                                            | Disable animations while customizing properties                                  |
| `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                                                                   |
| `disableFullWindowOverlay` | `boolean`                                           | `false` | When true on iOS, uses View instead of FullWindowOverlay. Enables element inspector; toasts won't appear above native modals |
| `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

### Element Inspector (iOS)

Toast uses FullWindowOverlay on iOS. To enable the React Native element inspector during development, set `disableFullWindowOverlay={true}` on `ToastProvider` (via `config.toast` when using HeroUINativeProvider). Tradeoff: toasts will not appear above native modals when disabled.

</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 Effect

Add a highlight overlay component for iOS-style feedback effect. The highlight uses the root's press state from context.

```tsx
<PressableFeedback>
  <PressableFeedback.Highlight />
  ...
</PressableFeedback>

```

### Ripple Effect

Add a ripple overlay component for Android-style feedback effect that emanates from the press point.

```tsx
<PressableFeedback>
  <PressableFeedback.Ripple />
  ...
</PressableFeedback>

```

### Custom Scale Animation

Customize or disable the default scale animation on press.

```tsx
<PressableFeedback
  animation={{
    scale: {
      value: 0.9,
      timingConfig: { duration: 150 },
    },
  }}
>
  ...
</PressableFeedback>

```

### Custom Highlight Animation

Configure highlight overlay opacity and background color.

```tsx
<PressableFeedback>
  <PressableFeedback.Highlight
    animation={{
      opacity: { value: [0, 0.2] },
      backgroundColor: { value: '#3b82f6' },
    }}
  />
  ...
</PressableFeedback>

```

### Custom Ripple Animation

Configure ripple effect color, opacity, and duration.

```tsx
<PressableFeedback>
  <PressableFeedback.Ripple
    animation={{
      backgroundColor: { value: '#ec4899' },
      opacity: { value: [0, 0.1, 0] },
      progress: { baseDuration: 600 },
    }}
  />
  ...
</PressableFeedback>

```

## Example

```tsx
import { PressableFeedback, Card, Button } from 'heroui-native';
import { Image } from 'expo-image';
import { LinearGradient } from 'expo-linear-gradient';
import { StyleSheet, View } from 'react-native';

export default function PressableFeedbackExample() {
  return (
    <PressableFeedback className="w-full aspect-square rounded-3xl">
      <Card className="flex-1">
        <Image
          source={{
            uri: 'https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo2.jpeg',
          }}
          style={StyleSheet.absoluteFill}
          contentFit="cover"
        />
        <LinearGradient
          colors={['rgba(0,0,0,0.1)', 'rgba(0,0,0,0.4)']}
          style={StyleSheet.absoluteFill}
        />
        <PressableFeedback.Ripple
          animation={{
            backgroundColor: { value: 'white' },
            opacity: { value: [0, 0.3, 0] },
          }}
        />
        <View className="flex-1 gap-4" pointerEvents="box-none">
          <Card.Body className="flex-1" pointerEvents="none">
            <Card.Title className="text-base text-zinc-50 uppercase mb-0.5">
              Neo
            </Card.Title>
            <Card.Description className="text-zinc-50 font-medium text-base">
              Home robot
            </Card.Description>
          </Card.Body>
          <Card.Footer className="gap-3">
            <View className="flex-row items-center justify-between">
              <View pointerEvents="none">
                <Text className="text-base text-white">Available soon</Text>
                <Text className="text-base text-zinc-300">Get notified</Text>
              </View>
              <Button size="sm" className="bg-white">
                <Button.Label className="text-black">Notify me</Button.Label>
              </Button>
            </View>
          </Card.Footer>
        </View>
      </Card>
    </PressableFeedback>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/pressable-feedback.tsx).

## API Reference

### PressableFeedback

| prop                    | type                             | default | description                                                  |
| ----------------------- | -------------------------------- | ------- | ------------------------------------------------------------ |
| `children`              | `React.ReactNode`                | -       | Content to be wrapped with press feedback                    |
| `isDisabled`            | `boolean`                        | `false` | Whether the pressable component is disabled                  |
| `className`             | `string`                         | -       | Additional CSS classes                                       |
| `animation`             | `PressableFeedbackRootAnimation` | -       | Animation configuration for scale animation only             |
| `isAnimatedStyleActive` | `boolean`                        | `true`  | Whether animated styles (react-native-reanimated) are active |
| `...AnimatedProps`      | `AnimatedProps<PressableProps>`  | -       | All Reanimated Animated Pressable props are supported        |

#### PressableFeedbackRootAnimation

Animation configuration for PressableFeedback root component (scale only). Can be:

| prop                           | type                                     | default                                              | description                                                                |
| ------------------------------ | ---------------------------------------- | ---------------------------------------------------- | -------------------------------------------------------------------------- |
| `state`                        | `'disabled' \| 'disable-all' \| boolean` | -                                                    | Disable animations while customizing properties                            |
| `scale.value`                  | `number`                                 | `0.985`                                              | Scale value when pressed (automatically adjusted based on container width) |
| `scale.timingConfig`           | `WithTimingConfig`                       | `{ duration: 300, easing: Easing.out(Easing.ease) }` | Animation timing configuration                                             |
| `scale.ignoreScaleCoefficient` | `boolean`                                | `false`                                              | Ignore automatic scale coefficient and use the scale value directly        |

### PressableFeedback.Highlight

| prop                    | type                                  | default | description                                                  |
| ----------------------- | ------------------------------------- | ------- | ------------------------------------------------------------ |
| `className`             | `string`                              | -       | Additional CSS classes                                       |
| `animation`             | `PressableFeedbackHighlightAnimation` | -       | Animation configuration for highlight overlay                |
| `isAnimatedStyleActive` | `boolean`                             | `true`  | Whether animated styles (react-native-reanimated) are active |
| `style`                 | `ViewStyle`                           | -       | Additional styles                                            |
| `...AnimatedProps`      | `AnimatedProps<ViewProps>`            | -       | All Reanimated Animated View props are supported             |

#### PressableFeedbackHighlightAnimation

Animation configuration for highlight overlay. Can be:

* `false` or `"disabled"`: Disable highlight animations
* `"disable-all"`: Disable all animations including children
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop                    | type                    | default             | description                                     |
| ----------------------- | ----------------------- | ------------------- | ----------------------------------------------- |
| `state`                 | `'disabled' \| boolean` | -                   | Disable animations while customizing properties |
| `opacity.value`         | `[number, number]`      | `[0, 0.1]`          | Opacity values \[unpressed, pressed]            |
| `opacity.timingConfig`  | `WithTimingConfig`      | `{ duration: 200 }` | Animation timing configuration                  |
| `backgroundColor.value` | `string`                | Theme-aware gray    | Background color of highlight overlay           |

### PressableFeedback.Ripple

| prop                    | type                                      | default | description                                                  |
| ----------------------- | ----------------------------------------- | ------- | ------------------------------------------------------------ |
| `className`             | `string`                                  | -       | Additional CSS classes for container slot                    |
| `classNames`            | `ElementSlots<RippleSlots>`               | -       | Additional CSS classes for slots (container, ripple)         |
| `styles`                | `Partial<Record<RippleSlots, ViewStyle>>` | -       | Styles for different parts of the ripple overlay             |
| `animation`             | `PressableFeedbackRippleAnimation`        | -       | Animation configuration for ripple overlay                   |
| `isAnimatedStyleActive` | `boolean`                                 | `true`  | Whether animated styles (react-native-reanimated) are active |
| `...ViewProps`          | `Omit<ViewProps, 'style'>`                | -       | All View props except style are supported                    |

#### `styles`

| prop        | type        | description                   |
| ----------- | ----------- | ----------------------------- |
| `container` | `ViewStyle` | Styles for the container slot |
| `ripple`    | `ViewStyle` | Styles for the ripple slot    |

#### PressableFeedbackRippleAnimation

Animation configuration for ripple overlay. Can be:

* `false` or `"disabled"`: Disable ripple animations
* `"disable-all"`: Disable all animations including children
* `true` or `undefined`: Use default animations
* `object`: Custom animation configuration

| prop                                 | type                       | default                 | description                                                                  |
| ------------------------------------ | -------------------------- | ----------------------- | ---------------------------------------------------------------------------- |
| `state`                              | `'disabled' \| boolean`    | -                       | Disable animations while customizing properties                              |
| `backgroundColor.value`              | `string`                   | Computed based on theme | Background color of ripple effect                                            |
| `progress.baseDuration`              | `number`                   | `1000`                  | Base duration for ripple progress (automatically adjusted based on diagonal) |
| `progress.minBaseDuration`           | `number`                   | `750`                   | Minimum base duration for the ripple progress animation                      |
| `progress.ignoreDurationCoefficient` | `boolean`                  | `false`                 | Ignore automatic duration coefficient and use base duration directly         |
| `opacity.value`                      | `[number, number, number]` | `[0, 0.1, 0]`           | Opacity values \[start, peak, end] for ripple animation                      |
| `opacity.timingConfig`               | `WithTimingConfig`         | `{ duration: 200 }`     | Animation timing configuration                                               |
| `scale.value`                        | `[number, number, number]` | `[0, 1, 1]`             | Scale values \[start, peak, end] for ripple animation                        |
| `scale.timingConfig`                 | `WithTimingConfig`         | `{ duration: 200 }`     | Animation timing configuration                                               |

#### `ElementSlots<RippleSlots>`

Additional CSS classes for ripple slots:

| slot        | description                                                                                                         |
| ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `container` | Outer container slot (`absolute inset-0`) - styles can be fully customized                                          |
| `ripple`    | Inner ripple slot (`absolute top-0 left-0 rounded-full`) - has animated properties that cannot be set via className |

</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>
  );
}

```

You can find more examples in the [GitHub repository](https://github.com/heroui-inc/heroui-native/blob/rc/example/src/app/$home$/components/scroll-shadow.tsx).

## 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                                                                          |
| --------------- | ---------------------------------------- | -------- | ------------------------------------------------------------------------------------ |
| `state`         | `'disabled' \| 'disable-all' \| boolean` | -        | Disable animations while customizing properties                                      |
| `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

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

```

### 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">Outline</p>
        <ButtonGroup variant="outline">
          <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
* **Only direct child buttons receive the ButtonGroup props** - Buttons nested inside other components (like Modal, Dropdown, etc.) will not inherit the group's props even if they are descendants of the ButtonGroup
* 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="outline">Outline</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="outline">
        Outline
      </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>
  );
}

```

### Custom Render Function

```tsx
"use client";

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

export function CustomRenderFunction() {
  return (
    <Button
      render={(props, {isPressed}) => (
        <button {...props} data-custom={isPressed ? "pressed" : "bar"} />
      )}
    >
      Press me
    </Button>
  );
}

```

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

```

### Adding Ripple Effect

The Button component supports ripple effects through composition, allowing you to nest ripple components as children. This example uses [m3-ripple](https://github.com/saltyaom/m3-ripple).

```tsx
"use client";

import {Button} from "@heroui/react";
import {Ripple} from "m3-ripple";

import "m3-ripple/ripple.css";

export function RippleEffect() {
  return (
    <Button variant="secondary">
      <Ripple />
      Click me
    </Button>
  );
}

```

### 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--outline`
* `.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' \| 'outline' \| '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                                    |
| `render`     | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ButtonRenderProps>`    | -           | Overrides the default DOM element with a custom render function. |

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

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>
  );
}

```

### 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/list-box">
# ListBox

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/list-box
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(collections)/list-box.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";

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>
  );
}

```

### 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>
  );
}

```

### Custom Render Function

```tsx
"use client";

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

export function CustomRenderFunction() {
  return (
    <ListBox
      aria-label="Users"
      className="w-[220px]"
      render={(props) => <div {...props} data-custom="true" />}
      selectionMode="single"
    >
      <ListBox.Item
        id="1"
        render={(props) => <span {...props} data-custom="foo" />}
        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"
        render={(props) => <span {...props} data-custom="bar" />}
        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"
        render={(props) => <span {...props} data-custom="baz" />}
        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>
  );
}

```

## 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 {
  .list-box {
    @apply rounded-lg border border-border bg-surface p-2;
  }

.list-box-item {
    @apply rounded px-2 py-1 cursor-pointer;
  }

.list-box-item--danger {
    @apply text-danger;
  }

.list-box-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/list-box.css)):

#### Base Classes

* `.list-box` - Base listbox container
* `.list-box-item` - Individual listbox item
* `.list-box-item__indicator` - Selection indicator icon
* `.list-box-section` - Section container for grouping items

#### Variant Classes

* `.list-box--default` - Default variant styling
* `.list-box--danger` - Danger variant styling
* `.list-box-item--default` - Default item variant
* `.list-box-item--danger` - Danger item variant

#### State Classes

* `.list-box-item[data-selected="true"]` - Selected item state
* `.list-box-item[data-focus-visible="true"]` - Focused item state
* `.list-box-item[data-disabled="true"]` - Disabled item state
* `.list-box-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                                       |
| `render`              | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ListBoxRenderProps>` | -           | Overrides the default DOM element with a custom render function. |

### 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                                  |
| `render`     | `(props: DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> \| React.JSX.IntrinsicElements[keyof React.JSX.IntrinsicElements], renderProps: ListBoxItemRenderProps) => ReactElement` | -           | Overrides the default DOM element with a custom 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";

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>
  );
}

```

### 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 {Label, Tag, TagGroup} from "@heroui/react";

export function TagGroupVariants() {
  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>
  );
}

```

### 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>
  );
}

```

### Custom Render Function

```tsx
"use client";

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

export function CustomRenderFunction() {
  return (
    <TagGroup
      aria-label="Tags"
      render={(props) => <div {...props} data-custom="foo" />}
      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>
  );
}

```

## 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
* `.tag--surface` - Surface variant with surface background

#### 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"`                                          | `"default"` | Visual variant of the tags                                       |
| `className`           | `string`                                                          | -           | Additional CSS classes                                           |
| `children`            | `ReactNode \| RenderFunction`                                     | -           | TagGroup content or render function                              |
| `render`              | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | -           | Overrides the default DOM element with a custom 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                               |
| `render`           | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagListRenderProps>` | -       | Overrides the default DOM element with a custom 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                                       |
| `render`     | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagRenderProps>` | -       | Overrides the default DOM element with a custom render function.     |

**Note**: `size`, `variant` 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) |

**Note**: The `Tag.RemoveButton` component supports customization similar to `SearchField.ClearButton`. When `onRemove` is provided to `TagGroup`:

* **Auto-rendering**: If no custom `Tag.RemoveButton` is included in the `Tag` children, a default remove button is automatically rendered.
* **Custom button**: If a custom `Tag.RemoveButton` is provided as a child of `Tag`, it will be used instead of the auto-rendered button.
* **Custom icon**: You can pass custom content (like icons) to `Tag.RemoveButton` children to customize the appearance.

**Example - Auto-rendered (default)**:

```tsx
<TagGroup onRemove={handleRemove}>
  <TagGroup.List>
    <Tag id="news">News</Tag>
    {/* Remove button is automatically rendered */}
  </TagGroup.List>
</TagGroup>

```

**Example - Custom RemoveButton with icon**:

```tsx
<TagGroup onRemove={handleRemove}>
  <TagGroup.List>
    <Tag id="news">
      News
      <Tag.RemoveButton>
        <CustomIcon />
      </Tag.RemoveButton>
    </Tag>
  </TagGroup.List>
</TagGroup>

```

**Example - Custom RemoveButton in render props**:

```tsx
<Tag id="news">
  {(renderProps) => (
    <>
      News
      {!!renderProps.allowsRemoving && (
        <Tag.RemoveButton>
          <CustomIcon />
        </Tag.RemoveButton>
      )}
    </>
  )}
</Tag>

```

### 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/color-area">
# ColorArea

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/color-area
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-area.mdx
> A 2D color picker that allows users to select colors from a gradient area

## Import

```tsx
import { ColorArea } from '@heroui/react';

```

### Usage

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

export function ColorAreaBasic() {
  return (
    <ColorArea defaultValue="rgb(116, 52, 255)">
      <ColorArea.Thumb />
    </ColorArea>
  );
}

```

### Anatomy

```tsx
import { ColorArea } from '@heroui/react';

export default () => (
  <ColorArea>
    <ColorArea.Thumb />
  </ColorArea>
);

```

### With Dots

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

export function ColorAreaWithDots() {
  return (
    <ColorArea showDots defaultValue="hsl(200, 100%, 50%)">
      <ColorArea.Thumb />
    </ColorArea>
  );
}

```

### Controlled

```tsx
"use client";

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

import {ColorArea, ColorSwatch, parseColor} from "@heroui/react";
import {useState} from "react";

export function ColorAreaControlled() {
  const [color, setColor] = useState<Color>(parseColor("#9B80FF"));

return (
    <div className="flex flex-col gap-4">
      <ColorArea colorSpace="rgb" value={color} xChannel="red" yChannel="green" onChange={setColor}>
        <ColorArea.Thumb />
      </ColorArea>
      <div className="flex w-[300px] items-center gap-3">
        <ColorSwatch color={color} size="md" />
        <p className="text-sm text-muted">
          Current color:{" "}
          <span className="font-medium">{color ? color.toString("hex") : "(empty)"}</span>
        </p>
      </div>
    </div>
  );
}

```

### Color Space & Channels

Use `colorSpace` to set the color space (RGB, HSL, HSB) and `xChannel`/`yChannel` props to customize which color channels are displayed on each axis.

```tsx
"use client";

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

import {ColorArea, Label, ListBox, Select, parseColor} from "@heroui/react";
import {useState} from "react";

interface ChannelOption {
  id: ColorChannel;
  name: string;
}

const colorSpaces: Array<{id: ColorSpace; name: string}> = [
  {id: "rgb", name: "RGB"},
  {id: "hsl", name: "HSL"},
  {id: "hsb", name: "HSB"},
];

const channelsBySpace: Record<ColorSpace, ChannelOption[]> = {
  hsb: [
    {id: "hue", name: "Hue"},
    {id: "saturation", name: "Saturation"},
    {id: "brightness", name: "Brightness"},
  ],
  hsl: [
    {id: "hue", name: "Hue"},
    {id: "saturation", name: "Saturation"},
    {id: "lightness", name: "Lightness"},
  ],
  rgb: [
    {id: "red", name: "Red"},
    {id: "green", name: "Green"},
    {id: "blue", name: "Blue"},
  ],
};

export function ColorAreaSpaceAndChannels() {
  const [colorSpace, setColorSpace] = useState<ColorSpace>("hsb");
  const [color, setColor] = useState(() => parseColor("hsb(219, 58%, 93%)"));

const channels = channelsBySpace[colorSpace];
  const defaultX = colorSpace === "rgb" ? "blue" : "saturation";
  const defaultY =
    colorSpace === "rgb" ? "green" : colorSpace === "hsl" ? "lightness" : "brightness";

const [xChannel, setXChannel] = useState<ColorChannel>(defaultX);
  const [yChannel, setYChannel] = useState<ColorChannel>(defaultY);

const handleColorSpaceChange = (newSpace: Key | null) => {
    if (!newSpace) return;
    const space = newSpace as ColorSpace;

setColorSpace(space);
    // Reset channels to appropriate defaults for the new color space
    if (space === "rgb") {
      setXChannel("blue");
      setYChannel("green");
    } else if (space === "hsl") {
      setXChannel("saturation");
      setYChannel("lightness");
    } else {
      setXChannel("saturation");
      setYChannel("brightness");
    }
  };

// Filter out the other channel from options (can't have same channel on both axes)
  const xChannelOptions = channels.filter((c) => c.id !== yChannel);
  const yChannelOptions = channels.filter((c) => c.id !== xChannel);

return (
    <div className="flex flex-col items-center gap-6">
      {/* Controls */}
      <div className="flex gap-4">
        {/* Color Space Select */}
        <Select className="w-32" value={colorSpace} onChange={handleColorSpaceChange}>
          <Label>Color Space</Label>
          <Select.Trigger>
            <Select.Value />
            <Select.Indicator />
          </Select.Trigger>
          <Select.Popover>
            <ListBox>
              {colorSpaces.map((space) => (
                <ListBox.Item key={space.id} id={space.id} textValue={space.name}>
                  {space.name}
                  <ListBox.ItemIndicator />
                </ListBox.Item>
              ))}
            </ListBox>
          </Select.Popover>
        </Select>

{/* X Channel Select */}
        <Select
          className="w-36"
          value={xChannel}
          onChange={(value) => value && setXChannel(value as ColorChannel)}
        >
          <Label>X Axis</Label>
          <Select.Trigger>
            <Select.Value />
            <Select.Indicator />
          </Select.Trigger>
          <Select.Popover>
            <ListBox>
              {xChannelOptions.map((channel) => (
                <ListBox.Item key={channel.id} id={channel.id} textValue={channel.name}>
                  {channel.name}
                  <ListBox.ItemIndicator />
                </ListBox.Item>
              ))}
            </ListBox>
          </Select.Popover>
        </Select>

{/* Y Channel Select */}
        <Select
          className="w-36"
          value={yChannel}
          onChange={(value) => value && setYChannel(value as ColorChannel)}
        >
          <Label>Y Axis</Label>
          <Select.Trigger>
            <Select.Value />
            <Select.Indicator />
          </Select.Trigger>
          <Select.Popover>
            <ListBox>
              {yChannelOptions.map((channel) => (
                <ListBox.Item key={channel.id} id={channel.id} textValue={channel.name}>
                  {channel.name}
                  <ListBox.ItemIndicator />
                </ListBox.Item>
              ))}
            </ListBox>
          </Select.Popover>
        </Select>
      </div>
      {/* Color Area */}
      <ColorArea
        colorSpace={colorSpace}
        value={color}
        xChannel={xChannel}
        yChannel={yChannel}
        onChange={setColor}
      >
        <ColorArea.Thumb />
      </ColorArea>

{/* Color Value Display */}
      <div className="flex items-center gap-3">
        <div
          className="size-8 rounded-md border border-default"
          style={{backgroundColor: color.toString("css")}}
        />
        <code className="rounded bg-default/50 px-2 py-1 text-sm">
          {color.toString(colorSpace)}
        </code>
      </div>
    </div>
  );
}

```

### Disabled

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

export function ColorAreaDisabled() {
  return (
    <ColorArea isDisabled defaultValue="hsl(200, 100%, 50%)">
      <ColorArea.Thumb />
    </ColorArea>
  );
}

```

### Custom Render Function

```tsx
"use client";

import {ColorArea} from "@heroui/react";

export function CustomRenderFunction() {
  return (
    <ColorArea
      defaultValue="rgb(116, 52, 255)"
      render={(props) => <div {...props} data-custom="slider" />}
    >
      <ColorArea.Thumb render={(props) => <div {...props} data-custom="thumb" />} />
    </ColorArea>
  );
}

```

## Related Components

* **ColorSwatch**: Visual preview of a color value
* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorField**: Input for entering color values with hex format

## Styling

### Passing Tailwind CSS classes

```tsx
import { ColorArea } from '@heroui/react';

function CustomColorArea() {
  return (
    <ColorArea className="max-w-72 rounded-3xl">
      <ColorArea.Thumb />
    </ColorArea>
  );
}

```

### Customizing the component classes

To customize the ColorArea 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 {
  .color-area {
    @apply rounded-3xl;
  }

.color-area__thumb {
    @apply size-5 border-4;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The ColorArea component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-area.css)):

#### Base Classes

* `.color-area` - Base styles with gradient background and inner shadow
* `.color-area--show-dots` - Adds dot grid overlay for precision picking

#### Element Classes

* `.color-area__thumb` - Draggable thumb indicator

### Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

* **Disabled**: `[data-disabled="true"]`
* **Focus**: `[data-focus-visible="true"]`
* **Dragging**: `[data-dragging="true"]` (thumb only)

## API Reference

### ColorArea Props

Inherits from [React Aria ColorArea](https://react-spectrum.adobe.com/react-aria/ColorArea.html).

| Prop           | Type                                                                         | Default        | Description                                                      |
| -------------- | ---------------------------------------------------------------------------- | -------------- | ---------------------------------------------------------------- |
| `value`        | `string \| Color`                                                            | -              | The current color value (controlled)                             |
| `defaultValue` | `string \| Color`                                                            | -              | The default color value (uncontrolled)                           |
| `onChange`     | `(color: Color) => void`                                                     | -              | Handler called when the color changes while dragging             |
| `onChangeEnd`  | `(color: Color) => void`                                                     | -              | Handler called when the user stops dragging                      |
| `xChannel`     | `ColorChannel`                                                               | `"saturation"` | Color channel for the horizontal axis                            |
| `yChannel`     | `ColorChannel`                                                               | `"brightness"` | Color channel for the vertical axis                              |
| `colorSpace`   | `ColorSpace`                                                                 | -              | The color space for the channels                                 |
| `isDisabled`   | `boolean`                                                                    | `false`        | Whether the color area is disabled                               |
| `showDots`     | `boolean`                                                                    | `false`        | Whether to show the dot grid overlay                             |
| `className`    | `string`                                                                     | -              | Additional CSS classes                                           |
| `render`       | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorAreaRenderProps>` | -              | Overrides the default DOM element with a custom render function. |

### ColorArea.Thumb Props

| Prop        | Type                                                                          | Default | Description                                                      |
| ----------- | ----------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `className` | `string`                                                                      | -       | Additional CSS classes                                           |
| `style`     | `CSSProperties \| ((renderProps) => CSSProperties)`                           | -       | Inline styles or render props function                           |
| `render`    | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorThumbRenderProps>` | -       | Overrides the default DOM element with a custom render function. |

</page>

<page url="/docs/react/components/color-field">
# ColorField

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/color-field
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-field.mdx
> Color input field with labels, descriptions, and validation built on React Aria ColorField

## Import

```tsx
import { ColorField, parseColor } from '@heroui/react';

```

### Usage

```tsx
"use client";

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

import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
import {useState} from "react";

export function Basic() {
  const [color, setColor] = useState<Color | null>(parseColor("#0485F7"));

return (
    <ColorField className="w-[280px]" name="color" value={color} onChange={setColor}>
      <Label>Color</Label>
      <ColorField.Group>
        <ColorField.Prefix>
          <ColorSwatch color={color ?? undefined} size="xs" />
        </ColorField.Prefix>
        <ColorField.Input />
      </ColorField.Group>
    </ColorField>
  );
}

```

### Anatomy

```tsx
import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';

export default () => (
  <ColorField>
    <Label />
    <ColorField.Group>
      <ColorField.Prefix>
        <ColorSwatch color="#000000" />
      </ColorField.Prefix>
      <ColorField.Input />
    </ColorField.Group>
    <Description />
    <FieldError />
  </ColorField>
)

```

> **ColorField** combines label, color input, description, and error into a single accessible component.

### With Description

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

export function WithDescription() {
  return (
    <div className="flex flex-col gap-4">
      <ColorField className="w-[280px]" defaultValue="#3B82F6" name="color">
        <Label>Primary Color</Label>
        <ColorField.Group>
          <ColorField.Input />
        </ColorField.Group>
        <Description>Enter your brand's primary color</Description>
      </ColorField>
      <ColorField className="w-[280px]" defaultValue="#F59E0B" name="accent-color">
        <Label>Accent Color</Label>
        <ColorField.Group>
          <ColorField.Input />
        </ColorField.Group>
        <Description>Used for highlights and CTAs</Description>
      </ColorField>
    </div>
  );
}

```

### Required Field

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

export function Required() {
  return (
    <div className="flex flex-col gap-4">
      <ColorField isRequired className="w-[280px]" name="color">
        <Label>Brand Color</Label>
        <ColorField.Group>
          <ColorField.Input placeholder="#000000" />
        </ColorField.Group>
      </ColorField>
      <ColorField isRequired className="w-[280px]" name="theme-color">
        <Label>Theme Color</Label>
        <ColorField.Group>
          <ColorField.Input placeholder="#000000" />
        </ColorField.Group>
        <Description>Required field</Description>
      </ColorField>
    </div>
  );
}

```

### Validation

Use `isInvalid` together with `FieldError` to surface validation messages.

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

export function Invalid() {
  return (
    <div className="flex flex-col gap-4">
      <ColorField isInvalid isRequired className="w-[280px]" name="color">
        <Label>Color</Label>
        <ColorField.Group>
          <ColorField.Input placeholder="#000000" />
        </ColorField.Group>
        <FieldError>Please enter a valid hex color</FieldError>
      </ColorField>
      <ColorField isInvalid className="w-[280px]" name="invalid-color">
        <Label>Background Color</Label>
        <ColorField.Group>
          <ColorField.Input defaultValue="not-a-color" />
        </ColorField.Group>
        <FieldError>Invalid color format. Use hex (e.g., #FF5733)</FieldError>
      </ColorField>
    </div>
  );
}

```

### Channel Editing

ColorField supports editing individual color channels (hue, saturation, lightness, red, green, blue, alpha) by setting the `colorSpace` and `channel` props.

```tsx
"use client";

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

import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
import {useState} from "react";

export function ChannelEditing() {
  const [color, setColor] = useState<Color | null>(parseColor("#7F007F"));

return (
    <div className="flex flex-col gap-4">
      <p className="text-sm text-muted">Edit individual HSL channels:</p>
      <div className="flex gap-4">
        <ColorField
          channel="hue"
          className="w-[100px]"
          colorSpace="hsl"
          name="hue"
          value={color}
          onChange={setColor}
        >
          <Label>Hue</Label>
          <ColorField.Group>
            <ColorField.Input />
          </ColorField.Group>
        </ColorField>
        <ColorField
          channel="saturation"
          className="w-[100px]"
          colorSpace="hsl"
          name="saturation"
          value={color}
          onChange={setColor}
        >
          <Label>Saturation</Label>
          <ColorField.Group>
            <ColorField.Input />
            <ColorField.Suffix>
              <span className="text-sm text-muted">%</span>
            </ColorField.Suffix>
          </ColorField.Group>
        </ColorField>
        <ColorField
          channel="lightness"
          className="w-[100px]"
          colorSpace="hsl"
          name="lightness"
          value={color}
          onChange={setColor}
        >
          <Label>Lightness</Label>
          <ColorField.Group>
            <ColorField.Input />
            <ColorField.Suffix>
              <span className="text-sm text-muted">%</span>
            </ColorField.Suffix>
          </ColorField.Group>
        </ColorField>
      </div>
      <div className="flex items-center gap-2">
        <ColorSwatch color={color ?? undefined} size="md" />
        <span className="text-sm">Current: {color ? color.toString("hex") : "(empty)"}</span>
      </div>
    </div>
  );
}

```

### Controlled

Control the value to synchronize with other components or state management.

```tsx
"use client";

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

import {Button, ColorField, ColorSwatch, Description, Label, parseColor} from "@heroui/react";
import {useState} from "react";

export function Controlled() {
  const [value, setValue] = useState<Color | null>(parseColor("#0485F7"));

return (
    <div className="flex flex-col gap-4">
      <ColorField className="w-[280px]" name="color" value={value} onChange={setValue}>
        <Label>Color</Label>
        <ColorField.Group>
          <ColorField.Prefix>
            <ColorSwatch color={value ?? undefined} size="xs" />
          </ColorField.Prefix>
          <ColorField.Input />
        </ColorField.Group>
        <Description>Current value: {value ? value.toString("hex") : "(empty)"}</Description>
      </ColorField>
      <div className="flex gap-2">
        <Button variant="tertiary" onPress={() => setValue(parseColor("#EF4444"))}>
          Set Red
        </Button>
        <Button variant="tertiary" onPress={() => setValue(parseColor("#10B981"))}>
          Set Green
        </Button>
        <Button variant="tertiary" onPress={() => setValue(null)}>
          Clear
        </Button>
      </div>
    </div>
  );
}

```

### Disabled State

```tsx
"use client";

import {ColorField, Description, Label} from "@heroui/react";

export function Disabled() {
  return (
    <div className="flex flex-col gap-4">
      <ColorField isDisabled className="w-[280px]" defaultValue="#0485F7" name="color">
        <Label>Color</Label>
        <ColorField.Group>
          <ColorField.Input />
        </ColorField.Group>
        <Description>This color field is disabled</Description>
      </ColorField>
      <ColorField isDisabled className="w-[280px]" name="color-empty">
        <Label>Color</Label>
        <ColorField.Group>
          <ColorField.Input placeholder="#000000" />
        </ColorField.Group>
        <Description>This color field is disabled</Description>
      </ColorField>
    </div>
  );
}

```

### Full Width

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

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-4">
      <ColorField fullWidth defaultValue="#10B981" name="color">
        <Label>Brand Color</Label>
        <ColorField.Group>
          <ColorField.Input />
        </ColorField.Group>
      </ColorField>
      <ColorField fullWidth defaultValue="#8B5CF6" name="color-with-suffix">
        <Label>Theme Color</Label>
        <ColorField.Group>
          <ColorField.Input />
        </ColorField.Group>
      </ColorField>
    </div>
  );
}

```

### Variants

The ColorField.Group component supports two visual variants:

* **`primary`** (default) - Standard styling with shadow, suitable for most use cases
* **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components

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

export function Variants() {
  return (
    <div className="flex flex-col gap-4">
      <ColorField className="w-[280px]" defaultValue="#0485F7" name="primary-color">
        <Label>Primary variant</Label>
        <ColorField.Group variant="primary">
          <ColorField.Input />
        </ColorField.Group>
      </ColorField>
      <ColorField className="w-[280px]" defaultValue="#F43F5E" name="secondary-color">
        <Label>Secondary variant</Label>
        <ColorField.Group variant="secondary">
          <ColorField.Input />
        </ColorField.Group>
      </ColorField>
    </div>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on ColorField.Group to apply the lower emphasis variant suitable for surface backgrounds.

```tsx
import {ColorField, Description, Label, Surface} from "@heroui/react";

export function OnSurface() {
  return (
    <Surface className="w-[320px] p-4">
      <ColorField defaultValue="#3B82F6" name="color">
        <Label>Theme Color</Label>
        <ColorField.Group variant="secondary">
          <ColorField.Input />
        </ColorField.Group>
        <Description>Select your theme color</Description>
      </ColorField>
    </Surface>
  );
}

```

### Form Example

Complete form example with validation and submission handling.

```tsx
"use client";

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

import {Button, ColorField, ColorSwatch, Description, Form, Label} from "@heroui/react";
import {useState} from "react";

export function FormExample() {
  const [value, setValue] = useState<Color | null>(null);
  const [isSubmitting, setIsSubmitting] = useState(false);

const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();

if (!value) {
      return;
    }

setIsSubmitting(true);

// Simulate API call
    setTimeout(() => {
      console.log("Color submitted:", {color: value.toString("hex")});
      setValue(null);
      setIsSubmitting(false);
    }, 1500);
  };

return (
    <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}>
      <ColorField
        fullWidth
        isRequired
        className="w-full"
        name="brand-color"
        value={value}
        onChange={setValue}
      >
        <Label>Brand Color</Label>
        <ColorField.Group>
          <ColorField.Prefix>
            <ColorSwatch color={value ?? undefined} size="xs" />
          </ColorField.Prefix>
          <ColorField.Input placeholder="#000000" />
        </ColorField.Group>
        <Description>Choose your brand's primary color</Description>
      </ColorField>
      <Button
        className="w-full"
        isDisabled={!value}
        isPending={isSubmitting}
        type="submit"
        variant="primary"
      >
        {isSubmitting ? "Saving..." : "Save Color"}
      </Button>
    </Form>
  );
}

```

### Custom Render Function

```tsx
"use client";

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

import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react";
import {useState} from "react";

export function CustomRenderFunction() {
  const [color, setColor] = useState<Color | null>(parseColor("#0485F7"));

return (
    <ColorField
      className="w-[280px]"
      name="color"
      render={(props) => <div {...props} data-custom="foo" />}
      value={color}
      onChange={setColor}
    >
      <Label>Color</Label>
      <ColorField.Group render={(props) => <div {...props} data-custom="foo" />}>
        <ColorField.Prefix>
          <ColorSwatch color={color ?? undefined} size="xs" />
        </ColorField.Prefix>
        <ColorField.Input />
      </ColorField.Group>
    </ColorField>
  );
}

```

## Related Components

* **ColorSwatch**: Visual preview of a color value
* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorPicker**: Composable color picker with popover

## Styling

### Passing Tailwind CSS classes

```tsx
import {ColorField, Label, ColorSwatch, Description} from '@heroui/react';

function CustomColorField() {
  return (
    <ColorField className="gap-2 rounded-xl border border-border/60 bg-surface p-4 shadow-sm">
      <Label className="text-sm font-semibold text-default-700">
        Brand Color
      </Label>
      <ColorField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
        <ColorField.Prefix>
          <ColorSwatch color="#3B82F6" />
        </ColorField.Prefix>
        <ColorField.Input />
      </ColorField.Group>
      <Description className="text-xs text-default-500">
        Select your brand's primary color.
      </Description>
    </ColorField>
  );
}

```

### Customizing the component classes

ColorField has minimal default styling. Override the `.color-field` class to customize the container styling.

```css
@layer components {
  .color-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

* `.color-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. ColorField.Group styling is documented below in the API Reference section.

### Interactive States

ColorField 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

### ColorField Props

ColorField inherits all props from React Aria's [ColorField](https://react-aria.adobe.com/ColorField.md) component.

#### Base Props

| Prop        | Type                                                                            | Default | Description                                                          |
| ----------- | ------------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------- |
| `children`  | `React.ReactNode \| (values: ColorFieldRenderProps) => React.ReactNode`         | -       | Child components (Label, ColorField.Group, etc.) or render function. |
| `className` | `string \| (values: ColorFieldRenderProps) => string`                           | -       | CSS classes for styling, supports render props.                      |
| `style`     | `React.CSSProperties \| (values: ColorFieldRenderProps) => React.CSSProperties` | -       | Inline styles, supports render props.                                |
| `fullWidth` | `boolean`                                                                       | `false` | Whether the color field should take full width of its container      |
| `id`        | `string`                                                                        | -       | The element's unique identifier.                                     |
| `render`    | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorFieldRenderProps>`   | -       | Overrides the default DOM element with a custom render function.     |

#### Value Props

| Prop           | Type                             | Default | Description                            |
| -------------- | -------------------------------- | ------- | -------------------------------------- |
| `value`        | `Color \| null`                  | -       | Current value (controlled).            |
| `defaultValue` | `Color \| null`                  | -       | Default value (uncontrolled).          |
| `onChange`     | `(color: Color \| null) => void` | -       | Handler called when the value changes. |

#### Channel Props

| Prop         | Type           | Default | Description                                                                  |
| ------------ | -------------- | ------- | ---------------------------------------------------------------------------- |
| `colorSpace` | `ColorSpace`   | -       | The color space that the color field operates in when `channel` is provided. |
| `channel`    | `ColorChannel` | -       | The color channel to edit. If not provided, edits hex value.                 |

#### 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: Color) => ValidationError \| true \| null \| undefined` | -          | Custom validation function.                                    |
| `validationBehavior` | `'native' \| 'aria'`                                             | `'native'` | Whether to use native HTML form validation or ARIA attributes. |

#### State Props

| Prop              | Type      | Default | Description                                        |
| ----------------- | --------- | ------- | -------------------------------------------------- |
| `isDisabled`      | `boolean` | -       | Whether the input is disabled.                     |
| `isReadOnly`      | `boolean` | -       | Whether the input can be selected but not changed. |
| `isWheelDisabled` | `boolean` | -       | Whether to disable changing the value with scroll. |

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

| 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

ColorField works with these separate components that should be imported and used directly:

* **Label** - Field label component from `@heroui/react`
* **ColorField.Group** - Color input group component (documented below)
* **ColorField.Input** - Input element within ColorField.Group
* **ColorField.Prefix** / **ColorField.Suffix** - Prefix and suffix slots for the input group
* **ColorSwatch** - Color preview 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 ColorField for composition:

```tsx
import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react';

<ColorField
  isRequired
  isInvalid={hasError}
  value={color}
  onChange={setColor}
>
  <Label>Brand Color</Label>
  <ColorField.Group>
    <ColorField.Prefix>
      <ColorSwatch color={color?.toString("hex") || "#E4E4E7"} />
    </ColorField.Prefix>
    <ColorField.Input />
  </ColorField.Group>
  <Description>Select your brand's primary color.</Description>
  <FieldError>Please enter a valid color.</FieldError>
</ColorField>

```

### Color Types

ColorField uses `Color` objects from React Aria Components:

```tsx
import {parseColor} from '@heroui/react';

// Parse from hex string
const color = parseColor('#3B82F6');

// Get hex string from color
const hex = color.toString('hex'); // "#3b82f6"

// Get RGB values
const rgb = color.toString('rgb'); // "rgb(59, 130, 246)"

// Use in ColorField
<ColorField value={color} onChange={setColor}>
  {/* ... */}
</ColorField>

```

### ColorFieldRenderProps

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). |

### ColorField.Group Props

ColorField.Group 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 color input group should take full width of its container                                                                                              |
| `variant`   | `"primary" \| "secondary"`                                               | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |
| `render`    | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, GroupRenderProps>` | -           | Overrides the default DOM element with a custom render function.                                                                                                   |

### ColorField.Input Props

ColorField.Input accepts all props from React Aria's `Input` component plus the following:

| Prop          | Type     | Default | Description                                        |
| ------------- | -------- | ------- | -------------------------------------------------- |
| `className`   | `string` | -       | Tailwind classes merged with the component styles. |
| `placeholder` | `string` | -       | Placeholder text shown when empty.                 |

### ColorField.Prefix Props

ColorField.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.             |

### ColorField.Suffix Props

ColorField.Suffix accepts standard HTML `div` attributes:

## ColorField.Group Styling

### Customizing the component classes

The base classes power every instance. Override them once with `@layer components`.

```css
@layer components {
  .color-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;
    }
  }

.color-input-group__input {
    @apply flex flex-1 items-center rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none;
  }

.color-input-group__prefix,
  .color-input-group__suffix {
    @apply shrink-0 text-field-placeholder flex items-center;
  }
}

```

### ColorField.Group CSS Classes

* `.color-input-group` – Root container styling
* `.color-input-group__input` – Input wrapper styling
* `.color-input-group__prefix` – Prefix element styling
* `.color-input-group__suffix` – Suffix element styling

### ColorField.Group Interactive States

</page>

<page url="/docs/react/components/color-picker">
# ColorPicker

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/color-picker
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-picker.mdx
> A composable color picker that synchronizes color value between multiple color components

## Import

```tsx
import {
  ColorPicker,
  ColorArea,
  ColorSlider,
  ColorSwatch,
  ColorField,
  ColorSwatchPicker,
} from '@heroui/react';

```

### Usage

```tsx
import {ColorArea, ColorPicker, ColorSlider, ColorSwatch, Label} from "@heroui/react";

export function Basic() {
  return (
    <ColorPicker defaultValue="#0485F7">
      <ColorPicker.Trigger>
        <ColorSwatch size="lg" />
        <Label>Pick a color</Label>
      </ColorPicker.Trigger>
      <ColorPicker.Popover>
        <ColorArea
          aria-label="Color area"
          className="max-w-full"
          colorSpace="hsb"
          xChannel="saturation"
          yChannel="brightness"
        >
          <ColorArea.Thumb />
        </ColorArea>
        <ColorSlider channel="hue" className="gap-1 px-1" colorSpace="hsb">
          <Label>Hue</Label>
          <ColorSlider.Output className="text-muted" />
          <ColorSlider.Track>
            <ColorSlider.Thumb />
          </ColorSlider.Track>
        </ColorSlider>
      </ColorPicker.Popover>
    </ColorPicker>
  );
}

```

### Anatomy

The ColorPicker is a composable component that combines multiple color components:

```tsx
import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';

export default () => (
  <ColorPicker defaultValue="#0485F7">
    <ColorPicker.Trigger>
      <ColorSwatch />
      <Label>Pick a color</Label>
    </ColorPicker.Trigger>
    <ColorPicker.Popover>
      <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness">
        <ColorArea.Thumb />
      </ColorArea>
      <ColorSlider channel="hue" colorSpace="hsb">
        <ColorSlider.Track>
          <ColorSlider.Thumb />
        </ColorSlider.Track>
      </ColorSlider>
    </ColorPicker.Popover>
  </ColorPicker>
);

```

### Controlled

```tsx
"use client";

import {
  Button,
  ColorArea,
  ColorField,
  ColorPicker,
  ColorSlider,
  ColorSwatch,
  ColorSwatchPicker,
  Label,
  parseColor,
} from "@heroui/react";
import {Icon} from "@iconify/react";
import {useState} from "react";

export function Controlled() {
  const [color, setColor] = useState(parseColor("#325578"));

const colorPresets = [
    "#ef4444",
    "#f97316",
    "#eab308",
    "#22c55e",
    "#06b6d4",
    "#3b82f6",
    "#8b5cf6",
    "#ec4899",
    "#f43f5e",
  ];

const shuffleColor = () => {
    const randomHue = Math.floor(Math.random() * 360);
    const randomSaturation = 50 + Math.floor(Math.random() * 50); // 50-100%
    const randomLightness = 40 + Math.floor(Math.random() * 30); // 40-70%

setColor(parseColor(`hsl(${randomHue}, ${randomSaturation}%, ${randomLightness}%)`));
  };

return (
    <div className="flex flex-col gap-4">
      <ColorPicker value={color} onChange={setColor}>
        <ColorPicker.Trigger>
          <ColorSwatch size="lg" />
          <Label>Pick a color</Label>
        </ColorPicker.Trigger>
        <ColorPicker.Popover className="gap-2">
          <ColorSwatchPicker className="justify-center pt-2" size="xs">
            {colorPresets.map((preset) => (
              <ColorSwatchPicker.Item key={preset} color={preset}>
                <ColorSwatchPicker.Swatch />
              </ColorSwatchPicker.Item>
            ))}
          </ColorSwatchPicker>
          <ColorArea
            aria-label="Color area"
            className="max-w-full"
            colorSpace="hsb"
            xChannel="saturation"
            yChannel="brightness"
          >
            <ColorArea.Thumb />
          </ColorArea>
          <div className="flex items-center gap-2 px-1">
            <ColorSlider aria-label="Hue slider" channel="hue" className="flex-1" colorSpace="hsb">
              <ColorSlider.Track>
                <ColorSlider.Thumb />
              </ColorSlider.Track>
            </ColorSlider>
            <Button
              isIconOnly
              aria-label="Shuffle color"
              size="sm"
              variant="tertiary"
              onPress={shuffleColor}
            >
              <Icon className="size-4" icon="gravity-ui:shuffle" />
            </Button>
          </div>
          <ColorField aria-label="Color field">
            <ColorField.Group variant="secondary">
              <ColorField.Prefix>
                <ColorSwatch size="xs" />
              </ColorField.Prefix>
              <ColorField.Input />
            </ColorField.Group>
          </ColorField>
        </ColorPicker.Popover>
      </ColorPicker>
      <p className="w-60 text-sm text-muted">
        Selected: <span className="font-medium">{color.toString("hex")}</span>
      </p>
    </div>
  );
}

```

### With Swatches

```tsx
import {
  ColorArea,
  ColorPicker,
  ColorSlider,
  ColorSwatch,
  ColorSwatchPicker,
  Label,
} from "@heroui/react";

export function WithSwatches() {
  const presets = [
    "#ef4444",
    "#f97316",
    "#eab308",
    "#22c55e",
    "#06b6d4",
    "#3b82f6",
    "#8b5cf6",
    "#ec4899",
    "#f43f5e",
  ];

return (
    <ColorPicker defaultValue="#F43F5E">
      <ColorPicker.Trigger>
        <ColorSwatch size="lg" />
        <Label>Brand Color</Label>
      </ColorPicker.Trigger>
      <ColorPicker.Popover>
        <ColorArea
          aria-label="Color area"
          className="max-w-full"
          colorSpace="hsb"
          xChannel="saturation"
          yChannel="brightness"
        >
          <ColorArea.Thumb />
        </ColorArea>
        <ColorSlider aria-label="Hue slider" channel="hue" className="gap-1 px-1" colorSpace="hsb">
          <Label>Hue</Label>
          <ColorSlider.Output className="text-muted" />
          <ColorSlider.Track>
            <ColorSlider.Thumb />
          </ColorSlider.Track>
        </ColorSlider>
        <ColorSwatchPicker className="justify-center px-1" size="xs">
          {presets.map((preset) => (
            <ColorSwatchPicker.Item key={preset} color={preset}>
              <ColorSwatchPicker.Swatch />
            </ColorSwatchPicker.Item>
          ))}
        </ColorSwatchPicker>
      </ColorPicker.Popover>
    </ColorPicker>
  );
}

```

### With Fields

Use `ColorField` to allow users to edit individual color channel values with a `Select` to switch between color spaces.

```tsx
"use client";

import type {ColorChannel, ColorSpace} from "@heroui/react";

import {
  ColorArea,
  ColorField,
  ColorPicker,
  ColorSlider,
  ColorSwatch,
  Label,
  ListBox,
  Select,
} from "@heroui/react";
import {useState} from "react";

export function WithFields() {
  const [colorSpace, setColorSpace] = useState<ColorSpace>("hsl");

const colorChannelsByColorSpace: Record<ColorSpace, ColorChannel[]> = {
    hsb: ["hue", "saturation", "brightness"],
    hsl: ["hue", "saturation", "lightness"],
    rgb: ["red", "green", "blue"],
  };

return (
    <ColorPicker defaultValue="hsla(220, 90%, 50%, 0.8)">
      <ColorPicker.Trigger>
        <ColorSwatch size="lg" />
        <Label>Pick a color</Label>
      </ColorPicker.Trigger>
      <ColorPicker.Popover className="max-w-62 gap-2">
        <ColorArea
          className="max-w-full"
          colorSpace="hsb"
          xChannel="saturation"
          yChannel="brightness"
        >
          <ColorArea.Thumb />
        </ColorArea>
        <ColorSlider channel="hue" className="gap-1 px-1" colorSpace="hsb">
          <Label>Hue</Label>
          <ColorSlider.Output className="text-muted" />
          <ColorSlider.Track>
            <ColorSlider.Thumb />
          </ColorSlider.Track>
        </ColorSlider>
        <Select
          aria-label="Color space"
          value={colorSpace}
          variant="secondary"
          onChange={(value) => setColorSpace(value as ColorSpace)}
        >
          <Select.Trigger>
            <Select.Value className="uppercase" />
            <Select.Indicator />
          </Select.Trigger>
          <Select.Popover>
            <ListBox>
              {Object.keys(colorChannelsByColorSpace).map((space) => (
                <ListBox.Item key={space} className="uppercase" id={space} textValue={space}>
                  {space}
                  <ListBox.ItemIndicator />
                </ListBox.Item>
              ))}
            </ListBox>
          </Select.Popover>
        </Select>
        <div className="grid w-full grid-cols-3 items-center gap-2">
          {colorChannelsByColorSpace[colorSpace].map((channel) => (
            <ColorField
              key={channel}
              aria-label={channel}
              channel={channel}
              colorSpace={colorSpace}
            >
              <ColorField.Group variant="secondary">
                <ColorField.Input />
              </ColorField.Group>
            </ColorField>
          ))}
        </div>
      </ColorPicker.Popover>
    </ColorPicker>
  );
}

```

### With Sliders

Use multiple `ColorSlider` components to adjust each channel of a color value.

```tsx
"use client";

import type {ColorChannel, ColorSpace} from "@heroui/react";

import {ColorPicker, ColorSlider, ColorSwatch, Label, ListBox, Select} from "@heroui/react";
import {useState} from "react";

export function WithSliders() {
  const [colorSpace, setColorSpace] = useState<ColorSpace>("hsl");

const colorChannelsByColorSpace: Record<ColorSpace, ColorChannel[]> = {
    hsb: ["hue", "saturation", "brightness", "alpha"],
    hsl: ["hue", "saturation", "lightness", "alpha"],
    rgb: ["red", "green", "blue", "alpha"],
  };

return (
    <ColorPicker defaultValue="hsl(219, 58%, 93%)">
      <ColorPicker.Trigger>
        <ColorSwatch size="lg" />
        <Label>Pick a color</Label>
      </ColorPicker.Trigger>
      <ColorPicker.Popover className="max-w-62 gap-2 px-2 py-3">
        <Select
          aria-label="Color space"
          value={colorSpace}
          variant="secondary"
          onChange={(value) => setColorSpace(value as ColorSpace)}
        >
          <Select.Trigger>
            <Select.Value className="uppercase" />
            <Select.Indicator />
          </Select.Trigger>
          <Select.Popover>
            <ListBox>
              {Object.keys(colorChannelsByColorSpace).map((space) => (
                <ListBox.Item key={space} className="uppercase" id={space} textValue={space}>
                  {space}
                  <ListBox.ItemIndicator />
                </ListBox.Item>
              ))}
            </ListBox>
          </Select.Popover>
        </Select>
        <div className="flex flex-col gap-2">
          {colorChannelsByColorSpace[colorSpace].map((channel: ColorChannel) => (
            // @ts-expect-error - TypeScript can't correlate dynamic colorSpace with channel type
            <ColorSlider
              key={channel}
              aria-label={channel}
              channel={channel}
              className="gap-1 px-1"
              colorSpace={colorSpace}
            >
              <Label className="capitalize">{channel}</Label>
              <ColorSlider.Output className="text-muted" />
              <ColorSlider.Track>
                <ColorSlider.Thumb />
              </ColorSlider.Track>
            </ColorSlider>
          ))}
        </div>
      </ColorPicker.Popover>
    </ColorPicker>
  );
}

```

## Related Components

* **ColorArea**: 2D color picker for selecting colors from a gradient area
* **ColorSlider**: Slider for adjusting individual color channel values
* **ColorSwatch**: Visual preview of a color value

## Styling

### Passing Tailwind CSS classes

```tsx
import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react';

function CustomColorPicker() {
  return (
    <ColorPicker defaultValue="#0485F7">
      <ColorPicker.Trigger className="gap-4">
        <ColorSwatch className="rounded-lg" />
        <Label>Pick a color</Label>
      </ColorPicker.Trigger>
      <ColorPicker.Popover className="p-4 rounded-xl">
        <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness">
          <ColorArea.Thumb />
        </ColorArea>
      </ColorPicker.Popover>
    </ColorPicker>
  );
}

```

### Customizing the component classes

To customize the ColorPicker 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 {
  .color-picker {
    @apply inline-flex;
  }

.color-picker__trigger {
    @apply inline-flex items-center gap-4 rounded-lg;
  }

.color-picker__popover {
    @apply p-4 rounded-xl;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The ColorPicker component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-picker.css)):

#### Base Classes

* `.color-picker` - Base container
* `.color-picker__trigger` - Trigger button
* `.color-picker__popover` - Popover container

### Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

* **Focus**: `:focus-visible` or `[data-focus-visible="true"]`
* **Disabled**: `:disabled` or `[data-disabled="true"]`

## API Reference

### ColorPicker Props

Inherits from [React Aria ColorPicker](https://react-spectrum.adobe.com/react-aria/ColorPicker.html).

| Prop           | Type                     | Default | Description                                          |
| -------------- | ------------------------ | ------- | ---------------------------------------------------- |
| `value`        | `string \| Color`        | -       | The current color value (controlled)                 |
| `defaultValue` | `string \| Color`        | -       | The default color value (uncontrolled)               |
| `onChange`     | `(color: Color) => void` | -       | Handler called when the color changes                |
| `children`     | `React.ReactNode`        | -       | Content of the color picker (Trigger, Popover, etc.) |
| `className`    | `string`                 | -       | Additional CSS classes                               |

### ColorPicker.Trigger Props

| Prop        | Type                                                    | Default | Description                    |
| ----------- | ------------------------------------------------------- | ------- | ------------------------------ |
| `children`  | `React.ReactNode \| ((renderProps) => React.ReactNode)` | -       | Trigger content or render prop |
| `className` | `string`                                                | -       | Additional CSS classes         |

### ColorPicker.Popover Props

| Prop        | Type              | Default         | Description              |
| ----------- | ----------------- | --------------- | ------------------------ |
| `placement` | `Placement`       | `"bottom left"` | Placement of the popover |
| `children`  | `React.ReactNode` | -               | Popover content          |
| `className` | `string`          | -               | Additional CSS classes   |

### Related Types

#### Color

Represents a color value. See [React Aria Color](https://react-spectrum.adobe.com/react-aria/ColorPicker.html#color) for full API.

| Method                             | Description                                                                  |
| ---------------------------------- | ---------------------------------------------------------------------------- |
| `toString(format)`                 | Converts the color to a string in the given format (hex, rgb, hsl, hsb, css) |
| `toFormat(format)`                 | Converts the color to the given format and returns a new Color object        |
| `getChannelValue(channel)`         | Returns the numeric value for a given channel                                |
| `withChannelValue(channel, value)` | Sets the numeric value for a channel and returns a new Color                 |

#### parseColor

```tsx
import { parseColor } from 'react-aria-components';

// Parse from string
const color = parseColor('#ff0000');
const hslColor = parseColor('hsl(0, 100%, 50%)');

```

</page>

<page url="/docs/react/components/color-slider">
# ColorSlider

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/color-slider
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-slider.mdx
> A color slider allows users to adjust an individual channel of a color value

## Import

```tsx
import { ColorSlider, Label } from '@heroui/react';

```

### Usage

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

export function Basic() {
  return (
    <ColorSlider channel="hue" className="w-full max-w-xs" defaultValue="hsl(0, 100%, 50%)">
      <Label>Hue</Label>
      <ColorSlider.Output />
      <ColorSlider.Track>
        <ColorSlider.Thumb />
      </ColorSlider.Track>
    </ColorSlider>
  );
}

```

### Anatomy

Import the ColorSlider component and access all parts using dot notation.

```tsx
import { ColorSlider, Label } from '@heroui/react';

export default () => (
  <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)">
    <Label>Hue</Label>
    <ColorSlider.Output />
    <ColorSlider.Track>
      <ColorSlider.Thumb />
    </ColorSlider.Track>
  </ColorSlider>
)

```

### Vertical

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

export function Vertical() {
  return (
    <div className="flex h-48 gap-4">
      <ColorSlider
        aria-label="Hue"
        channel="hue"
        defaultValue="hsl(0, 100%, 50%)"
        orientation="vertical"
      >
        <ColorSlider.Track>
          <ColorSlider.Thumb />
        </ColorSlider.Track>
      </ColorSlider>
      <ColorSlider
        aria-label="Saturation"
        channel="saturation"
        defaultValue="hsl(0, 100%, 50%)"
        orientation="vertical"
      >
        <ColorSlider.Track>
          <ColorSlider.Thumb />
        </ColorSlider.Track>
      </ColorSlider>
      <ColorSlider
        aria-label="Lightness"
        channel="lightness"
        defaultValue="hsl(0, 100%, 50%)"
        orientation="vertical"
      >
        <ColorSlider.Track>
          <ColorSlider.Thumb />
        </ColorSlider.Track>
      </ColorSlider>
    </div>
  );
}

```

### Disabled

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

export function Disabled() {
  return (
    <ColorSlider
      isDisabled
      channel="hue"
      className="w-full max-w-xs"
      defaultValue="hsl(200, 100%, 50%)"
    >
      <Label>Hue</Label>
      <ColorSlider.Output />
      <ColorSlider.Track>
        <ColorSlider.Thumb />
      </ColorSlider.Track>
    </ColorSlider>
  );
}

```

### Controlled

```tsx
"use client";

import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
import {useState} from "react";
import {parseColor} from "react-aria-components";

export function Controlled() {
  const [color, setColor] = useState(parseColor("hsl(200, 100%, 50%)"));

```

### HSL Channels

Use multiple ColorSliders to control different channels of a color value. The sliders can share the same color value to create a complete color picker.

```tsx
"use client";

import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
import {useState} from "react";
import {parseColor} from "react-aria-components";

export function Channels() {
  const [color, setColor] = useState(parseColor("hsl(0, 100%, 50%)"));

return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      <ColorSlider channel="hue" value={color} onChange={setColor}>
        <Label>Hue</Label>
        <ColorSlider.Output />
        <ColorSlider.Track>
          <ColorSlider.Thumb />
        </ColorSlider.Track>
      </ColorSlider>
      <ColorSlider channel="saturation" value={color} onChange={setColor}>
        <Label>Saturation</Label>
        <ColorSlider.Output />
        <ColorSlider.Track>
          <ColorSlider.Thumb />
        </ColorSlider.Track>
      </ColorSlider>
      <ColorSlider channel="lightness" value={color} onChange={setColor}>
        <Label>Lightness</Label>
        <ColorSlider.Output />
        <ColorSlider.Track>
          <ColorSlider.Thumb />
        </ColorSlider.Track>
      </ColorSlider>
      <div className="flex items-center gap-2">
        <ColorSwatch color={color} size="sm" />
        <p className="text-sm text-muted">
          Current color: <code className="font-mono">{color.toString("hsl")}</code>
        </p>
      </div>
    </div>
  );
}

```

### Alpha Channel

The alpha channel slider shows a transparency checkerboard pattern to help visualize the transparency level.

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

export function AlphaChannel() {
  return (
    <ColorSlider channel="alpha" className="w-full max-w-xs" defaultValue="hsla(0, 100%, 50%, 0.5)">
      <Label>Alpha</Label>
      <ColorSlider.Output />
      <ColorSlider.Track>
        <ColorSlider.Thumb />
      </ColorSlider.Track>
    </ColorSlider>
  );
}

```

### RGB Channels

You can also use RGB color space with red, green, and blue channels.

```tsx
"use client";

import {ColorSlider, ColorSwatch, Label} from "@heroui/react";
import {useState} from "react";
import {parseColor} from "react-aria-components";

export function RGBChannels() {
  const [color, setColor] = useState(parseColor("rgb(255, 100, 50)"));

return (
    <div className="flex w-full max-w-xs flex-col gap-4">
      <ColorSlider channel="red" value={color} onChange={setColor}>
        <Label>Red</Label>
        <ColorSlider.Output />
        <ColorSlider.Track>
          <ColorSlider.Thumb />
        </ColorSlider.Track>
      </ColorSlider>
      <ColorSlider channel="green" value={color} onChange={setColor}>
        <Label>Green</Label>
        <ColorSlider.Output />
        <ColorSlider.Track>
          <ColorSlider.Thumb />
        </ColorSlider.Track>
      </ColorSlider>
      <ColorSlider channel="blue" value={color} onChange={setColor}>
        <Label>Blue</Label>
        <ColorSlider.Output />
        <ColorSlider.Track>
          <ColorSlider.Thumb />
        </ColorSlider.Track>
      </ColorSlider>
      <div className="flex items-center gap-2">
        <ColorSwatch color={color} size="sm" />
        <p className="text-sm text-muted">
          Current color: <code className="font-mono">{color.toString("rgb")}</code>
        </p>
      </div>
    </div>
  );
}

```

### Custom Render Function

```tsx
"use client";

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

export function CustomRenderFunction() {
  return (
    <ColorSlider
      channel="hue"
      className="w-full max-w-xs"
      defaultValue="hsl(0, 100%, 50%)"
      render={(props) => <div {...props} data-custom="foo" />}
    >
      <Label>Hue</Label>
      <ColorSlider.Output />
      <ColorSlider.Track>
        <ColorSlider.Thumb />
      </ColorSlider.Track>
    </ColorSlider>
  );
}

```

## Related Components

* **ColorSwatch**: Visual preview of a color value
* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorPicker**: Composable color picker with popover

## Styling

### Passing Tailwind CSS classes

```tsx
import { ColorSlider, Label } from '@heroui/react';

function CustomColorSlider() {
  return (
    <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)" className="w-full">
      <Label>Hue</Label>
      <ColorSlider.Output className="text-muted text-sm" />
      <ColorSlider.Track className="h-6 rounded-full">
        <ColorSlider.Thumb className="size-5 rounded-full border-2 border-white" />
      </ColorSlider.Track>
    </ColorSlider>
  );
}

```

### Customizing the component classes

To customize the ColorSlider 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 {
  .color-slider {
    @apply flex flex-col gap-2;
  }

.color-slider__output {
    @apply text-muted text-sm;
  }

.color-slider__track {
    @apply relative h-5 w-full rounded-full;
  }

.color-slider__thumb {
    @apply size-4 rounded-full border-3 border-white shadow-overlay;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The ColorSlider component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-slider.css)):

#### Base Classes

* `.color-slider` - Base slider container
* `.color-slider__output` - Output element displaying current value
* `.color-slider__track` - Track element with color gradient
* `.color-slider__thumb` - Thumb element showing current color

#### State Classes

* `.color-slider[data-disabled="true"]` - Disabled slider state
* `.color-slider[data-orientation="vertical"]` - Vertical orientation
* `.color-slider__thumb[data-dragging="true"]` - Thumb being dragged
* `.color-slider__thumb[data-focus-visible="true"]` - Thumb keyboard focused
* `.color-slider__thumb[data-disabled="true"]` - Disabled thumb state

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

### ColorSlider Props

Inherits from [React Aria ColorSlider](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).

| Prop           | Type                                                                           | Default        | Description                                                                                                     |
| -------------- | ------------------------------------------------------------------------------ | -------------- | --------------------------------------------------------------------------------------------------------------- |
| `channel`      | `ColorChannel`                                                                 | -              | The color channel that the slider manipulates (hue, saturation, lightness, brightness, alpha, red, green, blue) |
| `colorSpace`   | `ColorSpace`                                                                   | -              | The color space (hsl, hsb, rgb). Defaults to the color space of the value                                       |
| `value`        | `string \| Color`                                                              | -              | The current color value (controlled)                                                                            |
| `defaultValue` | `string \| Color`                                                              | -              | The default color value (uncontrolled)                                                                          |
| `onChange`     | `(value: Color) => void`                                                       | -              | Handler called when the value changes during dragging                                                           |
| `onChangeEnd`  | `(value: Color) => void`                                                       | -              | Handler called when dragging ends                                                                               |
| `orientation`  | `"horizontal" \| "vertical"`                                                   | `"horizontal"` | The orientation of the slider                                                                                   |
| `isDisabled`   | `boolean`                                                                      | -              | Whether the slider is disabled                                                                                  |
| `name`         | `string`                                                                       | -              | The name of the input element for form submission                                                               |
| `aria-label`   | `string`                                                                       | -              | Accessibility label for the slider                                                                              |
| `className`    | `string`                                                                       | -              | Additional CSS classes                                                                                          |
| `children`     | `ReactNode \| RenderFunction`                                                  | -              | Slider content or render function                                                                               |
| `render`       | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSliderRenderProps>` | -              | Overrides the default DOM element with a custom render function.                                                |

### ColorSlider.Output Props

| Prop        | Type                          | Default | Description                       |
| ----------- | ----------------------------- | ------- | --------------------------------- |
| `className` | `string`                      | -       | Additional CSS classes            |
| `children`  | `ReactNode \| RenderFunction` | -       | Output content or render function |

### ColorSlider.Track Props

| Prop        | Type                              | Default | Description                      |
| ----------- | --------------------------------- | ------- | -------------------------------- |
| `className` | `string`                          | -       | Additional CSS classes           |
| `style`     | `CSSProperties \| RenderFunction` | -       | Inline styles or render function |
| `children`  | `ReactNode \| RenderFunction`     | -       | Track content or render function |

### ColorSlider.Thumb Props

### RenderProps

When using render functions, these values are provided:

| Prop          | Type                         | Description                    |
| ------------- | ---------------------------- | ------------------------------ |
| `state`       | `ColorSliderState`           | The state of the color slider  |
| `color`       | `Color`                      | The current color value        |
| `orientation` | `"horizontal" \| "vertical"` | The orientation of the slider  |
| `isDisabled`  | `boolean`                    | Whether the slider is disabled |

## Accessibility

The ColorSlider 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

For more information, see the [React Aria ColorSlider documentation](https://react-spectrum.adobe.com/react-aria/ColorSlider.html).

</page>

<page url="/docs/react/components/color-swatch-picker">
# ColorSwatchPicker

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/color-swatch-picker
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-swatch-picker.mdx
> A list of color swatches that allows users to select a color from a predefined palette.

## Import

```tsx
import { ColorSwatchPicker, parseColor } from '@heroui/react';

```

### Usage

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

const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];

export function Basic() {
  return (
    <ColorSwatchPicker>
      {colors.map((color) => (
        <ColorSwatchPicker.Item key={color} color={color}>
          <ColorSwatchPicker.Swatch />
          <ColorSwatchPicker.Indicator />
        </ColorSwatchPicker.Item>
      ))}
    </ColorSwatchPicker>
  );
}

```

### Anatomy

Import the ColorSwatchPicker component and access all parts using dot notation.

```tsx
import { ColorSwatchPicker } from '@heroui/react';

export default () => (
  <ColorSwatchPicker>
    <ColorSwatchPicker.Item color="#F43F5E">
      <ColorSwatchPicker.Swatch />
      <ColorSwatchPicker.Indicator />
    </ColorSwatchPicker.Item>
    <ColorSwatchPicker.Item color="#D946EF">
      <ColorSwatchPicker.Swatch />
      <ColorSwatchPicker.Indicator />
    </ColorSwatchPicker.Item>
    <ColorSwatchPicker.Item color="#8B5CF6">
      <ColorSwatchPicker.Swatch />
      <ColorSwatchPicker.Indicator />
    </ColorSwatchPicker.Item>
  </ColorSwatchPicker>
);

```

### Variants

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

const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];

export function Variants() {
  return (
    <div className="flex flex-col gap-6">
      <div className="flex flex-col gap-2">
        <span className="text-sm text-muted">Circle (default)</span>
        <ColorSwatchPicker variant="circle">
          {colors.map((color) => (
            <ColorSwatchPicker.Item key={color} color={color}>
              <ColorSwatchPicker.Swatch />
              <ColorSwatchPicker.Indicator />
            </ColorSwatchPicker.Item>
          ))}
        </ColorSwatchPicker>
      </div>
      <div className="flex flex-col gap-2">
        <span className="text-sm text-muted">Square</span>
        <ColorSwatchPicker variant="square">
          {colors.map((color) => (
            <ColorSwatchPicker.Item key={color} color={color}>
              <ColorSwatchPicker.Swatch />
              <ColorSwatchPicker.Indicator />
            </ColorSwatchPicker.Item>
          ))}
        </ColorSwatchPicker>
      </div>
    </div>
  );
}

```

### Sizes

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

const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];

const sizes = ["xs", "sm", "md", "lg", "xl"] as const;

export function Sizes() {
  return (
    <div className="flex flex-col gap-6">
      {sizes.map((size) => (
        <div key={size} className="flex items-center gap-4">
          <span className="w-8 text-sm text-muted">{size}</span>
          <ColorSwatchPicker size={size}>
            {colors.map((color) => (
              <ColorSwatchPicker.Item key={color} color={color}>
                <ColorSwatchPicker.Swatch />
                <ColorSwatchPicker.Indicator />
              </ColorSwatchPicker.Item>
            ))}
          </ColorSwatchPicker>
        </div>
      ))}
    </div>
  );
}

```

### Stack Layout

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

const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];

export function StackLayout() {
  return (
    <ColorSwatchPicker layout="stack">
      {colors.map((color) => (
        <ColorSwatchPicker.Item key={color} color={color}>
          <ColorSwatchPicker.Swatch />
          <ColorSwatchPicker.Indicator />
        </ColorSwatchPicker.Item>
      ))}
    </ColorSwatchPicker>
  );
}

```

### Default Value

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

const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];

export function DefaultValue() {
  return (
    <ColorSwatchPicker defaultValue="#8B5CF6">
      {colors.map((color) => (
        <ColorSwatchPicker.Item key={color} color={color}>
          <ColorSwatchPicker.Swatch />
          <ColorSwatchPicker.Indicator />
        </ColorSwatchPicker.Item>
      ))}
    </ColorSwatchPicker>
  );
}

```

### Controlled

```tsx
"use client";

import {ColorSwatchPicker, parseColor} from "@heroui/react";
import {useState} from "react";

const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];

export function Controlled() {
  const [value, setValue] = useState(parseColor("#F43F5E"));

return (
    <div className="flex flex-col gap-4">
      <ColorSwatchPicker value={value} onChange={setValue}>
        {colors.map((color) => (
          <ColorSwatchPicker.Item key={color} color={color}>
            <ColorSwatchPicker.Swatch />
            <ColorSwatchPicker.Indicator />
          </ColorSwatchPicker.Item>
        ))}
      </ColorSwatchPicker>
      <p className="text-sm text-muted">
        Selected: <span className="font-medium">{value.toString("hex")}</span>
      </p>
    </div>
  );
}

```

### Disabled

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

const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];

export function Disabled() {
  return (
    <ColorSwatchPicker>
      {colors.map((color) => (
        <ColorSwatchPicker.Item key={color} isDisabled color={color}>
          <ColorSwatchPicker.Swatch />
          <ColorSwatchPicker.Indicator />
        </ColorSwatchPicker.Item>
      ))}
    </ColorSwatchPicker>
  );
}

```

### Custom Indicator

```tsx
import {HeartFill} from "@gravity-ui/icons";
import {ColorSwatchPicker} from "@heroui/react";

export function CustomIndicator() {
  const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];

return (
    <ColorSwatchPicker>
      {colors.map((color) => (
        <ColorSwatchPicker.Item key={color} color={color}>
          <ColorSwatchPicker.Swatch />
          <ColorSwatchPicker.Indicator>
            <HeartFill />
          </ColorSwatchPicker.Indicator>
        </ColorSwatchPicker.Item>
      ))}
    </ColorSwatchPicker>
  );
}

```

### Custom Render Function

```tsx
"use client";

import {ColorSwatchPicker} from "@heroui/react";

const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"];

export function CustomRenderFunction() {
  return (
    <ColorSwatchPicker render={(props) => <div {...props} data-custom="foo" />}>
      {colors.map((color) => (
        <ColorSwatchPicker.Item key={color} color={color}>
          <ColorSwatchPicker.Swatch />
          <ColorSwatchPicker.Indicator />
        </ColorSwatchPicker.Item>
      ))}
    </ColorSwatchPicker>
  );
}

```

## Related Components

* **ColorSwatch**: Visual preview of a color value
* **ColorField**: Input for entering color values with hex format
* **ColorArea**: 2D color picker for selecting colors from a gradient area

## Styling

### Passing Tailwind CSS classes

You can customize the ColorSwatchPicker using className props:

```tsx
import { ColorSwatchPicker } from '@heroui/react';

function CustomColorSwatchPicker() {
  return (
    <ColorSwatchPicker className="gap-4">
      <ColorSwatchPicker.Item color="#F43F5E" className="shadow-lg">
        <ColorSwatchPicker.Swatch />
      </ColorSwatchPicker.Item>
      <ColorSwatchPicker.Item color="#D946EF">
        <ColorSwatchPicker.Swatch />
      </ColorSwatchPicker.Item>
    </ColorSwatchPicker>
  );
}

```

### Customizing the component classes

To customize the ColorSwatchPicker 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 {
  .color-swatch-picker {
    @apply gap-4;
  }

.color-swatch-picker__item {
    @apply shadow-md;
  }

.color-swatch-picker__swatch {
    @apply border-2 border-white;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The ColorSwatchPicker component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch-picker.css)):

#### Base & Structure

* `.color-swatch-picker` - Base container (flex layout)
* `.color-swatch-picker__item` - Individual swatch item wrapper
* `.color-swatch-picker__swatch` - The color swatch visual element

#### Size Classes

* `.color-swatch-picker--xs` - Extra small (16px)
* `.color-swatch-picker--sm` - Small (24px)
* `.color-swatch-picker--md` - Medium (32px, default)
* `.color-swatch-picker--lg` - Large (36px)
* `.color-swatch-picker--xl` - Extra large (40px)

#### Shape Variants

* `.color-swatch-picker--circle` - Circle shape (default)
* `.color-swatch-picker--square` - Square shape with rounded corners

#### Layout Classes

* `.color-swatch-picker--grid` - Horizontal wrapping layout (default)
* `.color-swatch-picker--stack` - Vertical stacked layout

### Interactive States

The component supports both CSS pseudo-classes and data attributes for flexibility:

* **Hover**: `:hover` or `[data-hovered="true"]` - Scale up to 1.1 (only when not selected)
* **Focus**: `:focus-visible` or `[data-focus-visible="true"]` - Focus ring
* **Selected**: `[data-selected="true"]` - Inner border with same color as swatch
* **Disabled**: `[data-disabled="true"]` - Reduced opacity

## API Reference

### ColorSwatchPicker Props

Inherits from [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/react-aria/ColorSwatchPicker.html).

| Prop           | Type                                                                                 | Default    | Description                                                      |
| -------------- | ------------------------------------------------------------------------------------ | ---------- | ---------------------------------------------------------------- |
| `value`        | `string \| Color`                                                                    | -          | The current selected color (controlled)                          |
| `defaultValue` | `string \| Color`                                                                    | -          | The default selected color (uncontrolled)                        |
| `onChange`     | `(value: Color) => void`                                                             | -          | Handler called when selection changes                            |
| `size`         | `"xs" \| "sm" \| "md" \| "lg" \| "xl"`                                               | `"md"`     | Size of the swatches                                             |
| `variant`      | `"circle" \| "square"`                                                               | `"circle"` | Shape of the swatches                                            |
| `layout`       | `"grid" \| "stack"`                                                                  | `"grid"`   | Layout direction                                                 |
| `className`    | `string`                                                                             | -          | Additional CSS classes                                           |
| `children`     | `React.ReactNode`                                                                    | -          | ColorSwatchPicker.Item elements                                  |
| `render`       | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerRenderProps>` | -          | Overrides the default DOM element with a custom render function. |

### ColorSwatchPicker.Item Props

| Prop         | Type                                                                                     | Default      | Description                                                      |
| ------------ | ---------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------- |
| `color`      | `string \| Color`                                                                        | **Required** | The color of the swatch                                          |
| `isDisabled` | `boolean`                                                                                | `false`      | Whether the item is disabled                                     |
| `className`  | `string`                                                                                 | -            | Additional CSS classes                                           |
| `children`   | `React.ReactNode`                                                                        | -            | ColorSwatchPicker.Swatch element                                 |
| `render`     | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerItemRenderProps>` | -            | Overrides the default DOM element with a custom render function. |

### ColorSwatchPicker.Swatch Props

| Prop        | Type     | Default | Description            |
| ----------- | -------- | ------- | ---------------------- |
| `className` | `string` | -       | Additional CSS classes |

### parseColor

The `parseColor` function is re-exported from React Aria Components for convenience:

```tsx
import { parseColor } from '@heroui/react';

// Parse hex color
const red = parseColor('#ff0000');

// Parse RGB
const green = parseColor('rgb(0, 255, 0)');

// Parse HSL
const blue = parseColor('hsl(240, 100%, 50%)');

```

</page>

<page url="/docs/react/components/color-swatch">
# ColorSwatch

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/color-swatch
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(colors)/color-swatch.mdx
> A visual preview of a color value with accessibility support

## Import

```tsx
import { ColorSwatch } from '@heroui/react';

```

### Usage

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

export function ColorSwatchBasic() {
  return (
    <div className="flex items-center gap-3">
      <ColorSwatch aria-label="Blue" color="#0485F7" />
      <ColorSwatch aria-label="Red" color="#EF4444" />
      <ColorSwatch aria-label="Amber" color="#F59E0B" />
      <ColorSwatch aria-label="Green" color="#10B981" />
      <ColorSwatch aria-label="Fuchsia" color="#D946EF" />
    </div>
  );
}

```

### Sizes

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

export function ColorSwatchSizes() {
  return (
    <div className="flex items-center gap-3">
      <ColorSwatch color="#0485F7" size="xs" />
      <ColorSwatch color="#EF4444" size="sm" />
      <ColorSwatch color="#F59E0B" size="md" />
      <ColorSwatch color="#10B981" size="lg" />
      <ColorSwatch color="#D946EF" size="xl" />
    </div>
  );
}

```

### Shapes

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

export function ColorSwatchShapes() {
  return (
    <div className="flex items-center gap-3">
      <ColorSwatch color="#0485F7" shape="circle" />
      <ColorSwatch color="#0485F7" shape="square" />
    </div>
  );
}

```

### Transparency

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

export function ColorSwatchTransparency() {
  return (
    <div className="flex items-center gap-3">
      <ColorSwatch aria-label="100% opacity" color="rgba(4, 133, 247, 1)" />
      <ColorSwatch aria-label="75% opacity" color="rgba(4, 133, 247, 0.75)" />
      <ColorSwatch aria-label="50% opacity" color="rgba(4, 133, 247, 0.5)" />
      <ColorSwatch aria-label="25% opacity" color="rgba(4, 133, 247, 0.25)" />
      <ColorSwatch aria-label="0% opacity" color="rgba(4, 133, 247, 0)" />
    </div>
  );
}

```

### Custom Styles with Render Props

You can use the `style` render props to access the color value and create custom visual effects.

```tsx
"use client";

import {ColorSwatch} from "@heroui/react";

export function ColorSwatchCustomStyles() {
  const colors = ["#0485F7", "#EF4444", "#F59E0B", "#10B981", "#D946EF"];

return (
    <div className="flex flex-col gap-8">
      {/* Glow effect */}
      <div className="flex flex-col gap-2">
        <span className="text-sm text-muted">Glow Effect</span>
        <div className="flex items-center gap-4">
          {colors.map((color) => (
            <ColorSwatch
              key={color}
              color={color}
              size="xl"
              style={() => ({
                boxShadow: `0 0 20px 2px ${color}`,
              })}
            />
          ))}
        </div>
      </div>

{/* Gradient swatch */}
      <div className="flex flex-col gap-2">
        <span className="text-sm text-muted">Gradient</span>
        <div className="flex items-center gap-4">
          {colors.map((color) => (
            <ColorSwatch
              key={color}
              color={color}
              size="xl"
              style={({color: c}) => ({
                background: `linear-gradient(135deg, ${c.toString("css")}, white)`,
              })}
            />
          ))}
        </div>
      </div>
    </div>
  );
}

```

### Accessibility

Use `colorName` to provide a custom accessible name for the color, and `aria-label` to add context about how the color is used.

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

export function ColorSwatchAccessibility() {
  return (
    <div className="flex items-center gap-3">
      <ColorSwatch aria-label="Primary brand color" color="#0485F7" colorName="Ocean Blue" />
      <ColorSwatch aria-label="Error state color" color="#EF4444" colorName="Coral Red" />
      <ColorSwatch aria-label="Warning color" color="#F59E0B" colorName="Sunset Orange" />
    </div>
  );
}

```

### Custom Render Function

```tsx
"use client";

import {ColorSwatch} from "@heroui/react";

export function CustomRenderFunction() {
  return (
    <div className="flex items-center gap-3">
      <ColorSwatch
        aria-label="Blue"
        color="#0485F7"
        render={(props) => <div {...props} data-custom="blue" />}
      />
      <ColorSwatch
        aria-label="Red"
        color="#EF4444"
        render={(props) => <div {...props} data-custom="red" />}
      />
      <ColorSwatch
        aria-label="Amber"
        color="#F59E0B"
        render={(props) => <div {...props} data-custom="amber" />}
      />
      <ColorSwatch
        aria-label="Green"
        color="#10B981"
        render={(props) => <div {...props} data-custom="green" />}
      />
      <ColorSwatch
        aria-label="Fuchsia"
        color="#D946EF"
        render={(props) => <div {...props} data-custom="fuchsia" />}
      />
    </div>
  );
}

```

## Related Components

* **ColorSwatchPicker**: Color swatch selection from a list of colors
* **ColorField**: Input for entering color values with hex format
* **ColorArea**: 2D color picker for selecting colors from a gradient area

## Styling

### Passing Tailwind CSS classes

```tsx
import {ColorSwatch} from '@heroui/react';

function CustomColorSwatch() {
  return (
    <ColorSwatch
      className="size-12 rounded-lg"
      color="#0485F7"
    />
  );
}

```

### Customizing the component classes

To customize the ColorSwatch 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 {
  .color-swatch {
    @apply border-2 border-white;
  }
}

```

HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize.

### CSS Classes

The ColorSwatch component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch.css)):

#### Base Classes

* `.color-swatch` - Base swatch styles with checkered background for transparency

#### Shape Classes

* `.color-swatch--circle` - Circular shape (default)
* `.color-swatch--square` - Square shape with rounded corners

#### Size Classes

* `.color-swatch--xs` - Extra small (16px)
* `.color-swatch--sm` - Small (24px)
* `.color-swatch--md` - Medium (32px, default)
* `.color-swatch--lg` - Large (36px)
* `.color-swatch--xl` - Extra large (40px)

## API Reference

### ColorSwatch Props

| Prop         | Type                                                                           | Default    | Description                                                          |
| ------------ | ------------------------------------------------------------------------------ | ---------- | -------------------------------------------------------------------- |
| `color`      | `string \| Color`                                                              | -          | The color value to display (hex, rgb, hsl, etc.)                     |
| `colorName`  | `string`                                                                       | -          | Accessible name for the color (overrides auto-generated description) |
| `className`  | `string`                                                                       | -          | Additional CSS classes                                               |
| `shape`      | `"circle" \| "square"`                                                         | `"circle"` | Shape of the swatch                                                  |
| `size`       | `"xs" \| "sm" \| "md" \| "lg" \| "xl"`                                         | `"md"`     | Size of the swatch                                                   |
| `style`      | `CSSProperties \| ((renderProps) => CSSProperties)`                            | -          | Inline styles or render props function with access to color          |
| `aria-label` | `string`                                                                       | -          | Accessible label for the swatch                                      |
| `render`     | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchRenderProps>` | -          | Overrides the default DOM element with a custom render function.     |

### Style Render Props

When using the `style` prop as a function, you receive render props with access to the color:

```tsx
<ColorSwatch
  color="#0485F7"
  style={({ color }) => ({
    boxShadow: `0 4px 14px ${color.toString("css")}80`,
  })}
/>

```

The `color` object provides methods like:

* `color.toString("css")` - Returns CSS color string
* `color.toString("hex")` - Returns hex color string
* `color.getChannelValue("alpha")` - Returns alpha channel value

</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";

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>
  );
}

```

### 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>
  );
}

```

### Custom Render Function

```tsx
"use client";

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

export function CustomRenderFunction() {
  return (
    <Slider
      className="w-full max-w-xs"
      defaultValue={30}
      render={(props) => <div {...props} data-custom="foo" />}
    >
      <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:

## 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                                |
| `render`          | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderRenderProps>` | -              | Overrides the default DOM element with a custom render function. |

### Slider.Output Props

| Prop        | Type                                                                            | Default | Description                                                      |
| ----------- | ------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- |
| `className` | `string`                                                                        | -       | Additional CSS classes                                           |
| `children`  | `ReactNode \| RenderFunction`                                                   | -       | Output content or render function                                |
| `render`    | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderOutputRenderProps>` | -       | Overrides the default DOM element with a custom render function. |

### Slider.Track Props

| Prop        | Type                                                                           | Default | Description                                                      |
| ----------- | ------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------- |
| `className` | `string`                                                                       | -       | Additional CSS classes                                           |
| `children`  | `ReactNode \| RenderFunction`                                                  | -       | Track content or render function                                 |
| `render`    | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderTrackRenderProps>` | -       | Overrides the default DOM element with a custom 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                                 |
| `render`     | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderThumbRenderProps>` | -       | Overrides the default DOM element with a custom 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:

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";

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

```

### 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>
  );
}

```

### Custom Render Function

```tsx
"use client";

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

export function CustomRenderFunction() {
  return (
    <Switch render={(props) => <label {...props} data-custom="foo" />}>
      <Switch.Control>
        <Switch.Thumb />
      </Switch.Control>
      <Label className="text-sm">Enable notifications</Label>
    </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                                     |
| `render`          | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SwitchRenderProps>` | -       | Overrides the default DOM element with a custom render function.  |

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

```

## Anatomy

Import the Chip component and access all parts using dot notation.

> Plain-text children are automatically wrapped in `<Chip.Label>`.

```tsx
<Chip>
  Label text
</Chip>

```

### Usage

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

```

### 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 />
                        <Chip.Label>Label</Chip.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} />
        <Chip.Label>Information</Chip.Label>
      </Chip>
      <Chip color="success">
        <CircleCheckFill width={12} />
        <Chip.Label>Completed</Chip.Label>
      </Chip>
      <Chip color="warning">
        <Clock width={12} />
        <Chip.Label>Pending</Chip.Label>
      </Chip>
      <Chip color="danger">
        <Xmark width={12} />
        <Chip.Label>Failed</Chip.Label>
      </Chip>
      <Chip color="accent">
        <Chip.Label>Label</Chip.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} />
          <Chip.Label>Default</Chip.Label>
        </Chip>
        <Chip color="success" variant="primary">
          <CircleFill width={6} />
          <Chip.Label>Active</Chip.Label>
        </Chip>
        <Chip color="warning" variant="primary">
          <CircleFill width={6} />
          <Chip.Label>Pending</Chip.Label>
        </Chip>
        <Chip color="danger" variant="primary">
          <CircleFill width={6} />
          <Chip.Label>Inactive</Chip.Label>
        </Chip>
      </div>

<div className="flex flex-wrap items-center gap-3">
        <Chip>
          <CircleInfo width={12} />
          <Chip.Label>New Feature</Chip.Label>
        </Chip>
        <Chip color="success">
          <Check width={12} />
          <Chip.Label>Available</Chip.Label>
        </Chip>
        <Chip color="warning">
          <TriangleExclamation width={12} />
          <Chip.Label>Beta</Chip.Label>
        </Chip>
        <Chip color="danger">
          <Ban width={12} />
          <Chip.Label>Deprecated</Chip.Label>
        </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

You can style the root container and individual slots:

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

function CustomChip() {
  return (
    <Chip className="rounded-full px-4 py-2 font-bold">
      <Chip.Label className="text-lg uppercase">
        Custom Styled
      </Chip.Label>
    </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__label {
    @apply font-medium;
  }

.chip--accent {
    @apply border-accent/20;
  }

.chip--accent .chip__label {
    @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 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 container styles
* `.chip__label` - Label text slot 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 for the root element |
| `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                            |

### Chip.Label Props

| Prop        | Type              | Default | Description                               |
| ----------- | ----------------- | ------- | ----------------------------------------- |
| `children`  | `React.ReactNode` | -       | Label text content                        |
| `className` | `string`          | -       | Additional CSS classes for the label slot |

</page>

<page url="/docs/react/components/calendar">
# Calendar

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/calendar
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(date-and-time)/calendar.mdx
> Composable date picker with month grid, navigation, and year picker support built on React Aria Calendar

## Import

```tsx
import { Calendar } from '@heroui/react';

```

### Usage

```tsx
"use client";

import {Calendar} from "@heroui/react";

export function Basic() {
  return (
    <Calendar aria-label="Event date">
      <Calendar.Header>
        <Calendar.Heading />
        <Calendar.NavButton slot="previous" />
        <Calendar.NavButton slot="next" />
      </Calendar.Header>
      <Calendar.Grid>
        <Calendar.GridHeader>
          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
        </Calendar.GridHeader>
        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
      </Calendar.Grid>
    </Calendar>
  );
}

```

### Anatomy

```tsx
import {Calendar} from '@heroui/react';

export default () => (
  <Calendar aria-label="Event date">
    <Calendar.Header>
      <Calendar.Heading />
      <Calendar.NavButton slot="previous" />
      <Calendar.NavButton slot="next" />
    </Calendar.Header>
    <Calendar.Grid>
      <Calendar.GridHeader>
        {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
      </Calendar.GridHeader>
      <Calendar.GridBody>
        {(date) => <Calendar.Cell date={date} />}
      </Calendar.GridBody>
    </Calendar.Grid>
  </Calendar>
)

```

### Year Picker

`Calendar.YearPickerTrigger`, `Calendar.YearPickerGrid`, and their body/cell subcomponents provide an integrated year navigation pattern.

```tsx
"use client";

import {Calendar} from "@heroui/react";

export function YearPicker() {
  return (
    <Calendar aria-label="Event date">
      <Calendar.Header>
        <Calendar.YearPickerTrigger>
          <Calendar.YearPickerTriggerHeading />
          <Calendar.YearPickerTriggerIndicator />
        </Calendar.YearPickerTrigger>
        <Calendar.NavButton slot="previous" />
        <Calendar.NavButton slot="next" />
      </Calendar.Header>
      <Calendar.Grid>
        <Calendar.GridHeader>
          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
        </Calendar.GridHeader>
        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
      </Calendar.Grid>
      <Calendar.YearPickerGrid>
        <Calendar.YearPickerGridBody>
          {({year}) => <Calendar.YearPickerCell year={year} />}
        </Calendar.YearPickerGridBody>
      </Calendar.YearPickerGrid>
    </Calendar>
  );
}

```

### Default Value

```tsx
"use client";

import {Calendar} from "@heroui/react";
import {parseDate} from "@internationalized/date";

export function DefaultValue() {
  return (
    <Calendar aria-label="Event date" defaultValue={parseDate("2025-02-14")}>
      <Calendar.Header>
        <Calendar.Heading />
        <Calendar.NavButton slot="previous" />
        <Calendar.NavButton slot="next" />
      </Calendar.Header>
      <Calendar.Grid>
        <Calendar.GridHeader>
          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
        </Calendar.GridHeader>
        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
      </Calendar.Grid>
    </Calendar>
  );
}

```

### Controlled

Use controlled `value` and `focusedValue` for external state coordination and custom shortcuts.

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {Button, ButtonGroup, Calendar, Description} from "@heroui/react";
import {
  getLocalTimeZone,
  parseDate,
  startOfMonth,
  startOfWeek,
  today,
} from "@internationalized/date";
import {useState} from "react";
import {useLocale} from "react-aria-components";

export function Controlled() {
  const [value, setValue] = useState<DateValue | null>(null);
  const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-12-25"));
  const {locale} = useLocale();

return (
    <div className="flex flex-col items-center gap-4">
      <ButtonGroup fullWidth size="sm" variant="tertiary">
        <Button
          onPress={() => {
            const todayDate = today(getLocalTimeZone());

setValue(todayDate);
            setFocusedDate(todayDate);
          }}
        >
          Today
        </Button>
        <Button
          onPress={() => {
            const nextWeekStart = startOfWeek(today(getLocalTimeZone()), locale);

setValue(nextWeekStart);
            setFocusedDate(nextWeekStart);
          }}
        >
          Week
        </Button>
        <Button
          onPress={() => {
            const nextMonthStart = startOfMonth(today(getLocalTimeZone()));

setValue(nextMonthStart);
            setFocusedDate(nextMonthStart);
          }}
        >
          Month
        </Button>
      </ButtonGroup>

<Description className="text-center">
        Selected date: {value ? value.toString() : "(none)"}
      </Description>

<div className="flex gap-2">
        <Button
          size="sm"
          variant="secondary"
          onPress={() => {
            const todayDate = today(getLocalTimeZone());

setValue(todayDate);
            setFocusedDate(todayDate);
          }}
        >
          Set Today
        </Button>
        <Button
          size="sm"
          variant="secondary"
          onPress={() => {
            const christmasDate = parseDate("2025-12-25");

setValue(christmasDate);
            setFocusedDate(christmasDate);
          }}
        >
          Set Christmas
        </Button>
        <Button size="sm" variant="tertiary" onPress={() => setValue(null)}>
          Clear
        </Button>
      </div>
    </div>
  );
}

```

### Min and Max Dates

```tsx
"use client";

import {Calendar, Description} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";

export function MinMaxDates() {
  const now = today(getLocalTimeZone());
  const minDate = now;
  const maxDate = now.add({months: 3});

return (
    <div className="flex flex-col items-center gap-4">
      <Calendar aria-label="Appointment date" maxValue={maxDate} minValue={minDate}>
        <Calendar.Header>
          <Calendar.Heading />
          <Calendar.NavButton slot="previous" />
          <Calendar.NavButton slot="next" />
        </Calendar.Header>
        <Calendar.Grid>
          <Calendar.GridHeader>
            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
          </Calendar.GridHeader>
          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
        </Calendar.Grid>
      </Calendar>
      <Description className="text-center">
        Select a date between today and {maxDate.toString()}
      </Description>
    </div>
  );
}

```

### Unavailable Dates

Use `isDateUnavailable` to block dates such as weekends, holidays, or booked slots.

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {Calendar, Description} from "@heroui/react";
import {isWeekend} from "@internationalized/date";
import {useLocale} from "react-aria-components";

export function UnavailableDates() {
  const {locale} = useLocale();
  const isDateUnavailable = (date: DateValue) => isWeekend(date, locale);

return (
    <div className="flex flex-col items-center gap-4">
      <Calendar aria-label="Appointment date" isDateUnavailable={isDateUnavailable}>
        <Calendar.Header>
          <Calendar.Heading />
          <Calendar.NavButton slot="previous" />
          <Calendar.NavButton slot="next" />
        </Calendar.Header>
        <Calendar.Grid>
          <Calendar.GridHeader>
            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
          </Calendar.GridHeader>
          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
        </Calendar.Grid>
      </Calendar>
      <Description className="text-center">Weekends are unavailable</Description>
    </div>
  );
}

```

### Disabled

```tsx
"use client";

import {Calendar, Description} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";

export function Disabled() {
  return (
    <div className="flex flex-col items-center gap-4">
      <Calendar isDisabled aria-label="Event date" defaultValue={today(getLocalTimeZone())}>
        <Calendar.Header>
          <Calendar.Heading />
          <Calendar.NavButton slot="previous" />
          <Calendar.NavButton slot="next" />
        </Calendar.Header>
        <Calendar.Grid>
          <Calendar.GridHeader>
            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
          </Calendar.GridHeader>
          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
        </Calendar.Grid>
      </Calendar>
      <Description className="text-center">Calendar is disabled</Description>
    </div>
  );
}

```

### Read Only

```tsx
"use client";

import {Calendar, Description} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";

export function ReadOnly() {
  return (
    <div className="flex flex-col items-center gap-4">
      <Calendar isReadOnly aria-label="Event date" defaultValue={today(getLocalTimeZone())}>
        <Calendar.Header>
          <Calendar.Heading />
          <Calendar.NavButton slot="previous" />
          <Calendar.NavButton slot="next" />
        </Calendar.Header>
        <Calendar.Grid>
          <Calendar.GridHeader>
            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
          </Calendar.GridHeader>
          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
        </Calendar.Grid>
      </Calendar>
      <Description className="text-center">Calendar is read-only</Description>
    </div>
  );
}

```

### Focused Value

Programmatically control which date is focused using `focusedValue` and `onFocusChange`.

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {Button, Calendar, Description} from "@heroui/react";
import {parseDate} from "@internationalized/date";
import {useState} from "react";

export function FocusedValue() {
  const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-06-15"));

return (
    <div className="flex flex-col items-center gap-4">
      <Calendar aria-label="Event date" focusedValue={focusedDate} onFocusChange={setFocusedDate}>
        <Calendar.Header>
          <Calendar.Heading />
          <Calendar.NavButton slot="previous" />
          <Calendar.NavButton slot="next" />
        </Calendar.Header>
        <Calendar.Grid>
          <Calendar.GridHeader>
            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
          </Calendar.GridHeader>
          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
        </Calendar.Grid>
      </Calendar>

<Description className="text-center">Focused: {focusedDate.toString()}</Description>

<div className="flex flex-wrap justify-center gap-2">
        <Button
          size="sm"
          variant="secondary"
          onPress={() => setFocusedDate(parseDate("2025-01-01"))}
        >
          Go to Jan
        </Button>
        <Button
          size="sm"
          variant="secondary"
          onPress={() => setFocusedDate(parseDate("2025-06-15"))}
        >
          Go to Jun
        </Button>
        <Button
          size="sm"
          variant="secondary"
          onPress={() => setFocusedDate(parseDate("2025-12-25"))}
        >
          Go to Christmas
        </Button>
      </div>
    </div>
  );
}

```

### Cell Indicators

You can customize `Calendar.Cell` children and use `Calendar.CellIndicator` to display metadata like events.

```tsx
"use client";

import {Calendar} from "@heroui/react";
import {getLocalTimeZone, isToday} from "@internationalized/date";

const datesWithEvents = [3, 7, 12, 15, 21, 28];

export function WithIndicators() {
  return (
    <Calendar aria-label="Event date">
      <Calendar.Header>
        <Calendar.Heading />
        <Calendar.NavButton slot="previous" />
        <Calendar.NavButton slot="next" />
      </Calendar.Header>
      <Calendar.Grid>
        <Calendar.GridHeader>
          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
        </Calendar.GridHeader>
        <Calendar.GridBody>
          {(date) => (
            <Calendar.Cell date={date}>
              {({formattedDate}) => (
                <>
                  {formattedDate}
                  {(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && (
                    <Calendar.CellIndicator />
                  )}
                </>
              )}
            </Calendar.Cell>
          )}
        </Calendar.GridBody>
      </Calendar.Grid>
    </Calendar>
  );
}

```

### Multiple Months

Render multiple grids with `visibleDuration` and `offset` for booking and planning experiences.

```tsx
"use client";

import {Calendar} from "@heroui/react";
import {getLocalTimeZone} from "@internationalized/date";
import React from "react";
import {CalendarStateContext, useLocale} from "react-aria-components";

function CalendarMonthHeading({offset = 0}: {offset?: number}) {
  const state = React.useContext(CalendarStateContext)!;
  const {locale} = useLocale();

const startDate = state.visibleRange.start;
  const monthDate = startDate.add({months: offset});
  const dateObj = monthDate.toDate(getLocalTimeZone());
  const monthYear = new Intl.DateTimeFormat(locale, {month: "long", year: "numeric"}).format(
    dateObj,
  );

return <span className="text-sm font-medium">{monthYear}</span>;
}

export function MultipleMonths() {
  return (
    <Calendar
      aria-label="Trip dates"
      className="@container-normal w-auto"
      visibleDuration={{months: 2}}
    >
      <Calendar.Heading className="sr-only" />
      <div className="flex gap-8">
        <div className="w-64">
          <Calendar.Header>
            <Calendar.NavButton slot="previous" />
            <CalendarMonthHeading offset={0} />
            <div className="size-6" />
          </Calendar.Header>
          <Calendar.Grid>
            <Calendar.GridHeader>
              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
            </Calendar.GridHeader>
            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
          </Calendar.Grid>
        </div>
        <div className="w-64">
          <Calendar.Header>
            <div className="size-6" />
            <CalendarMonthHeading offset={1} />
            <Calendar.NavButton slot="next" />
          </Calendar.Header>
          <Calendar.Grid offset={{months: 1}}>
            <Calendar.GridHeader>
              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
            </Calendar.GridHeader>
            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
          </Calendar.Grid>
        </div>
      </div>
    </Calendar>
  );
}

```

### International Calendars

By default, Calendar displays dates using the calendar system for the user's locale. You can override this by wrapping your Calendar with `I18nProvider` and setting the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string).

The example below shows the Indian calendar system:

```tsx
"use client";

import {Calendar} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";
import {I18nProvider} from "react-aria-components";

export function InternationalCalendar() {
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <Calendar aria-label="Event date" defaultValue={today(getLocalTimeZone())}>
        <Calendar.Header>
          <Calendar.YearPickerTrigger>
            <Calendar.YearPickerTriggerHeading />
            <Calendar.YearPickerTriggerIndicator />
          </Calendar.YearPickerTrigger>
          <Calendar.NavButton slot="previous" />
          <Calendar.NavButton slot="next" />
        </Calendar.Header>
        <Calendar.Grid>
          <Calendar.GridHeader>
            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
          </Calendar.GridHeader>
          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
        </Calendar.Grid>
        <Calendar.YearPickerGrid>
          <Calendar.YearPickerGridBody>
            {({year}) => <Calendar.YearPickerCell year={year} />}
          </Calendar.YearPickerGridBody>
        </Calendar.YearPickerGrid>
      </Calendar>
    </I18nProvider>
  );
}

```

**Note:** The `onChange` event always returns a date in the same calendar system as the `value` or `defaultValue` (Gregorian if no value is provided), regardless of the displayed locale. This ensures your application logic works consistently with a single calendar system while still displaying dates in the user's preferred format.

For a complete list of supported calendar systems and their identifiers, see:

* [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations)
* [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars)

### Custom Navigation Icons

Pass children to `Calendar.NavButton` to replace the default chevron icons.

```tsx
"use client";

import {Calendar} from "@heroui/react";

export function CustomIcons() {
  return (
    <Calendar aria-label="Event date">
      <Calendar.Header>
        <Calendar.Heading />
        <Calendar.NavButton slot="previous">
          <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg">
            <path d="M15.41 16.59L10.83 12l4.58-4.59L14 6l-6 6l6 6z" fill="currentColor" />
          </svg>
        </Calendar.NavButton>
        <Calendar.NavButton slot="next">
          <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg">
            <path d="M8.59 16.59L13.17 12L8.59 7.41L10 6l6 6l-6 6z" fill="currentColor" />
          </svg>
        </Calendar.NavButton>
      </Calendar.Header>
      <Calendar.Grid>
        <Calendar.GridHeader>
          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
        </Calendar.GridHeader>
        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
      </Calendar.Grid>
    </Calendar>
  );
}

```

### Real-World Example

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {Button, Calendar} from "@heroui/react";
import {getLocalTimeZone, isWeekend, today} from "@internationalized/date";
import {useState} from "react";
import {useLocale} from "react-aria-components";

export function BookingCalendar() {
  const [selectedDate, setSelectedDate] = useState<DateValue | null>(null);
  const {locale} = useLocale();

const bookedDates = [5, 6, 12, 13, 14, 20];

const isDateUnavailable = (date: DateValue) => {
    return isWeekend(date, locale) || bookedDates.includes(date.day);
  };

return (
    <div className="flex flex-col items-center gap-4">
      <Calendar
        aria-label="Booking date"
        isDateUnavailable={isDateUnavailable}
        minValue={today(getLocalTimeZone())}
        value={selectedDate}
        onChange={setSelectedDate}
      >
        <Calendar.Header>
          <Calendar.Heading />
          <Calendar.NavButton slot="previous" />
          <Calendar.NavButton slot="next" />
        </Calendar.Header>
        <Calendar.Grid>
          <Calendar.GridHeader>
            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
          </Calendar.GridHeader>
          <Calendar.GridBody>
            {(date) => (
              <Calendar.Cell date={date}>
                {({formattedDate, isUnavailable}) => (
                  <>
                    {formattedDate}
                    {!isUnavailable &&
                      !isWeekend(date, locale) &&
                      bookedDates.includes(date.day) && <Calendar.CellIndicator />}
                  </>
                )}
              </Calendar.Cell>
            )}
          </Calendar.GridBody>
        </Calendar.Grid>
      </Calendar>

<div className="flex flex-col gap-2 text-center">
        <div className="flex items-center justify-center gap-4 text-xs text-muted">
          <span className="flex items-center gap-1">
            <span className="size-2 rounded-full bg-muted" /> Has bookings
          </span>
          <span className="flex items-center gap-1">
            <span className="size-2 rounded-full bg-default" /> Weekend/Unavailable
          </span>
        </div>
        {selectedDate ? (
          <Button size="sm" variant="primary">
            Book {selectedDate.toString()}
          </Button>
        ) : null}
      </div>
    </div>
  );
}

```

### Custom Styles

```tsx
"use client";

import {Calendar} from "@heroui/react";

export function CustomStyles() {
  return (
    <Calendar aria-label="Custom styled calendar">
      <Calendar.Header>
        <Calendar.NavButton className="text-foreground" slot="previous" />
        <Calendar.YearPickerTrigger className="w-full justify-center">
          <Calendar.YearPickerTriggerHeading className="text-foreground" />
          <Calendar.YearPickerTriggerIndicator className="text-foreground" />
        </Calendar.YearPickerTrigger>
        <Calendar.NavButton className="text-foreground" slot="next" />
      </Calendar.Header>
      <Calendar.Grid>
        <Calendar.GridHeader>
          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
        </Calendar.GridHeader>
        <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
      </Calendar.Grid>
      <Calendar.YearPickerGrid>
        <Calendar.YearPickerGridBody>
          {({year}) => <Calendar.YearPickerCell year={year} />}
        </Calendar.YearPickerGridBody>
      </Calendar.YearPickerGrid>
    </Calendar>
  );
}

```

## Related Components

* **DateField**: Date input field with labels, descriptions, and validation
* **DatePicker**: Composable date picker with date field trigger and calendar popover
* **TimeField**: Time input field with labels, descriptions, and validation

## Styling

### Passing Tailwind CSS classes

```tsx
import {Calendar} from '@heroui/react';

function CustomCalendar() {
  return (
    <Calendar aria-label="Custom calendar" className="w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm">
      <Calendar.Header className="pb-3">
        <Calendar.Heading className="text-default" />
        <Calendar.NavButton slot="previous" className="text-default" />
        <Calendar.NavButton slot="next" className="text-default" />
      </Calendar.Header>
      <Calendar.Grid>
        <Calendar.GridHeader>
          {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
        </Calendar.GridHeader>
        <Calendar.GridBody>
          {(date) => <Calendar.Cell date={date} />}
        </Calendar.GridBody>
      </Calendar.Grid>
    </Calendar>
  );
}

```

### Customizing the component classes

```css
@layer components {
  .calendar {
    @apply w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm;
  }

.calendar__heading {
    @apply text-sm font-semibold text-default-700;
  }

.calendar__cell[data-selected="true"] {
    @apply bg-accent text-accent-foreground;
  }
}

```

### CSS Classes

Calendar uses these classes in `packages/styles/components/calendar.css` and `packages/styles/components/calendar-year-picker.css`:

* `.calendar` - Root container.
* `.calendar__header` - Header row containing nav buttons and heading.
* `.calendar__heading` - Current month label.
* `.calendar__nav-button` - Previous/next navigation controls.
* `.calendar__grid` - Main day grid.
* `.calendar__grid-header` - Weekday header row wrapper.
* `.calendar__grid-body` - Date rows wrapper.
* `.calendar__header-cell` - Weekday header cell.
* `.calendar__cell` - Interactive day cell.
* `.calendar__cell-indicator` - Dot indicator inside a day cell.
* `.calendar-year-picker__trigger` - Year picker toggle button.
* `.calendar-year-picker__trigger-heading` - Heading text inside year picker trigger.
* `.calendar-year-picker__trigger-indicator` - Indicator icon inside year picker trigger.
* `.calendar-year-picker__year-grid` - Overlay grid of selectable years.
* `.calendar-year-picker__year-cell` - Individual year option.

### Interactive States

Calendar supports both pseudo-classes and React Aria data attributes:

* **Selected**: `[data-selected="true"]`
* **Today**: `[data-today="true"]`
* **Unavailable**: `[data-unavailable="true"]`
* **Outside month**: `[data-outside-month="true"]`
* **Hovered**: `:hover` or `[data-hovered="true"]`
* **Pressed**: `:active` or `[data-pressed="true"]`
* **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]`
* **Disabled**: `:disabled` or `[data-disabled="true"]`

## API Reference

### Calendar Props

Calendar inherits all props from React Aria [Calendar](https://react-spectrum.adobe.com/react-aria/Calendar.html).

| Prop                     | Type                           | Default                     | Description                                            |
| ------------------------ | ------------------------------ | --------------------------- | ------------------------------------------------------ |
| `value`                  | `DateValue \| null`            | -                           | Controlled selected date.                              |
| `defaultValue`           | `DateValue \| null`            | -                           | Initial selected date (uncontrolled).                  |
| `onChange`               | `(value: DateValue) => void`   | -                           | Called when selection changes.                         |
| `focusedValue`           | `DateValue`                    | -                           | Controlled focused date.                               |
| `onFocusChange`          | `(value: DateValue) => void`   | -                           | Called when focus moves to another date.               |
| `minValue`               | `DateValue`                    | Calendar-aware `1900-01-01` | Earliest selectable date.                              |
| `maxValue`               | `DateValue`                    | Calendar-aware `2099-12-31` | Latest selectable date.                                |
| `isDateUnavailable`      | `(date: DateValue) => boolean` | -                           | Marks dates as unavailable.                            |
| `isDisabled`             | `boolean`                      | `false`                     | Disables interaction and selection.                    |
| `isReadOnly`             | `boolean`                      | `false`                     | Keeps content readable but prevents selection changes. |
| `isInvalid`              | `boolean`                      | `false`                     | Marks the calendar as invalid for validation UI.       |
| `visibleDuration`        | `{months?: number}`            | `{months: 1}`               | Number of visible months.                              |
| `defaultYearPickerOpen`  | `boolean`                      | `false`                     | Initial open state of internal year picker.            |
| `isYearPickerOpen`       | `boolean`                      | -                           | Controlled year picker open state.                     |
| `onYearPickerOpenChange` | `(isOpen: boolean) => void`    | -                           | Called when year picker open state changes.            |

### Composition Parts

| Component                             | Description                                                                |
| ------------------------------------- | -------------------------------------------------------------------------- |
| `Calendar.Header`                     | Header container for navigation and heading.                               |
| `Calendar.Heading`                    | Current month/year heading.                                                |
| `Calendar.NavButton`                  | Previous/next navigation control (`slot=\"previous\"` or `slot=\"next\"`). |
| `Calendar.Grid`                       | Day grid for one month (`offset` supported for multi-month layouts).       |
| `Calendar.GridHeader`                 | Weekday header container.                                                  |
| `Calendar.GridBody`                   | Date cell body container.                                                  |
| `Calendar.HeaderCell`                 | Weekday label cell.                                                        |
| `Calendar.Cell`                       | Individual date cell.                                                      |
| `Calendar.CellIndicator`              | Optional indicator element for custom metadata.                            |
| `Calendar.YearPickerTrigger`          | Trigger to toggle year-picker mode.                                        |
| `Calendar.YearPickerTriggerHeading`   | Localized heading content inside the year-picker trigger.                  |
| `Calendar.YearPickerTriggerIndicator` | Toggle icon inside the year-picker trigger.                                |
| `Calendar.YearPickerGrid`             | Overlay year selection grid container.                                     |
| `Calendar.YearPickerGridBody`         | Body renderer for year grid cells.                                         |
| `Calendar.YearPickerCell`             | Individual year option cell.                                               |

### Calendar.Cell Render Props

When `Calendar.Cell` children is a function, React Aria render props are available:

| Prop             | Type      | Description                                 |
| ---------------- | --------- | ------------------------------------------- |
| `formattedDate`  | `string`  | Localized day label for the cell.           |
| `isSelected`     | `boolean` | Whether the date is selected.               |
| `isUnavailable`  | `boolean` | Whether the date is unavailable.            |
| `isDisabled`     | `boolean` | Whether the cell is disabled.               |
| `isOutsideMonth` | `boolean` | Whether the date belongs to adjacent month. |

</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/(date-and-time)/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, Label} from "@heroui/react";

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

```

### Anatomy

```tsx
import {DateField, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <DateField>
    <Label />
    <DateField.Group>
      <DateField.Input>
        {(segment) => <DateField.Segment segment={segment} />}
      </DateField.Input>
    </DateField.Group>
    <Description />
    <FieldError />
  </DateField>
)

```

> **DateField** combines label, date input, description, and error into a single accessible component.

### With Description

```tsx
"use client";

import {DateField, 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>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        <Description>Enter your date of birth</Description>
      </DateField>
      <DateField className="w-[256px]" name="appointment-date">
        <Label>Appointment date</Label>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        <Description>Enter a date for your appointment</Description>
      </DateField>
    </div>
  );
}

```

### Required Field

```tsx
"use client";

import {DateField, 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>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
      </DateField>
      <DateField isRequired className="w-[256px]" name="start-date">
        <Label>Start date</Label>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        <Description>Required field</Description>
      </DateField>
    </div>
  );
}

```

### Validation

Use `isInvalid` together with `FieldError` to surface validation messages.

```tsx
"use client";

import {DateField, 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>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        <FieldError>Please enter a valid date</FieldError>
      </DateField>
      <DateField isInvalid className="w-[256px]" name="invalid-date">
        <Label>Date</Label>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        <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, 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>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        {isInvalid ? (
          <FieldError>Date must be today or in the future</FieldError>
        ) : (
          <Description>Enter a date from today onwards</Description>
        )}
      </DateField>
    </div>
  );
}

```

### Granularity

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {CircleQuestion} from "@gravity-ui/icons";
import {DateField, Label, ListBox, Select, Tooltip} from "@heroui/react";
import {parseDate, parseZonedDateTime} from "@internationalized/date";
import {useState} from "react";

export function Granularity() {
  const granularityOptions = [
    {id: "day", label: "Day"},
    {id: "hour", label: "Hour"},
    {id: "minute", label: "Minute"},
    {id: "second", label: "Second"},
  ] as const;

const [granularity, setGranularity] = useState<"day" | "hour" | "minute" | "second">("day");

// Determine appropriate default value based on granularity
  let defaultValue: DateValue;

if (granularity === "day") {
    defaultValue = parseDate("2025-02-03");
  } else {
    // hour, minute, second
    defaultValue = parseZonedDateTime("2025-02-03T08:45:00[America/Los_Angeles]");
  }

return (
    <div className="flex gap-4">
      <DateField
        className="w-[256px]"
        defaultValue={defaultValue}
        granularity={granularity}
        name="granularity-date"
      >
        <Label>Appointment Date</Label>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
      </DateField>
      <div className="flex flex-col gap-1">
        <div className="flex items-center gap-2">
          <Label>Granularity</Label>
          <Tooltip delay={0}>
            <Tooltip.Trigger aria-label="Granularity information">
              <CircleQuestion className="size-4 text-muted" />
            </Tooltip.Trigger>
            <Tooltip.Content placement="bottom start">
              <p>
                Determines the smallest unit displayed in the date picker. By default, this is "day"
                for dates, and "minute" for times.
              </p>
            </Tooltip.Content>
          </Tooltip>
        </div>
        <Select
          className="w-[110px]"
          placeholder="Select granularity"
          value={granularity}
          variant="secondary"
          onChange={(value) => setGranularity(value as typeof granularity)}
        >
          <Select.Trigger>
            <Select.Value />
            <Select.Indicator />
          </Select.Trigger>
          <Select.Popover>
            <ListBox>
              {granularityOptions.map((option) => (
                <ListBox.Item key={option.id} id={option.id} textValue={option.label}>
                  {option.label}
                  <ListBox.ItemIndicator />
                </ListBox.Item>
              ))}
            </ListBox>
          </Select.Popover>
        </Select>
      </div>
    </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, 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>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        <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, 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>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        <Description>This date field is disabled</Description>
      </DateField>
      <DateField isDisabled className="w-[256px]" name="date-empty">
        <Label>Date</Label>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        <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, Label} from "@heroui/react";

export function WithPrefixIcon() {
  return (
    <DateField className="w-[256px]" name="date">
      <Label>Date</Label>
      <DateField.Group>
        <DateField.Prefix>
          <Calendar className="size-4 text-muted" />
        </DateField.Prefix>
        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
      </DateField.Group>
    </DateField>
  );
}

```

```tsx
"use client";

import {Calendar} from "@gravity-ui/icons";
import {DateField, Label} from "@heroui/react";

export function WithSuffixIcon() {
  return (
    <DateField className="w-[256px]" name="date">
      <Label>Date</Label>
      <DateField.Group>
        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        <DateField.Suffix>
          <Calendar className="size-4 text-muted" />
        </DateField.Suffix>
      </DateField.Group>
    </DateField>
  );
}

```

```tsx
"use client";

import {Calendar, ChevronDown} from "@gravity-ui/icons";
import {DateField, Description, Label} from "@heroui/react";

export function WithPrefixAndSuffix() {
  return (
    <DateField className="w-[256px]" name="date">
      <Label>Date</Label>
      <DateField.Group>
        <DateField.Prefix>
          <Calendar className="size-4 text-muted" />
        </DateField.Prefix>
        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        <DateField.Suffix>
          <ChevronDown className="size-4 text-muted" />
        </DateField.Suffix>
      </DateField.Group>
      <Description>Enter a date</Description>
    </DateField>
  );
}

```

### Full Width

```tsx
"use client";

import {Calendar, ChevronDown} from "@gravity-ui/icons";
import {DateField, Label} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-4">
      <DateField fullWidth name="date">
        <Label>Date</Label>
        <DateField.Group>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
      </DateField>
      <DateField fullWidth name="date-icons">
        <Label>Date</Label>
        <DateField.Group>
          <DateField.Prefix>
            <Calendar className="size-4 text-muted" />
          </DateField.Prefix>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
          <DateField.Suffix>
            <ChevronDown className="size-4 text-muted" />
          </DateField.Suffix>
        </DateField.Group>
      </DateField>
    </div>
  );
}

```

### Variants

The DateField.Group component supports two visual variants:

* **`primary`** (default) - Standard styling with shadow, suitable for most use cases
* **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components

```tsx
"use client";

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

export function Variants() {
  return (
    <div className="flex flex-col gap-4">
      <DateField className="w-[256px]" name="primary-date">
        <Label>Primary variant</Label>
        <DateField.Group variant="primary">
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
      </DateField>
      <DateField className="w-[256px]" name="secondary-date">
        <Label>Secondary variant</Label>
        <DateField.Group variant="secondary">
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
      </DateField>
    </div>
  );
}

```

### In Surface

When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on DateField.Group to apply the lower emphasis variant suitable for surface backgrounds.

```tsx
"use client";

import {Calendar} from "@gravity-ui/icons";
import {DateField, 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>
        <DateField.Group variant="secondary">
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        <Description>Enter a date</Description>
      </DateField>
      <DateField className="w-full" name="date-2">
        <Label>Appointment date</Label>
        <DateField.Group variant="secondary">
          <DateField.Prefix>
            <Calendar className="size-4 text-muted" />
          </DateField.Prefix>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        <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, 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>
        <DateField.Group>
          <DateField.Prefix>
            <Calendar className="size-4 text-muted" />
          </DateField.Prefix>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        </DateField.Group>
        {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

* **DatePicker**: Composable date picker with date field trigger and calendar popover
* **Calendar**: Interactive month grid for selecting dates
* **Label**: Accessible label for form controls

### Custom Render Function

```tsx
"use client";

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

export function CustomRenderFunction() {
  return (
    <DateField
      className="w-[256px]"
      name="date"
      render={(props) => <div {...props} data-custom="date-field" />}
    >
      <Label render={(props) => <span {...props} data-custom="date-field-label" />}>Date</Label>
      <DateField.Group render={(props) => <div {...props} data-custom="date-field-group" />}>
        <DateField.Input render={(props) => <div {...props} data-custom="date-field-input" />}>
          {(segment) => <DateField.Segment segment={segment} />}
        </DateField.Input>
      </DateField.Group>
    </DateField>
  );
}

```

## Styling

### Passing Tailwind CSS classes

```tsx
import {DateField, Label, 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>
      <DateField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
        <DateField.Input>
          {(segment) => <DateField.Segment segment={segment} />}
        </DateField.Input>
      </DateField.Group>
      <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. DateField.Group styling is documented below in the API Reference section.

### Interactive States

DateField automatically manages these data attributes based on its state:

## 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, DateField.Group, 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.                                    |
| `render`    | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DateFieldRenderProps>`   | -       | Overrides the default DOM element with a custom render function.    |

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

### Composition Components

DateField works with these separate components that should be imported and used directly:

* **Label** - Field label component from `@heroui/react`
* **DateField.Group** - Date input group component (documented below)
* **DateField.Input** - Input component with segmented editing from `@heroui/react`
* **DateField.Segment** - Individual date segment (year, month, day, etc.)
* **DateField.Prefix** / **DateField.Suffix** - Prefix and suffix slots for the input group
* **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, Description, FieldError} from '@heroui/react';

<DateField
  isRequired
  isInvalid={hasError}
  minValue={today(getLocalTimeZone())}
  value={date}
  onChange={setDate}
>
  <Label>Appointment Date</Label>
  <DateField.Group>
    <DateField.Input>
      {(segment) => <DateField.Segment segment={segment} />}
    </DateField.Input>
  </DateField.Group>
  <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:

### DateField.Group Props

DateField.Group 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                                                                                               |
| `variant`   | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |

### DateField.Input Props

DateField.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.                                                                                                             |
| `variant`   | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |

The `DateField.Input` component accepts a render prop function that receives date segments. Each segment represents a part of the date (year, month, day, etc.).

### DateField.Segment Props

DateField.Segment accepts all props from React Aria's `DateSegment` component:

| Prop        | Type          | Default | Description                                                   |
| ----------- | ------------- | ------- | ------------------------------------------------------------- |
| `segment`   | `DateSegment` | -       | The date segment object from the DateField.Input render prop. |
| `className` | `string`      | -       | Tailwind classes merged with the component styles.            |

### DateField.Prefix Props

DateField.Prefix accepts standard HTML `div` attributes:

### DateField.Suffix Props

DateField.Suffix accepts standard HTML `div` attributes:

## DateField.Group 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;
  }
}

```

### DateField.Group 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

### DateField.Group 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/date-picker">
# DatePicker

**Category**: react
**URL**: https://v3.heroui.com/docs/react/components/date-picker
**Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(date-and-time)/date-picker.mdx
> Composable date picker built on React Aria DatePicker with DateField and Calendar composition

## Import

```tsx
import { DatePicker, DateField, Calendar, Label } from '@heroui/react';

```

### Usage

```tsx
"use client";

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

export function Basic() {
  return (
    <DatePicker className="w-64" name="date">
      <Label>Date</Label>
      <DateField.Group fullWidth>
        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        <DateField.Suffix>
          <DatePicker.Trigger>
            <DatePicker.TriggerIndicator />
          </DatePicker.Trigger>
        </DateField.Suffix>
      </DateField.Group>
      <DatePicker.Popover>
        <Calendar aria-label="Event date">
          <Calendar.Header>
            <Calendar.YearPickerTrigger>
              <Calendar.YearPickerTriggerHeading />
              <Calendar.YearPickerTriggerIndicator />
            </Calendar.YearPickerTrigger>
            <Calendar.NavButton slot="previous" />
            <Calendar.NavButton slot="next" />
          </Calendar.Header>
          <Calendar.Grid>
            <Calendar.GridHeader>
              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
            </Calendar.GridHeader>
            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
          </Calendar.Grid>
          <Calendar.YearPickerGrid>
            <Calendar.YearPickerGridBody>
              {({year}) => <Calendar.YearPickerCell year={year} />}
            </Calendar.YearPickerGridBody>
          </Calendar.YearPickerGrid>
        </Calendar>
      </DatePicker.Popover>
    </DatePicker>
  );
}

```

### Anatomy

`DatePicker` follows a composition-first API. Compose `DateField` and `Calendar` explicitly to control structure and styling.

```tsx
import {Calendar, DateField, DatePicker, Label} from '@heroui/react';

export default () => (
  <DatePicker>
    <Label />
    <DateField.Group>
      <DateField.Input>
        {(segment) => <DateField.Segment segment={segment} />}
      </DateField.Input>
      <DateField.Suffix>
        <DatePicker.Trigger>
          <DatePicker.TriggerIndicator />
        </DatePicker.Trigger>
      </DateField.Suffix>
    </DateField.Group>
    <DatePicker.Popover>
      <Calendar aria-label="Choose date">
        <Calendar.Header>
          <Calendar.YearPickerTrigger>
            <Calendar.YearPickerTriggerHeading />
            <Calendar.YearPickerTriggerIndicator />
          </Calendar.YearPickerTrigger>
          <Calendar.NavButton slot="previous" />
          <Calendar.NavButton slot="next" />
        </Calendar.Header>
        <Calendar.Grid>
          <Calendar.GridHeader>
            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
          </Calendar.GridHeader>
          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
        </Calendar.Grid>
      </Calendar>
    </DatePicker.Popover>
  </DatePicker>
)

```

### Controlled

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {Button, Calendar, DateField, DatePicker, Description, Label} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";
import {useState} from "react";

export function Controlled() {
  const [value, setValue] = useState<DateValue | null>(today(getLocalTimeZone()));

return (
    <div className="flex w-64 flex-col gap-4">
      <DatePicker name="date" value={value} onChange={setValue}>
        <Label>Date</Label>
        <DateField.Group fullWidth>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
          <DateField.Suffix>
            <DatePicker.Trigger>
              <DatePicker.TriggerIndicator />
            </DatePicker.Trigger>
          </DateField.Suffix>
        </DateField.Group>
        <DatePicker.Popover>
          <Calendar aria-label="Event date">
            <Calendar.Header>
              <Calendar.YearPickerTrigger>
                <Calendar.YearPickerTriggerHeading />
                <Calendar.YearPickerTriggerIndicator />
              </Calendar.YearPickerTrigger>
              <Calendar.NavButton slot="previous" />
              <Calendar.NavButton slot="next" />
            </Calendar.Header>
            <Calendar.Grid>
              <Calendar.GridHeader>
                {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
              </Calendar.GridHeader>
              <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
            </Calendar.Grid>
            <Calendar.YearPickerGrid>
              <Calendar.YearPickerGridBody>
                {({year}) => <Calendar.YearPickerCell year={year} />}
              </Calendar.YearPickerGridBody>
            </Calendar.YearPickerGrid>
          </Calendar>
        </DatePicker.Popover>
      </DatePicker>
      <Description>Current value: {value ? value.toString() : "(empty)"}</Description>
      <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>
  );
}

```

### Validation

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {Calendar, DateField, DatePicker, 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 currentDate = today(getLocalTimeZone());
  const isInvalid = value != null && value.compare(currentDate) < 0;

return (
    <DatePicker
      isRequired
      className="w-64"
      isInvalid={isInvalid}
      minValue={currentDate}
      name="date"
      value={value}
      onChange={setValue}
    >
      <Label>Appointment date</Label>
      <DateField.Group fullWidth>
        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        <DateField.Suffix>
          <DatePicker.Trigger>
            <DatePicker.TriggerIndicator />
          </DatePicker.Trigger>
        </DateField.Suffix>
      </DateField.Group>
      <FieldError>Date must be today or in the future.</FieldError>
      <DatePicker.Popover>
        <Calendar aria-label="Event date">
          <Calendar.Header>
            <Calendar.YearPickerTrigger>
              <Calendar.YearPickerTriggerHeading />
              <Calendar.YearPickerTriggerIndicator />
            </Calendar.YearPickerTrigger>
            <Calendar.NavButton slot="previous" />
            <Calendar.NavButton slot="next" />
          </Calendar.Header>
          <Calendar.Grid>
            <Calendar.GridHeader>
              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
            </Calendar.GridHeader>
            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
          </Calendar.Grid>
          <Calendar.YearPickerGrid>
            <Calendar.YearPickerGridBody>
              {({year}) => <Calendar.YearPickerCell year={year} />}
            </Calendar.YearPickerGridBody>
          </Calendar.YearPickerGrid>
        </Calendar>
      </DatePicker.Popover>
    </DatePicker>
  );
}

```

### Format Options

Control how DatePicker values are displayed with props such as `granularity`, `hourCycle`, `hideTimeZone`, and `shouldForceLeadingZeros`.

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {Calendar, DateField, DatePicker, Label, ListBox, Select, Switch} from "@heroui/react";
import {parseDate, parseZonedDateTime} from "@internationalized/date";
import {useMemo, useState} from "react";

type Granularity = "day" | "hour" | "minute" | "second";
type HourCycle = 12 | 24;
const granularityOptions: {label: string; value: Granularity}[] = [
  {label: "Day", value: "day"},
  {label: "Hour", value: "hour"},
  {label: "Minute", value: "minute"},
  {label: "Second", value: "second"},
];
const hourCycleOptions: {label: string; value: HourCycle}[] = [
  {label: "12-hour", value: 12},
  {label: "24-hour", value: 24},
];

export function FormatOptions() {
  const [granularity, setGranularity] = useState<Granularity>("day");
  const [hourCycle, setHourCycle] = useState<HourCycle>(12);
  const [hideTimeZone, setHideTimeZone] = useState(false);
  const [shouldForceLeadingZeros, setShouldForceLeadingZeros] = useState(false);

const defaultValue = useMemo<DateValue>(() => {
    if (granularity === "day") {
      return parseDate("2025-02-03");
    }

return parseZonedDateTime("2025-02-03T08:45:00[America/Los_Angeles]");
  }, [granularity]);

return (
    <div className="flex flex-col gap-4">
      <DatePicker
        key={granularity}
        className="min-w-64"
        defaultValue={defaultValue}
        granularity={granularity}
        hideTimeZone={hideTimeZone}
        hourCycle={hourCycle}
        name="date"
        shouldForceLeadingZeros={shouldForceLeadingZeros}
      >
        <Label>Date and time</Label>
        <DateField.Group fullWidth>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
          <DateField.Suffix>
            <DatePicker.Trigger>
              <DatePicker.TriggerIndicator />
            </DatePicker.Trigger>
          </DateField.Suffix>
        </DateField.Group>
        <DatePicker.Popover>
          <Calendar aria-label="Event date">
            <Calendar.Header>
              <Calendar.YearPickerTrigger>
                <Calendar.YearPickerTriggerHeading />
                <Calendar.YearPickerTriggerIndicator />
              </Calendar.YearPickerTrigger>
              <Calendar.NavButton slot="previous" />
              <Calendar.NavButton slot="next" />
            </Calendar.Header>
            <Calendar.Grid>
              <Calendar.GridHeader>
                {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
              </Calendar.GridHeader>
              <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
            </Calendar.Grid>
            <Calendar.YearPickerGrid>
              <Calendar.YearPickerGridBody>
                {({year}) => <Calendar.YearPickerCell year={year} />}
              </Calendar.YearPickerGridBody>
            </Calendar.YearPickerGrid>
          </Calendar>
        </DatePicker.Popover>
      </DatePicker>

<div className="flex flex-wrap gap-4">
        <div className="flex flex-col gap-1">
          <Label>Granularity</Label>
          <Select
            className="w-[120px]"
            value={granularity}
            variant="secondary"
            onChange={(value) => setGranularity(value as Granularity)}
          >
            <Select.Trigger>
              <Select.Value />
              <Select.Indicator />
            </Select.Trigger>
            <Select.Popover>
              <ListBox>
                {granularityOptions.map((option) => (
                  <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
                    {option.label}
                    <ListBox.ItemIndicator />
                  </ListBox.Item>
                ))}
              </ListBox>
            </Select.Popover>
          </Select>
        </div>

<div className="flex flex-col gap-1">
          <Label>Hour cycle</Label>
          <Select
            className="w-[120px]"
            value={hourCycle}
            variant="secondary"
            onChange={(value) => setHourCycle(Number(value) as HourCycle)}
          >
            <Select.Trigger>
              <Select.Value />
              <Select.Indicator />
            </Select.Trigger>
            <Select.Popover>
              <ListBox>
                {hourCycleOptions.map((option) => (
                  <ListBox.Item key={option.value} id={option.value} textValue={option.label}>
                    {option.label}
                    <ListBox.ItemIndicator />
                  </ListBox.Item>
                ))}
              </ListBox>
            </Select.Popover>
          </Select>
        </div>
      </div>

<div className="flex flex-col gap-2">
        <Switch isSelected={hideTimeZone} onChange={setHideTimeZone}>
          <Switch.Control>
            <Switch.Thumb />
          </Switch.Control>
          <Label className="text-sm">Hide timezone</Label>
        </Switch>
        <Switch isSelected={shouldForceLeadingZeros} onChange={setShouldForceLeadingZeros}>
          <Switch.Control>
            <Switch.Thumb />
          </Switch.Control>
          <Label className="text-sm">Force leading zeros</Label>
        </Switch>
      </div>
    </div>
  );
}

```

### Disabled

```tsx
"use client";

import {Calendar, DateField, DatePicker, Description, Label} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";

export function Disabled() {
  return (
    <DatePicker isDisabled className="w-64" name="date" value={today(getLocalTimeZone())}>
      <Label>Date</Label>
      <DateField.Group fullWidth>
        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        <DateField.Suffix>
          <DatePicker.Trigger>
            <DatePicker.TriggerIndicator />
          </DatePicker.Trigger>
        </DateField.Suffix>
      </DateField.Group>
      <Description>This date picker is disabled.</Description>
      <DatePicker.Popover>
        <Calendar aria-label="Event date">
          <Calendar.Header>
            <Calendar.YearPickerTrigger>
              <Calendar.YearPickerTriggerHeading />
              <Calendar.YearPickerTriggerIndicator />
            </Calendar.YearPickerTrigger>
            <Calendar.NavButton slot="previous" />
            <Calendar.NavButton slot="next" />
          </Calendar.Header>
          <Calendar.Grid>
            <Calendar.GridHeader>
              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
            </Calendar.GridHeader>
            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
          </Calendar.Grid>
          <Calendar.YearPickerGrid>
            <Calendar.YearPickerGridBody>
              {({year}) => <Calendar.YearPickerCell year={year} />}
            </Calendar.YearPickerGridBody>
          </Calendar.YearPickerGrid>
        </Calendar>
      </DatePicker.Popover>
    </DatePicker>
  );
}

```

### Custom Indicator

`DatePicker.TriggerIndicator` renders the default `IconCalendar` when no children are provided. Pass children to replace it.

```tsx
"use client";

import {Calendar, DateField, DatePicker, Description, Label} from "@heroui/react";
import {Icon} from "@iconify/react";

export function WithCustomIndicator() {
  return (
    <DatePicker className="w-64" name="date">
      <Label>Date</Label>
      <DateField.Group fullWidth>
        <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
        <DateField.Suffix>
          <DatePicker.Trigger>
            <DatePicker.TriggerIndicator>
              <Icon className="size-4" icon="gravity-ui:chevron-down" />
            </DatePicker.TriggerIndicator>
          </DatePicker.Trigger>
        </DateField.Suffix>
      </DateField.Group>
      <Description>Replace the default calendar icon by passing custom children.</Description>
      <DatePicker.Popover>
        <Calendar aria-label="Event date">
          <Calendar.Header>
            <Calendar.YearPickerTrigger>
              <Calendar.YearPickerTriggerHeading />
              <Calendar.YearPickerTriggerIndicator />
            </Calendar.YearPickerTrigger>
            <Calendar.NavButton slot="previous" />
            <Calendar.NavButton slot="next" />
          </Calendar.Header>
          <Calendar.Grid>
            <Calendar.GridHeader>
              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
            </Calendar.GridHeader>
            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
          </Calendar.Grid>
          <Calendar.YearPickerGrid>
            <Calendar.YearPickerGridBody>
              {({year}) => <Calendar.YearPickerCell year={year} />}
            </Calendar.YearPickerGridBody>
          </Calendar.YearPickerGrid>
        </Calendar>
      </DatePicker.Popover>
    </DatePicker>
  );
}

```

### Form Example

```tsx
"use client";

import type {DateValue} from "@internationalized/date";

import {
  Button,
  Calendar,
  DateField,
  DatePicker,
  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 currentDate = today(getLocalTimeZone());
  const isInvalid = value != null && value.compare(currentDate) < 0;

const handleSubmit = (event: React.FormEvent) => {
    event.preventDefault();

if (!value || isInvalid) {
      return;
    }

setIsSubmitting(true);

setTimeout(() => {
      setValue(null);
      setIsSubmitting(false);
    }, 1200);
  };

return (
    <Form className="flex w-64 flex-col gap-3" onSubmit={handleSubmit}>
      <DatePicker
        isRequired
        isInvalid={isInvalid}
        minValue={currentDate}
        name="appointmentDate"
        value={value}
        onChange={setValue}
      >
        <Label>Appointment date</Label>
        <DateField.Group fullWidth>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
          <DateField.Suffix>
            <DatePicker.Trigger>
              <DatePicker.TriggerIndicator />
            </DatePicker.Trigger>
          </DateField.Suffix>
        </DateField.Group>
        {isInvalid ? (
          <FieldError>Date must be today or in the future.</FieldError>
        ) : (
          <Description>Choose a valid appointment date.</Description>
        )}
        <DatePicker.Popover>
          <Calendar aria-label="Event date">
            <Calendar.Header>
              <Calendar.YearPickerTrigger>
                <Calendar.YearPickerTriggerHeading />
                <Calendar.YearPickerTriggerIndicator />
              </Calendar.YearPickerTrigger>
              <Calendar.NavButton slot="previous" />
              <Calendar.NavButton slot="next" />
            </Calendar.Header>
            <Calendar.Grid>
              <Calendar.GridHeader>
                {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
              </Calendar.GridHeader>
              <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
            </Calendar.Grid>
            <Calendar.YearPickerGrid>
              <Calendar.YearPickerGridBody>
                {({year}) => <Calendar.YearPickerCell year={year} />}
              </Calendar.YearPickerGridBody>
            </Calendar.YearPickerGrid>
          </Calendar>
        </DatePicker.Popover>
      </DatePicker>
      <Button
        className="w-full"
        isDisabled={!value || isInvalid}
        isPending={isSubmitting}
        type="submit"
      >
        {isSubmitting ? "Submitting..." : "Submit"}
      </Button>
    </Form>
  );
}

```

### International Calendar

By default, DatePicker displays dates using the calendar system for the user's locale. You can override this by wrapping your DatePicker with `I18nProvider` and setting the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string).

The example below shows the Indian calendar system:

```tsx
"use client";

import {Calendar, DateField, DatePicker, Label} from "@heroui/react";
import {getLocalTimeZone, today} from "@internationalized/date";
import {I18nProvider} from "react-aria-components";

export function InternationalCalendar() {
  return (
    <I18nProvider locale="hi-IN-u-ca-indian">
      <DatePicker
        className="w-64"
        defaultValue={today(getLocalTimeZone())}
        name="international-date"
      >
        <Label>Event date</Label>
        <DateField.Group fullWidth>
          <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input>
          <DateField.Suffix>
            <DatePicker.Trigger>
              <DatePicker.TriggerIndicator />
            </DatePicker.Trigger>
          </DateField.Suffix>
        </DateField.Group>
        <DatePicker.Popover>
          <Calendar aria-label="Event date">
            <Calendar.Header>
              <Calendar.YearPickerTrigger>
                <Calendar.YearPickerTriggerHeading />
                <Calendar.YearPickerTriggerIndicator />
              </Calendar.YearPickerTrigger>
              <Calendar.NavButton slot="previous" />
              <Calendar.NavButton slot="next" />
            </Calendar.Header>
            <Calendar.Grid>
              <Calendar.GridHeader>
                {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
              </Calendar.GridHeader>
              <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
            </Calendar.Grid>
            <Calendar.YearPickerGrid>
              <Calendar.YearPickerGridBody>
                {({year}) => <Calendar.YearPickerCell year={year} />}
              </Calendar.YearPickerGridBody>
            </Calendar.YearPickerGrid>
          </Calendar>
        </DatePicker.Popover>
      </DatePicker>
    </I18nProvider>
  );
}

```

For a complete list of supported calendar systems and their identifiers, see:

### Custom Render Function

```tsx
"use client";

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

export function CustomRenderFunction() {
  return (
    <DatePicker
      className="w-64"
      name="date"
      render={(props) => <div {...props} data-custom="date-picker" />}
    >
      <Label render={(props) => <span {...props} data-custom="date-picker-label" />}>Date</Label>
      <DateField.Group
        fullWidth
        render={(props) => <div {...props} data-custom="date-field-group" />}
      >
        <DateField.Input render={(props) => <div {...props} data-custom="date-field-input" />}>
          {(segment) => (
            <DateField.Segment
              render={(props) => <span {...props} data-custom="date-field-segment" />}
              segment={segment}
            />
          )}
        </DateField.Input>
        <DateField.Suffix>
          <DatePicker.Trigger
            render={(props) => <button {...props} data-custom="date-picker-trigger" />}
          >
            <DatePicker.TriggerIndicator />
          </DatePicker.Trigger>
        </DateField.Suffix>
      </DateField.Group>
      <DatePicker.Popover>
        <Calendar aria-label="Event date">
          <Calendar.Header>
            <Calendar.YearPickerTrigger>
              <Calendar.YearPickerTriggerHeading />
              <Calendar.YearPickerTriggerIndicator />
            </Calendar.YearPickerTrigger>
            <Calendar.NavButton slot="previous" />
            <Calendar.NavButton slot="next" />
          </Calendar.Header>
          <Calendar.Grid>
            <Calendar.GridHeader>
              {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
            </Calendar.GridHeader>
            <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
          </Calendar.Grid>
          <Calendar.YearPickerGrid>
            <Calendar.YearPickerGridBody>
              {({year}) => <Calendar.YearPickerCell year={year} />}
            </Calendar.YearPickerGridBody>
          </Calendar.YearPickerGrid>
        </Calendar>
      </DatePicker.Popover>
    </DatePicker>
  );
}

```

## Related Components

* **Calendar**: Interactive month grid for selecting dates
* **DateField**: Date input field with labels, descriptions, and validation
* **TimeField**: Time input field with labels, descriptions, and validation

## Styling

### Passing Tailwind CSS classes

You can style each composition part independently:

```tsx
import {Calendar, DateField, DatePicker, Label} from '@heroui/react';

function CustomDatePicker() {
  return (
    <DatePicker className="w-[320px] gap-2">
      <Label className="text-sm font-semibold">Date</Label>
      <DateField.Group className="rounded-xl border border-border/60 bg-surface" fullWidth variant="secondary">
        <DateField.Input>
          {(segment) => <DateField.Segment segment={segment} />}
        </DateField.Input>
        <DateField.Suffix>
          <DatePicker.Trigger className="w-full">
            <DatePicker.TriggerIndicator className="text-default-600" />
          </DatePicker.Trigger>
        </DateField.Suffix>
      </DateField.Group>
      <DatePicker.Popover className="rounded-xl p-2">
        <Calendar aria-label="Custom date picker calendar">
          {/* Calendar parts */}
        </Calendar>
      </DatePicker.Popover>
    </DatePicker>
  );
}

```

### Customizing the component classes

To customize DatePicker base classes, use `@layer components`.

```css
@layer components {
  .date-picker {
    @apply inline-flex flex-col gap-1;
  }

.date-picker__trigger {
    @apply inline-flex items-center justify-between;
  }

.date-picker__trigger-indicator {
    @apply text-muted;
  }

.date-picker__popover {
    @apply min-w-[var(--trigger-width)] p-0;
  }
}

```

HeroUI follows [BEM](https://getbem.com/) naming for reusable customization.

### CSS Classes

DatePicker uses these classes in `packages/styles/components/date-picker.css`:

* `.date-picker` - Root wrapper.
* `.date-picker__trigger` - Trigger part that opens the popover.
* `.date-picker__trigger-indicator` - Default/custom indicator slot.
* `.date-picker__popover` - Popover content wrapper.

### Interactive States

DatePicker supports React Aria data attributes and pseudo states:

* **Open**: `[data-open="true"]` on trigger.
* **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]` on trigger.
* **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]` on trigger.
* **Hover**: `:hover` or `[data-hovered="true"]` on trigger.

## API Reference

### DatePicker Props

DatePicker inherits all props from React Aria [DatePicker](https://react-aria.adobe.com/DatePicker.md).

| Prop           | Type                                                        | Default | Description                                       |
| -------------- | ----------------------------------------------------------- | ------- | ------------------------------------------------- |
| `value`        | `DateValue \| null`                                         | -       | Controlled selected date value.                   |
| `defaultValue` | `DateValue \| null`                                         | -       | Default selected value in uncontrolled mode.      |
| `onChange`     | `(value: DateValue \| null) => void`                        | -       | Called when selected date changes.                |
| `isOpen`       | `boolean`                                                   | -       | Controlled popover open state.                    |
| `defaultOpen`  | `boolean`                                                   | `false` | Initial popover open state.                       |
| `onOpenChange` | `(isOpen: boolean) => void`                                 | -       | Called when popover open state changes.           |
| `isDisabled`   | `boolean`                                                   | `false` | Disables date selection and trigger interactions. |
| `isInvalid`    | `boolean`                                                   | -       | Marks the field as invalid for validation state.  |
| `minValue`     | `DateValue`                                                 | -       | Minimum selectable date.                          |
| `maxValue`     | `DateValue`                                                 | -       | Maximum selectable date.                          |
| `name`         | `string`                                                    | -       | Name used for HTML form submission.               |
| `children`     | `ReactNode \| (values: DatePickerRenderProps) => ReactNode` | -       | Composed content or render function.              |

### Composition Parts

| Component                     | Description                                                 |
| ----------------------------- | ----------------------------------------------------------- |
| `DatePicker.Root`             | Root date picker container and state owner.                 |
| `DatePicker.Trigger`          | Trigger button, usually rendered inside `DateField.Suffix`. |
| `DatePicker.TriggerIndicator` | Indicator slot with default calendar icon.                  |
| `DatePicker.Popover`          | Popover wrapper for `Calendar` content.                     |

</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/(date-and-time)/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 {Label, TimeField} from "@heroui/react";

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

```

### Anatomy

```tsx
import {TimeField, Label, Description, FieldError} from '@heroui/react';

export default () => (
  <TimeField>
    <Label />
    <TimeField.Group>
      <TimeField.Input>
        {(segment) => <TimeField.Segment segment={segment} />}
      </TimeField.Input>
    </TimeField.Group>
    <Description />
    <FieldError />
  </TimeField>
)

```

> **TimeField** combines label, time input, description, and error into a single accessible component.

### With Description

```tsx
"use client";

import {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>
        <TimeField.Group>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        <Description>Enter the start time</Description>
      </TimeField>
      <TimeField className="w-[256px]" name="end-time">
        <Label>End time</Label>
        <TimeField.Group>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        <Description>Enter the end time</Description>
      </TimeField>
    </div>
  );
}

```

### Required Field

```tsx
"use client";

import {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>
        <TimeField.Group>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
      </TimeField>
      <TimeField isRequired className="w-[256px]" name="appointment-time">
        <Label>Appointment time</Label>
        <TimeField.Group>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        <Description>Required field</Description>
      </TimeField>
    </div>
  );
}

```

### Validation

Use `isInvalid` together with `FieldError` to surface validation messages.

```tsx
"use client";

import {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>
        <TimeField.Group>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        <FieldError>Please enter a valid time</FieldError>
      </TimeField>
      <TimeField isInvalid className="w-[256px]" name="invalid-time">
        <Label>Time</Label>
        <TimeField.Group>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        <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 {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>
        <TimeField.Group>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        {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, 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>
        <TimeField.Group>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        <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 {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>
        <TimeField.Group>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        <Description>This time field is disabled</Description>
      </TimeField>
      <TimeField isDisabled className="w-[256px]" name="time-empty">
        <Label>Time</Label>
        <TimeField.Group>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        <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 {Label, TimeField} from "@heroui/react";

export function WithPrefixIcon() {
  return (
    <TimeField className="w-[256px]" name="time">
      <Label>Time</Label>
      <TimeField.Group>
        <TimeField.Prefix>
          <Clock className="size-4 text-muted" />
        </TimeField.Prefix>
        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
      </TimeField.Group>
    </TimeField>
  );
}

```

```tsx
"use client";

import {Clock} from "@gravity-ui/icons";
import {Label, TimeField} from "@heroui/react";

export function WithSuffixIcon() {
  return (
    <TimeField className="w-[256px]" name="time">
      <Label>Time</Label>
      <TimeField.Group>
        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        <TimeField.Suffix>
          <Clock className="size-4 text-muted" />
        </TimeField.Suffix>
      </TimeField.Group>
    </TimeField>
  );
}

```

```tsx
"use client";

import {ChevronDown, Clock} from "@gravity-ui/icons";
import {Description, Label, TimeField} from "@heroui/react";

export function WithPrefixAndSuffix() {
  return (
    <TimeField className="w-[256px]" name="time">
      <Label>Time</Label>
      <TimeField.Group>
        <TimeField.Prefix>
          <Clock className="size-4 text-muted" />
        </TimeField.Prefix>
        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        <TimeField.Suffix>
          <ChevronDown className="size-4 text-muted" />
        </TimeField.Suffix>
      </TimeField.Group>
      <Description>Enter a time</Description>
    </TimeField>
  );
}

```

### Full Width

```tsx
"use client";

import {ChevronDown, Clock} from "@gravity-ui/icons";
import {Label, TimeField} from "@heroui/react";

export function FullWidth() {
  return (
    <div className="w-[400px] space-y-4">
      <TimeField fullWidth name="time">
        <Label>Time</Label>
        <TimeField.Group fullWidth>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
      </TimeField>
      <TimeField fullWidth name="time-icons">
        <Label>Time</Label>
        <TimeField.Group fullWidth>
          <TimeField.Prefix>
            <Clock className="size-4 text-muted" />
          </TimeField.Prefix>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
          <TimeField.Suffix>
            <ChevronDown className="size-4 text-muted" />
          </TimeField.Suffix>
        </TimeField.Group>
      </TimeField>
    </div>
  );
}

```

### On Surface

When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on TimeField.Group to apply the lower emphasis variant suitable for surface backgrounds.

```tsx
"use client";

import {Clock} from "@gravity-ui/icons";
import {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>
        <TimeField.Group variant="secondary">
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        <Description>Enter a time</Description>
      </TimeField>
      <TimeField className="w-full" name="time-2">
        <Label>Appointment time</Label>
        <TimeField.Group variant="secondary">
          <TimeField.Prefix>
            <Clock className="size-4 text-muted" />
          </TimeField.Prefix>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        <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, 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>
        <TimeField.Group>
          <TimeField.Prefix>
            <Clock className="size-4 text-muted" />
          </TimeField.Prefix>
          <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
        </TimeField.Group>
        {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

### Custom Render Function

```tsx
"use client";

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

export function CustomRenderFunction() {
  return (
    <TimeField
      className="w-[256px]"
      name="time"
      render={(props) => <div {...props} data-custom="foo" />}
    >
      <Label>Time</Label>
      <TimeField.Group>
        <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input>
      </TimeField.Group>
    </TimeField>
  );
}

```

## Styling

### Passing Tailwind CSS classes

```tsx
import {TimeField, Label, 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>
      <TimeField.Group className="rounded-lg border border-border/60 bg-surface px-3 py-2">
        <TimeField.Input>
          {(segment) => <TimeField.Segment segment={segment} />}
        </TimeField.Input>
      </TimeField.Group>
      <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`)

> **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. TimeField.Group styling is documented below in the API Reference section.

### 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, TimeField.Group, 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.                                    |
| `render`    | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TimeFieldRenderProps>`   | -       | Overrides the default DOM element with a custom render function.    |

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

* **Label** - Field label component from `@heroui/react`
* **TimeField.Group** - Time input group component (documented below)
* **TimeField.Input** - Input component with segmented editing from `@heroui/react`
* **TimeField.Segment** - Individual time segment (hour, minute, second, etc.)
* **TimeField.Prefix** / **TimeField.Suffix** - Prefix and suffix slots for the input group
* **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 TimeField for composition:

```tsx
import {parseTime} from '@internationalized/date';
import {TimeField, Label, 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>
  <TimeField.Group>
    <TimeField.Input>
      {(segment) => <TimeField.Segment segment={segment} />}
    </TimeField.Input>
  </TimeField.Group>
  <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:

### TimeField.Group Props

TimeField.Group 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.                                                                                                                 |
| `variant`   | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |

### TimeField.Input Props

TimeField.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.                                                                                                             |
| `variant`   | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. |

The `TimeField.Input` component accepts a render prop function that receives date segments. Each segment represents a part of the time (hour, minute, second, etc.).

### TimeField.Segment Props

TimeField.Segment accepts all props from React Aria's `DateSegment` component:

| Prop        | Type          | Default | Description                                                   |
| ----------- | ------------- | ------- | ------------------------------------------------------------- |
| `segment`   | `DateSegment` | -       | The date segment object from the TimeField.Input render prop. |
| `className` | `string`      | -       | Tailwind classes merged with the component styles.            |

### TimeField.Prefix Props

TimeField.Prefix accepts standard HTML `div` attributes:

### TimeField.Suffix Props

TimeField.Suffix accepts standard HTML `div` attributes:

## TimeField.Group Styling