# 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 six visual variants for different emphasis levels. ```tsx ``` ### Feedback Variants Choose between highlight and ripple feedback effects for press interactions. ```tsx { /* Highlight feedback (default) */ } ; { /* Ripple feedback */ } ; { /* 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. ```tsx ``` ## Example ```tsx import { Button, useThemeColor } from 'heroui-native'; import { Ionicons } from '@expo/vector-icons'; import { View } from 'react-native'; export default function ButtonExample() { const themeColorAccentForeground = useThemeColor('accent-foreground'); const themeColorAccentSoftForeground = useThemeColor( 'accent-soft-foreground' ); const themeColorDangerForeground = useThemeColor('danger-foreground'); const themeColorDefaultForeground = useThemeColor('default-foreground'); return ( ); } ``` ## API Reference ### Button Button extends all props from [PressableFeedback](./pressable-feedback) component with additional button-specific props. | prop | type | default | description | | ------------ | -------------------------------------------------------------------------------- | ----------- | -------------------------------------------------------------- | | `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger' \| 'danger-soft'` | `'primary'` | Visual variant of the button | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size of the button | | `isIconOnly` | `boolean` | `false` | Whether the button displays an icon only (square aspect ratio) | For inherited props including `feedbackVariant`, `feedbackPosition`, `animation`, `isDisabled`, `className`, `children`, and all Pressable props, see [PressableFeedback API Reference](./pressable-feedback#api-reference). ### Button.Label | prop | type | default | description | | -------------- | ----------------- | ------- | ------------------------------------- | | `children` | `React.ReactNode` | - | Content to be rendered as label | | `className` | `string` | - | Additional CSS classes | | `...TextProps` | `TextProps` | - | All standard Text props are supported | ## Hooks ### useButton Hook to access the Button context values. Returns the button's size, variant, and disabled state. ```tsx import { useButton } from 'heroui-native'; const { size, variant, isDisabled } = useButton(); ``` #### Return Value | property | type | description | | ------------ | -------------------------------------------------------------------------------- | ------------------------------ | | `size` | `'sm' \| 'md' \| 'lg'` | Size of the button | | `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger' \| 'danger-soft'` | Visual variant of the button | | `isDisabled` | `boolean` | Whether the button is disabled | **Note:** This hook must be used within a `Button` component. It will throw an error if called outside of the button context. # 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 ); } ``` ## 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. # ErrorView **Category**: native **URL**: https://v3.heroui.com/docs/native/components/error-view **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(feedback)/error-view.mdx > Displays validation error message content with smooth animations. ## Import ```tsx import { ErrorView } from 'heroui-native'; ``` ## Anatomy ```tsx Error message content ``` * **ErrorView**: Main container that displays error messages with smooth animations. Accepts string children which are automatically wrapped with Text component, or custom React components for more complex layouts. Controls visibility through the `isInvalid` prop and supports custom entering/exiting animations. ## Usage ### Basic Usage The ErrorView component displays error messages when validation fails. ```tsx This field is required ``` ### Controlled Visibility Control when the error appears using the `isInvalid` prop. ```tsx const [isInvalid, setIsInvalid] = useState(false); 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 { ErrorView, TextField } from 'heroui-native'; import { useState } from 'react'; import { View } from 'react-native'; export default function ErrorViewExample() { const [email, setEmail] = useState(''); const [showError, setShowError] = useState(false); const isValidEmail = /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email); const handleBlur = () => { setShowError(email !== '' && !isValidEmail); }; return ( Email Address We'll use this to contact you Please enter a valid email address ); } ``` ## API Reference ### ErrorView | prop | type | default | description | | ---------------------- | ------------------------------ | ----------- | ------------------------------------------------------------------------ | | `children` | `React.ReactNode` | `undefined` | The content of the error field. String children are wrapped with Text | | `isInvalid` | `boolean` | `false` | Controls the visibility of the error field | | `animation` | `ErrorViewRootAnimation` | - | Animation configuration | | `className` | `string` | `undefined` | Additional CSS classes for the container | | `classNames` | `ElementSlots` | `undefined` | Additional CSS classes for different parts of the component | | `textProps` | `TextProps` | `undefined` | Additional props to pass to the Text component when children is a string | | `...AnimatedViewProps` | `AnimatedProps` | - | All Reanimated Animated.View props are supported | **classNames prop:** `ElementSlots` provides type-safe CSS classes for different parts of the error view component. Available slots: `container`, `text`. #### ErrorViewRootAnimation Animation configuration for error view root component. Can be: * `false` or `"disabled"`: Disable only root animations * `"disable-all"`: Disable all animations including children * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ---------------- | ----------------------- | ----------------------------------------------------------------------- | ---------------------------------------- | | `entering.value` | `EntryOrExitLayoutType` | `FadeIn`
`.duration(150)`
`.easing(Easing.out(Easing.ease))` | Custom entering animation for error view | | `exiting.value` | `EntryOrExitLayoutType` | `FadeOut`
`.duration(100)`
`.easing(Easing.out(Easing.ease))` | Custom exiting animation for error view | # 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. ); } ``` ## 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 | | ------------------------ | ----------------------- | --------------------------- | -------------------------------------- | | `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 ); } ``` ## API Reference ### Skeleton | prop | type | default | description | | ----------------------- | -------------------------------- | ----------- | ------------------------------------------------ | | `children` | `React.ReactNode` | - | Content to show when not loading | | `isLoading` | `boolean` | `true` | Whether the skeleton is currently loading | | `variant` | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | Animation variant | | `animation` | `SkeletonRootAnimation` | - | Animation configuration | | `className` | `string` | - | Additional CSS classes for styling | | `...Animated.ViewProps` | `AnimatedProps` | - | 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 | | ------------------------ | ----------------------- | --------------------------- | -------------------------------------- | | `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'} ); } ``` ## 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 | | ---------------- | ----------------------- | ---------------------------------------------------------------------- | ------------------------- | | `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 | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | #### SpinnerIndicatorAnimation Animation configuration for Spinner.Indicator component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ----------------- | ---------------------------- | --------------- | ------------------------------ | | `rotation.speed` | `number` | `1.1` | Rotation speed multiplier | | `rotation.easing` | `WithTimingConfig['easing']` | `Easing.linear` | Animation easing configuration | ### SpinnerIconProps | prop | type | default | description | | -------- | ------------------ | ---------------- | ------------------ | | `width` | `number \| string` | `24` | Width of the icon | | `height` | `number \| string` | `24` | Height of the icon | | `color` | `string` | `'currentColor'` | Color of the icon | # 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, Divider, FormField, Surface } from 'heroui-native'; import React from 'react'; import { View, Text } from 'react-native'; interface CheckboxFieldProps { isSelected: boolean; onSelectedChange: (value: boolean) => void; title: string; description: string; } const CheckboxField: React.FC = ({ 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 && } ))} ); } ``` ## API Reference ### Checkbox | prop | type | default | description | | ------------------- | ---------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- | | `children` | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | Child elements or render function to customize the checkbox | | `isSelected` | `boolean` | `undefined` | Whether the checkbox is currently selected | | `onSelectedChange` | `(isSelected: boolean) => void` | `undefined` | Callback fired when the checkbox selection state changes | | `isDisabled` | `boolean` | `false` | Whether the checkbox is disabled and cannot be interacted with | | `isInvalid` | `boolean` | `false` | Whether the checkbox is invalid (shows danger color) | | `isOnSurface` | `boolean` | `undefined` | Whether checkbox is on a surface background (auto-detected if not set) | | `hitSlop` | `number` | `6` | Hit slop for the pressable area | | `animation` | `CheckboxRootAnimation` | - | Animation configuration | | `className` | `string` | `undefined` | Additional CSS classes to apply | | `...PressableProps` | `PressableProps` | - | All standard React Native Pressable props are supported (except disabled) | #### CheckboxRenderProps | prop | type | description | | ------------ | --------- | -------------------------------- | | `isSelected` | `boolean` | Whether the checkbox is selected | | `isInvalid` | `boolean` | Whether the checkbox is invalid | | `isDisabled` | `boolean` | Whether the checkbox is disabled | #### CheckboxRootAnimation Animation configuration for checkbox root component. Can be: * `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 | | -------------------- | ------------------ | ------------------- | ---------------------------------- | | `scale.value` | `[number, number]` | `[1, 0.96]` | Scale values \[unpressed, pressed] | | `scale.timingConfig` | `WithTimingConfig` | `{ duration: 150 }` | Animation timing configuration | ### Checkbox.Indicator | prop | type | default | description | | ---------------------- | ---------------------------------------------------------------------- | ----------- | ----------------------------------------------------------- | | `children` | `React.ReactNode \| ((props: CheckboxRenderProps) => React.ReactNode)` | `undefined` | Content or render function for the checkbox indicator | | `className` | `string` | `undefined` | Additional CSS classes for the indicator | | `iconProps` | `CheckboxIndicatorIconProps` | `undefined` | Custom props for the default animated check icon | | `animation` | `CheckboxIndicatorAnimation` | - | Animation configuration | | `...AnimatedViewProps` | `AnimatedProps` | - | All standard React Native Animated View props are supported | #### CheckboxIndicatorIconProps Props for customizing the default animated check icon. | prop | type | description | | --------------- | -------- | ------------------------------------------------ | | `size` | `number` | Icon size | | `strokeWidth` | `number` | Icon stroke width | | `color` | `string` | Icon color (defaults to theme accent-foreground) | | `enterDuration` | `number` | Duration of enter animation (check appearing) | | `exitDuration` | `number` | Duration of exit animation (check disappearing) | #### CheckboxIndicatorAnimation Animation configuration for checkbox indicator component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | --------------------------- | ------------------ | ------------------- | -------------------------------------------- | | `opacity.value` | `[number, number]` | `[0, 1]` | Opacity values \[unselected, selected] | | `opacity.timingConfig` | `WithTimingConfig` | `{ duration: 100 }` | Animation timing configuration | | `borderRadius.value` | `[number, number]` | `[8, 0]` | Border radius values \[unselected, selected] | | `borderRadius.timingConfig` | `WithTimingConfig` | `{ duration: 50 }` | Animation timing configuration | | `translateX.value` | `[number, number]` | `[-4, 0]` | TranslateX values \[unselected, selected] | | `translateX.timingConfig` | `WithTimingConfig` | `{ duration: 100 }` | Animation timing configuration | | `scale.value` | `[number, number]` | `[0.8, 1]` | Scale values \[unselected, selected] | | `scale.timingConfig` | `WithTimingConfig` | `{ duration: 100 }` | Animation timing configuration | ## Hooks ### useCheckbox Hook to access checkbox context values within custom components or compound components. ```tsx import { useCheckbox } from 'heroui-native'; const CustomIndicator = () => { const { isSelected, isInvalid, isDisabled } = useCheckbox(); // ... your implementation }; ``` **Returns:** `UseCheckboxReturn` | property | type | description | | ------------------ | ---------------------------------------------- | -------------------------------------------------------------- | | `isSelected` | `boolean \| undefined` | Whether the checkbox is currently selected | | `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | Callback function to change the checkbox selection state | | `isDisabled` | `boolean` | Whether the checkbox is disabled and cannot be interacted with | | `isInvalid` | `boolean` | Whether the checkbox is invalid (shows danger color) | | `isOnSurface` | `boolean \| undefined` | Whether checkbox is on a surface background | | `nativeID` | `string \| undefined` | Native ID for the checkbox element | **Note:** This hook must be used within a `Checkbox` component. It will throw an error if called outside of the checkbox context. # FormField **Category**: native **URL**: https://v3.heroui.com/docs/native/components/form-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(forms)/form-field.mdx > Provides consistent layout and interaction for form controls with label, description, and error handling. Perfect for Switch and Checkbox components when you want the entire field to be pressable. ## Import ```tsx import { FormField } from 'heroui-native'; ``` ## Anatomy ```tsx ... ... ... ... ``` * **FormField**: Root container that manages layout and state propagation * **FormField.Label**: Primary text label for the control * **FormField.Description**: Secondary descriptive helper text * **FormField.Indicator**: Container for the form control component (Switch, Checkbox) * **FormField.ErrorMessage**: Validation error message display ## Usage ### Basic Usage FormField wraps form controls to provide consistent layout and state management. ```tsx 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, FormField, Switch } from 'heroui-native'; import React from 'react'; import { ScrollView, View } from 'react-native'; export default function FormFieldExample() { const [notifications, setNotifications] = React.useState(false); const [terms, setTerms] = React.useState(false); const [newsletter, setNewsletter] = React.useState(true); return ( 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 ); } ``` ## API Reference ### FormField | prop | type | default | description | | ----------------- | ----------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- | | children | `React.ReactNode \| ((props: FormFieldRenderProps) => React.ReactNode)` | - | Content to render inside the form control, or a render function | | isSelected | `boolean` | `undefined` | Whether the control is selected/checked | | isDisabled | `boolean` | `false` | Whether the form control is disabled | | isInvalid | `boolean` | `false` | Whether the form control is invalid | | className | `string` | - | Custom class name for the root element | | onSelectedChange | `(isSelected: boolean) => void` | - | Callback when selection state changes | | animation | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children | | ...PressableProps | `PressableProps` | - | All React Native Pressable props are supported | ### FormField.Label | prop | type | default | description | | ------------ | ----------------- | ------- | ----------------------------------------- | | children | `React.ReactNode` | - | Label text content | | className | `string` | - | Custom class name for the label element | | ...TextProps | `TextProps` | - | All React Native Text props are supported | ### FormField.Description | prop | type | default | description | | ------------ | ----------------- | ------- | --------------------------------------------- | | children | `React.ReactNode` | - | Description text content | | className | `string` | - | Custom class name for the description element | | ...TextProps | `TextProps` | - | All React Native Text props are supported | ### FormField.Indicator | prop | type | default | description | | ------------ | ------------------------ | ---------- | ---------------------------------------------------------- | | children | `React.ReactNode` | - | Control component to render (Switch, Checkbox) | | variant | `'checkbox' \| 'switch'` | `'switch'` | Variant of the control to render when no children provided | | className | `string` | - | Custom class name for the indicator element | | ...ViewProps | `ViewProps` | - | All React Native View props are supported | **Note**: When children are provided, the component automatically passes down `isSelected`, `onSelectedChange`, `isDisabled`, and `isInvalid` props from the FormField context if they are not already present on the child component. ### FormField.ErrorMessage FormField.ErrorMessage extends all props from [ErrorView](./error-view) component. **Note**: The `isInvalid` prop is automatically passed from the FormField context. The error message visibility is controlled by the `isInvalid` state of the parent FormField. ## Hooks ### useFormField **Returns:** | property | type | description | | ------------------ | ---------------------------------------------- | ---------------------------------------------- | | `isSelected` | `boolean \| undefined` | Whether the control is selected/checked | | `onSelectedChange` | `((isSelected: boolean) => void) \| undefined` | Callback when selection state changes | | `isDisabled` | `boolean` | Whether the form control is disabled | | `isInvalid` | `boolean` | Whether the form control is invalid | | `isPressed` | `SharedValue` | Reanimated shared value indicating press state | # 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 default indicator if no children provided. Supports render function children to access state (`isSelected`, `isInvalid`, `isDisabled`). * **RadioGroup.Label**: Optional clickable text label for the radio option. Linked to the radio for accessibility. * **RadioGroup.Description**: Optional secondary text below the label. Provides additional context about the radio option. * **RadioGroup.Indicator**: Optional container for the radio circle. Renders default thumb if no children provided. Manages the visual selection state. * **RadioGroup.IndicatorThumb**: Optional inner circle that appears when selected. Animates scale based on selection. Can be replaced with custom content. * **RadioGroup.ErrorMessage**: Error message displayed when radio group is invalid. Shown with animation below the radio group content. ## Usage ### Basic Usage RadioGroup with simple string children automatically renders title and indicator. ```tsx Option 1 Option 2 Option 3 ``` ### With Descriptions Add descriptive text below each radio option for additional context. ```tsx 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. ```tsx Custom Option {value === 'custom' && ( )} ``` ### With Render Function Use a render function on RadioGroup.Item to access state and customize the entire content. ```tsx {({ isSelected, isInvalid, isDisabled }) => ( <> Option 1 {isSelected && } )} ``` ### With Error Message Display validation errors below the radio group. ```tsx I agree to the terms I do not agree Please select an option to continue ``` ## Example ```tsx import { RadioGroup, useThemeColor } from 'heroui-native'; import { Ionicons } from '@expo/vector-icons'; import React from 'react'; import { View } from 'react-native'; export default function PaymentMethodExample() { const [paymentMethod, setPaymentMethod] = React.useState('card'); const themeColorForeground = useThemeColor('foreground'); return ( Credit/Debit Card Pay securely with your credit or debit card PayPal Fast and secure payment with PayPal Bank Transfer Direct transfer from your bank account ); } ``` ## API Reference ### RadioGroup | prop | type | default | description | | --------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- | | `children` | `React.ReactNode` | `undefined` | Radio group content | | `value` | `string \| undefined` | `undefined` | The currently selected value of the radio group | | `onValueChange` | `(val: string) => void` | `undefined` | Callback fired when the selected value changes | | `isDisabled` | `boolean` | `false` | Whether the entire radio group is disabled | | `isInvalid` | `boolean` | `false` | Whether the radio group is invalid | | `isOnSurface` | `boolean` | `undefined` | Whether the radio group is on surface | | `animation` | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children | | `className` | `string` | `undefined` | Custom class name | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### RadioGroup.Item | prop | type | default | description | | ------------------- | ---------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- | | `children` | `React.ReactNode \| ((props: RadioGroupItemRenderProps) => React.ReactNode)` | `undefined` | Radio item content or render function to customize the radio item | | `value` | `string` | `undefined` | The value associated with this radio item | | `isDisabled` | `boolean` | `false` | Whether this specific radio item is disabled | | `isInvalid` | `boolean` | `false` | Whether the radio item is invalid | | `isOnSurface` | `boolean` | `undefined` | Whether the radio item is on surface (auto-detected if not set) | | `hitSlop` | `number` | `6` | Hit slop for the pressable area | | `className` | `string` | `undefined` | Custom class name | | `...PressableProps` | `PressableProps` | - | All standard React Native Pressable props are supported (except disabled) | #### RadioGroupItemRenderProps | prop | type | description | | ------------ | --------- | ---------------------------------- | | `isSelected` | `boolean` | Whether the radio item is selected | | `isInvalid` | `boolean` | Whether the radio item is invalid | | `isDisabled` | `boolean` | Whether the radio item is disabled | ### RadioGroup.Indicator | prop | type | default | description | | ----------------------- | -------------------------- | ----------- | ------------------------------------------------ | | `children` | `React.ReactNode` | `undefined` | Indicator content | | `className` | `string` | `undefined` | Custom class name | | `...Animated.ViewProps` | `AnimatedProps` | - | All Reanimated Animated.View props are supported | **Note:** The `isOnSurface` state is automatically provided via context from the parent RadioGroup.Item component. ### RadioGroup.IndicatorThumb | prop | type | default | description | | ----------------------- | ----------------------------------- | ----------- | ------------------------------------------------ | | `className` | `string` | `undefined` | Custom class name | | `animation` | `RadioGroupIndicatorThumbAnimation` | - | Animation configuration | | `...Animated.ViewProps` | `AnimatedProps` | - | All Reanimated Animated.View props are supported | #### RadioGroupIndicatorThumbAnimation Animation configuration for RadioGroupIndicatorThumb component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | -------------------- | ------------------ | ---------------------------------------------------- | ------------------------------------ | | `scale.value` | `[number, number]` | `[1.5, 1]` | Scale values \[unselected, selected] | | `scale.timingConfig` | `WithTimingConfig` | `{ duration: 300, easing: Easing.out(Easing.ease) }` | Animation timing configuration | ### RadioGroup.Label | prop | type | default | description | | ----------------------- | -------------------------- | ----------- | ------------------------------------------------ | | `children` | `React.ReactNode` | `undefined` | Label text content | | `className` | `string` | `undefined` | Custom class name for the label element | | `...Animated.TextProps` | `AnimatedProps` | - | All Reanimated Animated.Text props are supported | ### RadioGroup.Description | prop | type | default | description | | ----------------------- | -------------------------- | ----------- | ------------------------------------------------ | | `children` | `React.ReactNode` | `undefined` | Description text content | | `className` | `string` | `undefined` | Custom class name for the description element | | `...Animated.TextProps` | `AnimatedProps` | - | All Reanimated Animated.Text props are supported | ### RadioGroup.ErrorMessage | prop | type | default | description | | ----------------------- | ------------------------------ | ----------- | ------------------------------------------------ | | `children` | `React.ReactNode` | `undefined` | The content of the error field | | `isInvalid` | `boolean` | `false` | Controls the visibility of the error field | | `className` | `string` | `undefined` | Additional CSS class for styling | | `classNames` | `ElementSlots` | `undefined` | Additional CSS classes for different parts | | `textProps` | `TextProps` | `undefined` | Additional props to pass to the Text component | | `...Animated.ViewProps` | `AnimatedProps` | - | All Reanimated Animated.View props are supported | ## Hooks ### useRadioGroup **Returns:** | Property | Type | Description | | --------------- | ------------------------- | ---------------------------------------------- | | `value` | `string \| undefined` | Currently selected value | | `isDisabled` | `boolean` | Whether the radio group is disabled | | `isInvalid` | `boolean` | Whether the radio group is in an invalid state | | `onValueChange` | `(value: string) => void` | Function to change the selected value | ### useRadioGroupItem **Returns:** | Property | Type | Description | | ------------- | --------- | ------------------------------------ | | `isSelected` | `boolean` | Whether the radio item is selected | | `isDisabled` | `boolean` | Whether the radio item is disabled | | `isInvalid` | `boolean` | Whether the radio item is invalid | | `isOnSurface` | `boolean` | Whether the radio item is on surface | # 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. * **Select.Value**: Displays the selected value or placeholder text. Automatically updates when selection changes. * **Select.Portal**: Renders select content in a portal layer above other content. Ensures proper stacking and positioning. * **Select.Overlay**: Optional background overlay. Can be transparent or semi-transparent to capture outside clicks. * **Select.Content**: Container for select content with three presentation modes: popover (floating with positioning), bottom sheet modal, or dialog modal. * **Select.Close**: Close button that dismisses the select when pressed. Renders a default X icon if no children provided. * **Select.ListLabel**: Label for the list of items with pre-styled typography. * **Select.Item**: Selectable option item. Handles selection state and press events. * **Select.ItemLabel**: Displays the label text for an item. * **Select.ItemDescription**: Optional description text for items with muted styling. * **Select.ItemIndicator**: Optional indicator shown for selected items. Renders a check icon by default. ## Usage ### Basic Usage The Select component uses compound parts to create dropdown selection interfaces. ```tsx ``` ### 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 ``` ### Controlled Mode Control the select state programmatically. ```tsx const [value, setValue] = useState(); const [isOpen, setIsOpen] = useState(false); ; ``` ## Example ```tsx import { Button, Select } from 'heroui-native'; import { useState } from 'react'; import { ScrollView, Text, View } from 'react-native'; type CountryOption = { value: string; label: string; flag: string; code: string; }; const COUNTRIES: CountryOption[] = [ { value: 'US', label: 'United States', flag: '🇺🇸', code: '+1' }, { value: 'GB', label: 'United Kingdom', flag: '🇬🇧', code: '+44' }, { value: 'CA', label: 'Canada', flag: '🇨🇦', code: '+1' }, { value: 'AU', label: 'Australia', flag: '🇦🇺', code: '+61' }, ]; export default function SelectExample() { const [country, setCountry] = useState(); return ( ); } ``` ## API Reference ### Select | prop | type | default | description | | -------------------------- | ------------------------------- | ------- | ---------------------------------------------------------------------- | | `children` | `ReactNode` | - | The content of the select | | `value` | `SelectOption` | - | The selected value (controlled mode) | | `onValueChange` | `(value: SelectOption) => void` | - | Callback when the value changes | | `defaultValue` | `SelectOption` | - | The default selected value (uncontrolled mode) | | `isOpen` | `boolean` | - | Whether the select is open (controlled mode) | | `isDefaultOpen` | `boolean` | - | Whether the select is open when initially rendered (uncontrolled mode) | | `onOpenChange` | `(isOpen: boolean) => void` | - | Callback when the select open state changes | | `closeDelay` | `number` | `400` | Delay in milliseconds before closing the select | | `isDisabled` | `boolean` | `false` | Whether the select is disabled | | `isDismissKeyboardOnClose` | `boolean` | `true` | Whether to dismiss keyboard when select closes | | `animation` | `SelectRootAnimation` | - | Animation configuration | | `asChild` | `boolean` | `false` | Whether to render as a child element | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | #### SelectRootAnimation Animation configuration for Select component. Can be: * `false` or `"disabled"`: Disable only root animations * `"disable-all"`: Disable all animations including children * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ---------------- | ------------------------------------------------ | ------- | ---------------------------------------------- | | `entering.value` | `SpringAnimationConfig \| TimingAnimationConfig` | - | Animation configuration for when select opens | | `exiting.value` | `SpringAnimationConfig \| TimingAnimationConfig` | - | Animation configuration for when select closes | #### SpringAnimationConfig | prop | type | default | description | | -------- | ------------------ | ------- | ----------------------------------------- | | `type` | `'spring'` | - | Animation type (must be `'spring'`) | | `config` | `WithSpringConfig` | - | Reanimated spring animation configuration | #### TimingAnimationConfig | prop | type | default | description | | -------- | ------------------ | ------- | ----------------------------------------- | | `type` | `'timing'` | - | Animation type (must be `'timing'`) | | `config` | `WithTimingConfig` | - | Reanimated timing animation configuration | ### Select.Trigger | prop | type | default | description | | ------------------- | ---------------- | ------- | ------------------------------------------------------- | | `children` | `ReactNode` | - | The trigger element content | | `className` | `string` | - | Additional CSS classes for the trigger | | `asChild` | `boolean` | `true` | Whether to render as a child element | | `...PressableProps` | `PressableProps` | - | All standard React Native Pressable props are supported | ### Select.Value | prop | type | default | description | | -------------- | ----------- | ------- | -------------------------------------------------- | | `placeholder` | `string` | - | Placeholder text when no value is selected | | `className` | `string` | - | Additional CSS classes for the value | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### Select.Portal | prop | type | default | description | | -------------- | ----------- | ------- | -------------------------------------------------- | | `children` | `ReactNode` | - | The portal content (required) | | `className` | `string` | - | Additional CSS classes for the portal container | | `hostName` | `string` | - | Optional name of the host element for the portal | | `forceMount` | `boolean` | - | Whether to force mount the component in the DOM | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Select.Overlay | prop | type | default | description | | ----------------------- | ------------------------ | ------- | --------------------------------------------------- | | `className` | `string` | - | Additional CSS classes for the overlay | | `animation` | `SelectOverlayAnimation` | - | Animation configuration | | `closeOnPress` | `boolean` | `true` | Whether to close the select when overlay is pressed | | `forceMount` | `boolean` | - | Whether to force mount the component in the DOM | | `asChild` | `boolean` | `false` | Whether to render as a child element | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | #### SelectOverlayAnimation Animation configuration for Select.Overlay component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | --------------- | -------------------------- | ----------- | ----------------------------------- | | `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values \[idle, open, close] | ### Select.Content (Popover Presentation) | prop | type | default | description | | ----------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------ | | `children` | `ReactNode` | - | The select content | | `width` | `number \| 'trigger' \| 'content-fit' \| 'full'` | `'content-fit'` | Width sizing strategy for the content | | `presentation` | `'popover'` | `'popover'` | Presentation mode for the select | | `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Placement of the content relative to trigger | | `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment along the placement axis | | `avoidCollisions` | `boolean` | `true` | Whether to flip placement when close to viewport edges | | `offset` | `number` | `8` | Distance from trigger element in pixels | | `alignOffset` | `number` | `0` | Offset along the alignment axis in pixels | | `className` | `string` | - | Additional CSS classes for the content container | | `animation` | `SelectContentPopoverAnimation` | - | Animation configuration | | `forceMount` | `boolean` | - | Whether to force mount the component in the DOM | | `insets` | `Insets` | - | Screen edge insets to respect when positioning | | `asChild` | `boolean` | `false` | Whether to render as a child element | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | #### SelectContentPopoverAnimation Animation configuration for Select.Content component (popover presentation). Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ----------------------- | -------------------------- | ------------------ | -------------------------------------- | | `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values \[idle, open, close] | | `scale.value` | `[number, number, number]` | `[0.95, 1, 0.95]` | Scale values \[idle, open, close] | | `translateX.value` | `[number, number, number]` | Based on placement | TranslateX values \[idle, open, close] | | `translateY.value` | `[number, number, number]` | Based on placement | TranslateY values \[idle, open, close] | | `transformOrigin.value` | `string` | Based on placement | Transform origin value | ### Select.Content (Bottom Sheet Presentation) | prop | type | default | description | | -------------------------- | ------------------ | ------- | ------------------------------------------------ | | `children` | `ReactNode` | - | The bottom sheet content | | `presentation` | `'bottom-sheet'` | - | Presentation mode for the select | | `bottomSheetViewClassName` | `string` | - | Additional CSS classes for the bottom sheet view | | `...BottomSheetProps` | `BottomSheetProps` | - | All @gorhom/bottom-sheet props are supported | ### Select.Content (Dialog Presentation) | prop | type | default | description | | ----------------------- | ---------------------------------------- | ------- | --------------------------------------------------- | | `children` | `ReactNode` | - | The dialog content | | `presentation` | `'dialog'` | - | Presentation mode for the select | | `classNames` | `{ wrapper?: string; content?: string }` | - | Additional CSS classes for wrapper and content | | `animation` | `SelectContentAnimation` | - | Animation configuration | | `isSwipeable` | `boolean` | `true` | Whether the dialog content can be swiped to dismiss | | `forceMount` | `boolean` | - | Whether to force mount the component in the DOM | | `asChild` | `boolean` | `false` | Whether to render as a child element | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | #### SelectContentAnimation Animation configuration for Select.Content component (dialog presentation). Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | --------------- | -------------------------- | ----------------- | ----------------------------------- | | `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values \[idle, open, close] | | `scale.value` | `[number, number, number]` | `[0.97, 1, 0.97]` | Scale values \[idle, open, close] | ### Select.Close | prop | type | default | description | | ------------------- | ---------------------- | ------- | ------------------------------------------------------- | | `children` | `ReactNode` | - | The close button content | | `className` | `string` | - | Additional CSS classes for the close button | | `iconProps` | `SelectCloseIconProps` | - | Close icon configuration | | `asChild` | `boolean` | - | Whether to render as a child element | | `...PressableProps` | `PressableProps` | - | All standard React Native Pressable props are supported | #### SelectCloseIconProps | prop | type | default | description | | ------- | -------- | ---------------- | ----------------- | | `size` | `number` | `18` | Size of the icon | | `color` | `string` | `--colors-muted` | Color of the icon | ### Select.ListLabel | prop | type | default | description | | -------------- | ----------- | ------- | -------------------------------------------------- | | `children` | `ReactNode` | - | The label text content | | `className` | `string` | - | Additional CSS classes for the list label | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### Select.Item | prop | type | default | description | | ------------------- | ------------------------------------------------------------ | ------- | -------------------------------------------------------------------------- | | `children` | `ReactNode \| ((props: SelectItemRenderProps) => ReactNode)` | - | Custom item content. Defaults to label and indicator, or a render function | | `value` | `any` | - | The value associated with this item (required) | | `label` | `string` | - | The label text for this item (required) | | `isDisabled` | `boolean` | `false` | Whether this item is disabled | | `className` | `string` | - | Additional CSS classes for the item | | `...PressableProps` | `PressableProps` | - | All standard React Native Pressable props are supported | #### SelectItemRenderProps When using a render function for `children`, the following props are provided: | property | type | description | | ------------ | --------- | --------------------------------------- | | `isSelected` | `boolean` | Whether this item is currently selected | | `value` | `string` | The value of the item | | `isDisabled` | `boolean` | Whether the item is disabled | ### Select.ItemLabel | prop | type | default | description | | -------------- | ----------- | ------- | -------------------------------------------------- | | `className` | `string` | - | Additional CSS classes for the item label | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### Select.ItemDescription | prop | type | default | description | | -------------- | ----------- | ------- | -------------------------------------------------- | | `children` | `ReactNode` | - | The description text content | | `className` | `string` | - | Additional CSS classes for the item description | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### Select.ItemIndicator | prop | type | default | description | | -------------- | ------------------------------ | ------- | -------------------------------------------------- | | `children` | `ReactNode` | - | Custom indicator content. Defaults to check icon | | `className` | `string` | - | Additional CSS classes for the item indicator | | `iconProps` | `SelectItemIndicatorIconProps` | - | Check icon configuration | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | #### SelectItemIndicatorIconProps | prop | type | default | description | | ------- | -------- | ---------------- | ----------------- | | `size` | `number` | `16` | Size of the icon | | `color` | `string` | `--colors-muted` | Color of the icon | ## Hooks ### useSelect Hook to access the Select root context. Returns the select state and control functions. ```tsx import { useSelect } from 'heroui-native'; const { isOpen, onOpenChange, isDefaultOpen, isDisabled, triggerPosition, setTriggerPosition, contentLayout, setContentLayout, nativeID, closeDelay, value, onValueChange, } = useSelect(); ``` #### Return Value | property | type | description | | -------------------- | -------------------------------------------- | --------------------------------------------------------- | | `isOpen` | `boolean` | Whether the select is currently open | | `onOpenChange` | `(open: boolean) => void` | Callback to change the open state | | `isDefaultOpen` | `boolean \| undefined` | Whether the select is open by default (uncontrolled mode) | | `isDisabled` | `boolean \| undefined` | Whether the select is disabled | | `triggerPosition` | `LayoutPosition \| null` | Position of the trigger element relative to viewport | | `setTriggerPosition` | `(position: LayoutPosition \| null) => void` | Updates the trigger element's position | | `contentLayout` | `LayoutRectangle \| null` | Layout measurements of the select content | | `setContentLayout` | `(layout: LayoutRectangle \| null) => void` | Updates the content layout measurements | | `nativeID` | `string` | Unique identifier for the select instance | | `closeDelay` | `number \| undefined` | Delay in milliseconds before the select closes | | `value` | `SelectOption` | Currently selected option | | `onValueChange` | `(option: SelectOption) => void` | Callback fired when the selected value changes | **Note:** This hook must be used within a `Select` component. It will throw an error if called outside of the select context. ### useSelectAnimation Hook to access the Select animation state values within custom components or compound components. ```tsx import { useSelectAnimation } from 'heroui-native'; const { selectState, progress, isDragging, isGestureReleaseAnimationRunning } = useSelectAnimation(); ``` #### Return Value | property | type | description | | ---------------------------------- | ----------------------------- | ---------------------------------------------------------- | | `selectState` | `'idle' \| 'open' \| 'close'` | Extended internal state for coordinating animations | | `progress` | `SharedValue` | 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 | # 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 && ( )} ); } ``` ## API Reference ### Switch | prop | type | default | description | | --------------------------- | -------------------------------------------------------------------- | ----------- | ------------------------------------------------------------ | | `children` | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | Content to render inside the switch, or a render function | | `isSelected` | `boolean` | `undefined` | Whether the switch is currently selected | | `isDisabled` | `boolean` | `false` | Whether the switch is disabled and cannot be interacted with | | `className` | `string` | `undefined` | Custom class name for the switch | | `animation` | `SwitchRootAnimation` | - | Animation configuration | | `onSelectedChange` | `(isSelected: boolean) => void` | - | Callback fired when the switch selection state changes | | `...AnimatedPressableProps` | `AnimatedProps` | - | 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 | | ------------------------------ | ------------------ | -------------------------------------------------------------- | ----------------------------------------------- | | `scale.value` | `[number, number]` | `[1, 0.96]` | Scale values \[unpressed, pressed] | | `scale.timingConfig` | `WithTimingConfig` | `{ duration: 150 }` | Animation timing configuration | | `backgroundColor.value` | `[string, string]` | Uses theme colors | Background color values \[unselected, selected] | | `backgroundColor.timingConfig` | `WithTimingConfig` | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | Animation timing configuration | ### Switch.Thumb | prop | type | default | description | | -------------- | -------------------------------------------------------------------- | ----------- | -------------------------------------------------------- | | `children` | `React.ReactNode \| ((props: SwitchRenderProps) => React.ReactNode)` | `undefined` | Content to render inside the thumb, or a render function | | `className` | `string` | `undefined` | Custom class name for the thumb element | | `animation` | `SwitchThumbAnimation` | - | Animation configuration | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | #### SwitchThumbAnimation Animation configuration for Switch.Thumb component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ------------------------------ | ------------------ | -------------------------------------------------------------- | ----------------------------------------------------------------------- | | `left.value` | `number` | `2` | Offset value from the edges (left when unselected, right when selected) | | `left.springConfig` | `WithSpringConfig` | `{ damping: 120, stiffness: 1600, mass: 2 }` | Spring animation configuration for thumb position | | `backgroundColor.value` | `[string, string]` | `['white', theme accent-foreground color]` | Background color values \[unselected, selected] | | `backgroundColor.timingConfig` | `WithTimingConfig` | `{ duration: 175, easing: Easing.bezier(0.25, 0.1, 0.25, 1) }` | Animation timing configuration | ### Switch.StartContent | prop | type | default | description | | -------------- | ----------------- | ----------- | -------------------------------------------------- | | `children` | `React.ReactNode` | `undefined` | Content to render inside the switch content | | `className` | `string` | `undefined` | Custom class name for the content element | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Switch.EndContent | 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 FormField The Switch component integrates seamlessly with FormField for press state sharing: ```tsx Enable notifications Receive push notifications ``` When wrapped in FormField, the Switch will automatically respond to press events on the entire FormField container, creating a larger touch target and better user experience. # 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**: Root container that provides spacing and state management * **TextField.Label**: Label with optional asterisk for required fields * **TextField.Input**: Input container with animated border and background * **TextField.InputStartContent**: Optional content at the start of the input * **TextField.InputEndContent**: Optional content at the end of the input * **TextField.Description**: Helper text displayed below the input * **TextField.ErrorMessage**: Error message shown when field is invalid ## Usage ### Basic Usage TextField provides a complete form input structure with label and description. ```tsx Email We'll never share your email ``` ### With Required Field Mark fields as required to show an asterisk in the label. ```tsx Username ``` ### With Start and End Content Add icons or other content at the beginning or end of the input. ```tsx Password ... ... ``` ### With Validation Display error messages when the field is invalid. ```tsx Email Please enter a valid email ``` ### With Local Invalid State Override Override the context's invalid state for individual components. ```tsx Email This shows despite input being invalid Email format is incorrect ``` ### Multiline Input Create text areas for longer content. ```tsx Message Maximum 500 characters ``` ### Disabled State Disable the entire field to prevent interaction. ```tsx Disabled Field ``` ### Custom Colors Customize the input colors for different states using the animation prop. ```tsx Custom Styled ``` ## Example ```tsx import { Ionicons } from '@expo/vector-icons'; import { TextField, useThemeColor } from 'heroui-native'; import React from 'react'; import { ScrollView, View } from 'react-native'; export default function TextFieldExample() { const themeColorMuted = useThemeColor('muted'); const [email, setEmail] = React.useState(''); const isInvalidEmail = email !== '' && !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email); return ( Email Address We'll send a confirmation to this email Please enter a valid email address Password Bio Brief description for your profile ); } ``` ## API Reference ### TextField | prop | type | default | description | | ------------ | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- | | children | `React.ReactNode` | - | Content to render inside the text field | | isDisabled | `boolean` | `false` | Whether the entire text field is disabled | | isInvalid | `boolean` | `false` | Whether the text field is in an invalid state | | isRequired | `boolean` | `false` | Whether the text field is required (shows asterisk) | | className | `string` | - | Custom class name for the root element | | animation | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children | | ...ViewProps | `ViewProps` | - | All standard React Native View props are supported | ### TextField.Label | prop | type | default | description | | --------------------- | -------------------------- | ----------- | ------------------------------------------------------------ | | children | `React.ReactNode` | - | Label text content | | isInvalid | `boolean` | `undefined` | Whether the label is in an invalid state (overrides context) | | className | `string` | - | Custom class name for the label element | | classNames | `ElementSlots` | - | Custom class names for different parts of the label | | animation | `TextFieldLabelAnimation` | - | Animation configuration | | ...Animated.TextProps | `AnimatedProps` | - | All Reanimated Animated.Text props are supported | #### `ElementSlots` | prop | type | description | | -------- | -------- | ------------------------------------ | | text | `string` | Custom class name for the label text | | asterisk | `string` | Custom class name for the asterisk | #### TextFieldLabelAnimation Animation configuration for TextField.Label component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ---------------- | ----------------------- | ----------------------------------------------------------------------- | ------------------------- | | `entering.value` | `EntryOrExitLayoutType` | `FadeIn`
`.duration(150)`
`.easing(Easing.out(Easing.ease))` | Custom entering animation | | `exiting.value` | `EntryOrExitLayoutType` | `FadeOut`
`.duration(150)`
`.easing(Easing.out(Easing.ease))` | Custom exiting animation | ### TextField.Input | prop | type | default | description | | ----------------- | -------------------------- | ----------- | ------------------------------------------------------------ | | children | `React.ReactNode` | - | Content to render inside the input container | | isInvalid | `boolean` | `undefined` | Whether the input is in an invalid state (overrides context) | | className | `string` | - | Custom class name for the input container | | classNames | `ElementSlots` | - | Custom class names for different parts of the input | | animation | `TextFieldInputAnimation` | - | Animation configuration | | ...TextInputProps | `TextInputProps` | - | All standard React Native TextInput props are supported | #### `ElementSlots` | prop | type | description | | --------- | -------- | -------------------------------------------- | | container | `string` | Custom class name for the input container | | input | `string` | Custom class name for the text input element | #### TextFieldInputAnimation Animation configuration for TextField.Input component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | --------------------------------------------- | ------------------ | ---------------------------------------------------- | --------------------------------------------------------------- | | `backgroundColor`
`.value`
`.blur` | `string` | Uses theme color | Background color when input is blurred | | `backgroundColor`
`.value`
`.focus` | `string` | Uses theme color | Background color when input is focused | | `backgroundColor`
`.value`
`.error` | `string` | Uses theme color | Background color when input is invalid | | `backgroundColor`
`.timingConfig` | `WithTimingConfig` | `{ duration: 150, easing: Easing.out(Easing.ease) }` | Animation timing configuration for background color transitions | | `borderColor`
`.value`
`.blur` | `string` | Uses theme color | Border color when input is blurred | | `borderColor`
`.value`
`.focus` | `string` | Uses theme color | Border color when input is focused | | `borderColor`
`.value`
`.error` | `string` | Uses theme color | Border color when input is invalid | | `borderColor`
`.timingConfig` | `WithTimingConfig` | `{ duration: 150, easing: Easing.out(Easing.ease) }` | Animation timing configuration for border color transitions | ### TextField.InputStartContent | prop | type | default | description | | ------------ | ----------------- | ------- | -------------------------------------------------- | | children | `React.ReactNode` | - | Content to render at the start of the input | | className | `string` | - | Custom class name for the start content element | | ...ViewProps | `ViewProps` | - | All standard React Native View props are supported | ### TextField.InputEndContent | prop | type | default | description | | ------------ | ----------------- | ------- | -------------------------------------------------- | | children | `React.ReactNode` | - | Content to render at the end of the input | | className | `string` | - | Custom class name for the end content element | | ...ViewProps | `ViewProps` | - | All standard React Native View props are supported | ### TextField.Description | prop | type | default | description | | --------------------- | ------------------------------- | ----------- | ------------------------------------------------------------------ | | children | `React.ReactNode` | - | Description text content | | isInvalid | `boolean` | `undefined` | Whether the description is in an invalid state (overrides context) | | className | `string` | - | Custom class name for the description element | | animation | `TextFieldDescriptionAnimation` | - | Animation configuration | | ...Animated.TextProps | `AnimatedProps` | - | All Reanimated Animated.Text props are supported | #### TextFieldDescriptionAnimation Animation configuration for TextField.Description component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ---------------- | ----------------------- | ----------------------------------------------------------------------- | ------------------------- | | `entering.value` | `EntryOrExitLayoutType` | `FadeIn`
`.duration(150)`
`.easing(Easing.out(Easing.ease))` | Custom entering animation | | `exiting.value` | `EntryOrExitLayoutType` | `FadeOut`
`.duration(150)`
`.easing(Easing.out(Easing.ease))` | Custom exiting animation | ### TextField.ErrorMessage > **Note**: `TextField.ErrorMessage` extends `ErrorView` component. For complete API reference, see [ErrorView documentation](error-view). ## Hooks ### useTextField Hook to access the TextField context values. Must be used within a `TextField` component. ```tsx import { TextField, useTextField } from 'heroui-native'; function CustomComponent() { const { isDisabled, isInvalid, isRequired } = useTextField(); // Use the context values... } ``` #### Returns | property | type | description | | ---------- | --------- | --------------------------------------------- | | isDisabled | `boolean` | Whether the entire text field is disabled | | isInvalid | `boolean` | Whether the text field is in an invalid state | | isRequired | `boolean` | Whether the text field is required | # 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**: 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 ... ``` ### With Title and Description Combine title and description components for structured text content. ```tsx ... ... ``` ### With Header and Footer Add header and footer sections for icons, badges, or actions. ```tsx ... ... ... ``` ### Variants Control the card's background appearance using different variants. ```tsx ... ... ... ... ... ``` ### Horizontal Layout Create horizontal cards by using flex-row styling. ```tsx ``` ### Background Image Use an image as an absolute positioned background. ```tsx ... ``` ## Example ```tsx import { Button, Card } from 'heroui-native'; import { Ionicons } from '@expo/vector-icons'; import { View } from 'react-native'; export default function CardExample() { return ( $450 Living room Sofa • Collection 2025 This sofa is perfect for modern tropical spaces, baroque inspired spaces. ); } ``` ## API Reference ### Card | prop | type | default | description | | -------------- | ------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Content to be rendered inside the card | | `variant` | `'default' \| 'secondary' \| 'tertiary' \| 'quaternary' \| 'transparent'` | `'default'` | Visual variant of the card surface | | `className` | `string` | - | Additional CSS classes to apply | | `animation` | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Card.Header | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered inside the header | | `className` | `string` | - | Additional CSS classes | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Card.Body | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered inside the body | | `className` | `string` | - | Additional CSS classes | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Card.Footer | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered inside the footer | | `className` | `string` | - | Additional CSS classes | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Card.Title | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered as the title text | | `className` | `string` | - | Additional CSS classes | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### Card.Description | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered as the description text | | `className` | `string` | - | Additional CSS classes | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | # Divider **Category**: native **URL**: https://v3.heroui.com/docs/native/components/divider **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(layout)/divider.mdx > A simple line to separate content visually. ## Import ```tsx import { Divider } from 'heroui-native'; ``` ## Anatomy ```tsx ``` * **Divider**: A simple line component that separates content visually. Can be oriented horizontally or vertically, with customizable thickness and variant styles. ## Usage ### Basic Usage The Divider component creates a visual separation between content sections. ```tsx ``` ### Orientation Control the direction of the divider with the `orientation` prop. ```tsx Horizontal divider Content below Left Right ``` ### Variants Choose between thin and thick variants for different visual emphasis. ```tsx ``` ### Custom Thickness Set a specific thickness value for precise control. ```tsx ``` ## Example ```tsx import { Divider, Surface } from 'heroui-native'; import { Text, View } from 'react-native'; export default function DividerExample() { return ( HeroUI Native A modern React Native component library. Components Themes Examples ); } ``` ## API Reference ### Divider | prop | type | default | description | | -------------- | ---------------------------- | -------------- | -------------------------------------------------------------------------------------------- | | `variant` | `'thin' \| 'thick'` | `'thin'` | Variant style of the divider | | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Orientation of the divider | | `thickness` | `number` | `undefined` | Custom thickness in pixels. Controls height for horizontal or width for vertical orientation | | `className` | `string` | `undefined` | Additional CSS classes to apply | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | # 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**: 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 ... ``` ### Variants Control the visual appearance with different surface levels. ```tsx ... ... ... ... ``` ### Nested Surfaces Create visual hierarchy by nesting surfaces with different variants. ```tsx ... ... ... ... ``` ### Custom Styling Apply custom styles using className or style props. ```tsx ... ... ``` ### 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 { Surface } from 'heroui-native'; import { Text, View } from 'react-native'; export default function SurfaceExample() { return ( Surface Content This is a default surface variant. It uses bg-surface styling. Surface Content This is a secondary surface variant. It uses bg-surface-secondary styling. Surface Content This is a tertiary surface variant. It uses bg-surface-tertiary styling. Surface Content This is a quaternary surface variant. It uses bg-surface-quaternary styling. ); } ``` ## API Reference ### Surface | prop | type | default | description | | -------------- | ------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------------------------- | | `variant` | `'default' \| 'secondary' \| 'tertiary' \| 'quaternary' \| 'transparent'` | `'default'` | Visual variant controlling background color and border | | `children` | `React.ReactNode` | - | Content to be rendered inside the surface | | `className` | `string` | - | Additional CSS classes to apply | | `animation` | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | # 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**: 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 ``` ### With Image Display an avatar image with automatic fallback handling. ```tsx JD ``` ### With Text Initials Show text initials as the avatar content. ```tsx AB ``` ### With Custom Icon Provide a custom icon as fallback content. ```tsx ``` ### Sizes Control the avatar size with the size prop. ```tsx ``` ### Variants Choose between different visual styles with the `variant` prop. ```tsx DF SF ``` ### Colors Apply different color variants to the avatar. ```tsx DF AC SC WR DG ``` ### Delayed Fallback Show fallback after a delay to prevent flashing during image load. ```tsx NA ``` ### Custom Image Component Use a custom image component with the asChild prop. ```tsx import { Image } from 'expo-image'; EI ; ``` ### Animation Control Control animations at different levels of the Avatar component. #### Disable All Animations Disable all animations including children from the root component: ```tsx JD ``` #### Custom Image Animation Customize the image opacity animation: ```tsx JD ``` #### Custom Fallback Animation Customize the fallback entering animation: ```tsx import { FadeInDown } from 'react-native-reanimated'; JD ; ``` #### Disable Individual Animations Disable animations for specific components: ```tsx JD ``` ## 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 ( {users.map((user) => ( {user.name .split(' ') .map((n) => n[0]) .join('')} ))} ); } ``` ## 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` from React Native Reanimated * When `asChild={true}`: extends primitive image props for custom image components **Note:** When using `asChild={true}` with custom image components, the `className` prop may not be applied in some cases depending on the custom component's implementation. Ensure your custom component properly handles style props. | prop | type | default | description | | ------------------ | ---------------------------------------------- | ------- | ------------------------------------------------ | | `source` | `ImageSourcePropType` | - | Image source (required when `asChild={false}`) | | `asChild` | `boolean` | `false` | Whether to use a custom image component as child | | `className` | `string` | - | Additional CSS classes to apply | | `animation` | `AvatarImageAnimation` | - | Animation configuration | | `...AnimatedProps` | `AnimatedProps` or primitive props | - | Additional props based on `asChild` value | #### AvatarImageAnimation Animation configuration for avatar image component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ---------------------- | ------------------ | --------------------------------------------------- | ----------------------------------------------------- | | `opacity.value` | `[number, number]` | `[0, 1]` | Opacity values \[initial, loaded] for image animation | | `opacity.timingConfig` | `WithTimingConfig` | `{ duration: 200, easing: Easing.in(Easing.ease) }` | Animation timing configuration | **Note:** Animation is automatically disabled when `asChild={true}` ### Avatar.Fallback | prop | type | default | description | | ----------------------- | ------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Fallback content (text, icon, or custom element) | | `delayMs` | `number` | `0` | Delay in milliseconds before showing the fallback (applied to entering animation) | | `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | inherited from parent | Color variant of the fallback | | `className` | `string` | - | Additional CSS classes for the container | | `classNames` | `ElementSlots` | - | Additional CSS classes for different parts | | `textProps` | `TextProps` | - | Props to pass to Text component when children is a string | | `iconProps` | `PersonIconProps` | - | Props to customize the default person icon | | `animation` | `AvatarFallbackAnimation` | - | Animation configuration | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | **classNames prop:** `ElementSlots` provides type-safe CSS classes for different parts of the fallback component. Available slots: `container`, `text`. #### AvatarFallbackAnimation Animation configuration for avatar fallback component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ---------------- | ----------------------- | -------------------------------------------------------------------------------------- | -------------------------------------- | | `entering.value` | `EntryOrExitLayoutType` | `FadeIn`
`.duration(200)`
`.easing(Easing.in(Easing.ease))`
`.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 ( JD ); } function AvatarContent() { const { status } = useAvatar(); if (status === 'loading') { return ; } 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. # 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**: 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 ... ... ``` ### Single Selection Mode Allow only one item to be expanded at a time. ```tsx ... ... ... ... ``` ### Multiple Selection Mode Allow multiple items to be expanded simultaneously. ```tsx ... ... ... ... ... ... ``` ### Surface Variant Apply a surface container style to the accordion. ```tsx ... ... ``` ### Custom Indicator Replace the default chevron indicator with custom content. ```tsx ... ... ``` ### Without Dividers Hide the dividers between accordion items. ```tsx ... ... ... ... ``` ### With PressableFeedback Wrap `Accordion.Trigger` with `PressableFeedback` to add custom press feedback animations. ```tsx import { Accordion, PressableFeedback } from 'heroui-native'; Item Title ... ; ``` ## 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: , 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: , 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: , content: 'Lorem ipsum dolor sit amet consectetur. Netus nunc mauris risus consequat. Libero placerat dignissim consectetur nisl.', }, ]; return ( {accordionData.map((item) => ( {item.icon} {item.title} {item.content} ))} ); } ``` ## API Reference ### Accordion | prop | type | default | description | | ----------------------- | -------------------------------------------------- | ----------- | ----------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered inside the accordion | | `selectionMode` | `'single' \| 'multiple'` | - | Whether the accordion allows single or multiple expanded items | | `variant` | `'default' \| 'surface'` | `'default'` | Visual variant of the accordion | | `isDividerVisible` | `boolean` | `true` | Whether to display a divider at the bottom of each accordion item | | `defaultValue` | `string \| string[] \| undefined` | - | Default expanded item(s) in uncontrolled mode | | `value` | `string \| string[] \| undefined` | - | Controlled expanded item(s) | | `isDisabled` | `boolean` | - | Whether all accordion items are disabled | | `isCollapsible` | `boolean` | `true` | Whether expanded items can be collapsed | | `animation` | `AccordionRootAnimation` | - | Animation configuration for accordion | | `className` | `string` | - | Additional CSS classes for the container | | `classNames` | `ElementSlots` | - | Additional CSS classes for the slots | | `onValueChange` | `(value: string \| string[] \| undefined) => void` | - | Callback when expanded items change | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | #### `ElementSlots` | prop | type | description | | ----------- | -------- | ----------------------------------------------- | | `container` | `string` | Custom class name for the accordion container | | `divider` | `string` | Custom class name for the divider between items | #### AccordionRootAnimation Animation configuration for accordion root component. Can be: * `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 | | -------------- | ------------------ | --------------------------------------------------------------------------------------------------- | ------------------------------------------------- | | `layout.value` | `LayoutTransition` | `LinearTransition`
`.springify()`
`.damping(140)`
`.stiffness(1600)`
`.mass(4)` | Custom layout animation for accordion transitions | ### Accordion.Item | prop | type | default | description | | ----------------------- | --------------------------------------------------------------------------- | ------- | -------------------------------------------------------------------------------- | | `children` | `React.ReactNode \| ((props: AccordionItemRenderProps) => React.ReactNode)` | - | Children elements to be rendered inside the accordion item, or a render function | | `value` | `string` | - | Unique value to identify this item | | `isDisabled` | `boolean` | - | Whether this specific item is disabled | | `className` | `string` | - | Additional CSS classes | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | #### AccordionItemRenderProps | prop | type | description | | ------------ | --------- | ------------------------------------------------ | | `isExpanded` | `boolean` | Whether the accordion item is currently expanded | | `value` | `string` | Unique value identifier for this accordion item | ### Accordion.Trigger | prop | type | default | description | | ------------------- | ----------------- | ------- | ------------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered inside the trigger | | `className` | `string` | - | Additional CSS classes | | `isDisabled` | `boolean` | - | Whether the trigger is disabled | | `...PressableProps` | `PressableProps` | - | All standard React Native Pressable props are supported | ### Accordion.Indicator | prop | type | default | description | | ----------------------- | ----------------------------- | ------- | ---------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Custom indicator content, if not provided defaults to animated chevron | | `className` | `string` | - | Additional CSS classes | | `iconProps` | `AccordionIndicatorIconProps` | - | Icon configuration | | `animation` | `AccordionIndicatorAnimation` | - | Animation configuration for indicator | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | #### AccordionIndicatorIconProps | prop | type | default | description | | ------- | -------- | ------------ | ----------------- | | `size` | `number` | `16` | Size of the icon | | `color` | `string` | `foreground` | Color of the icon | #### AccordionIndicatorAnimation Animation configuration for accordion indicator component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ----------------------- | ------------------ | -------------------------------------------- | ------------------------------------------------- | | `rotation.value` | `[number, number]` | `[0, -180]` | Rotation values \[collapsed, expanded] in degrees | | `rotation.springConfig` | `WithSpringConfig` | `{ damping: 140, stiffness: 1000, mass: 4 }` | Spring animation configuration for rotation | ### Accordion.Content | prop | type | default | description | | -------------- | --------------------------- | ------- | --------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered inside the content | | `className` | `string` | - | Additional CSS classes | | `animation` | `AccordionContentAnimation` | - | Animation configuration for content | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | #### AccordionContentAnimation Animation configuration for accordion content component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ---------------- | ----------------------- | ---------------------------------------------------------------------- | ------------------------------------- | | `entering.value` | `EntryOrExitLayoutType` | `FadeIn`
`.duration(200)`
`.easing(Easing.out(Easing.ease))` | Custom entering animation for content | | `exiting.value` | `EntryOrExitLayoutType` | `FadeOut`
`.duration(200)`
`.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'; {/* Other content */} {/* Accordion items */} ; ``` 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. # 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**: Main container that manages tab state and selection. Controls active tab, handles value changes, and provides context to child components. * **Tabs.List**: Container for tab triggers. Groups triggers together with optional styling variants (pill or line). * **Tabs.ScrollView**: Optional scrollable wrapper for tab triggers. Enables horizontal scrolling when tabs overflow with automatic centering of active tab. * **Tabs.Trigger**: Interactive button for each tab. Handles press events to change active tab and measures its position for indicator animation. * **Tabs.Label**: Text content for tab triggers. Displays the tab title with appropriate styling. * **Tabs.Indicator**: Animated visual indicator for active tab. Smoothly transitions between tabs using spring or timing animations. * **Tabs.Content**: Container for tab panel content. Shows content when its value matches the active tab. ## Usage ### Basic Usage The Tabs component uses compound parts to create navigable content sections. ```tsx Tab 1 Tab 2 ... ... ``` ### Pill Variant Default rounded pill style for tab triggers. ```tsx Settings Profile ... ... ``` ### Line Variant Underline style indicator for a more minimal appearance. ```tsx Overview Analytics ... ... ``` ### Scrollable Tabs Handle many tabs with horizontal scrolling. ```tsx First Tab Second Tab Third Tab Fourth Tab Fifth Tab ... ... ... ... ... ``` ### Disabled Tabs Disable specific tabs to prevent interaction. ```tsx Active Disabled Another ... ... ``` ### With Icons Combine icons with labels for enhanced visual context. ```tsx Home Search ... ... ``` ### With Render Function Use a render function on `Tabs.Trigger` to access state and customize content based on selection. ```tsx {({ isSelected, value, isDisabled }) => ( Settings )} {({ isSelected }) => ( <> Profile )} ... ... ``` ## Example ```tsx import { Tabs, TextField, FormField, Checkbox, Button } from 'heroui-native'; import { useState } from 'react'; import { View, Text } from 'react-native'; import Animated, { FadeIn, FadeOut, LinearTransition, } from 'react-native-reanimated'; const AnimatedContentContainer = ({ children, }: { children: React.ReactNode; }) => ( {children} ); export default function TabsExample() { const [activeTab, setActiveTab] = useState('general'); const [showSidebar, setShowSidebar] = useState(true); const [accountActivity, setAccountActivity] = useState(true); const [name, setName] = useState(''); return ( General Notifications Profile Show sidebar Display the sidebar navigation panel Account activity Notifications about your account activity Name ); } ``` ## API Reference ### Tabs | prop | type | default | description | | --------------- | ---------------------------- | ----------- | ----------------------------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered inside tabs | | `value` | `string` | - | Currently active tab value | | `variant` | `'pill' \| 'line'` | `'pill'` | Visual variant of the tabs | | `className` | `string` | - | Additional CSS classes for the container | | `animation` | `"disable-all" \| undefined` | `undefined` | Animation configuration. Use `"disable-all"` to disable all animations including children | | `onValueChange` | `(value: string) => void` | - | Callback when the active tab changes | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Tabs.List | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered inside the list | | `className` | `string` | - | Additional CSS classes | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Tabs.ScrollView | prop | type | default | description | | --------------------------- | ---------------------------------------- | ---------- | -------------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered inside the scroll view | | `scrollAlign` | `'start' \| 'center' \| 'end' \| 'none'` | `'center'` | Scroll alignment variant for the selected item | | `className` | `string` | - | Additional CSS classes for the scroll view | | `contentContainerClassName` | `string` | - | Additional CSS classes for the content container | | `...ScrollViewProps` | `ScrollViewProps` | - | All standard React Native ScrollView props are supported | ### Tabs.Trigger | prop | type | default | description | | ------------------- | ------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------- | | `children` | `React.ReactNode \| ((props: TabsTriggerRenderProps) => React.ReactNode)` | - | Children elements to be rendered inside the trigger, or a render function | | `value` | `string` | - | The unique value identifying this tab | | `isDisabled` | `boolean` | `false` | Whether the trigger is disabled | | `className` | `string` | - | Additional CSS classes | | `...PressableProps` | `PressableProps` | - | All standard React Native Pressable props are supported | #### TabsTriggerRenderProps When using a render function for `children`, the following props are provided: | property | type | description | | ------------ | --------- | ------------------------------------------ | | `isSelected` | `boolean` | Whether this trigger is currently selected | | `value` | `string` | The value of the trigger | | `isDisabled` | `boolean` | Whether the trigger is disabled | ### Tabs.Label | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Text content to be rendered as label | | `className` | `string` | - | Additional CSS classes | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### Tabs.Indicator | prop | type | default | description | | ----------------------- | ------------------------ | ------- | ------------------------------------------------ | | `children` | `React.ReactNode` | - | Custom indicator content | | `className` | `string` | - | Additional CSS classes | | `animation` | `TabsIndicatorAnimation` | - | Animation configuration | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | #### TabsIndicatorAnimation Animation configuration for Tabs.Indicator component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | --------------- | -------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------------- | | `width.type` | `'spring' \| 'timing'` | `'spring'` | Type of animation to use | | `width.config` | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration | | `height.type` | `'spring' \| 'timing'` | `'spring'` | Type of animation to use | | `height.config` | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration | | `left.type` | `'spring' \| 'timing'` | `'spring'` | Type of animation to use | | `left.config` | `WithSpringConfig \| WithTimingConfig` | `{ stiffness: 1200, damping: 120 }` (spring) or `{ duration: 200 }` (timing) | Reanimated animation configuration | ### Tabs.Content | prop | type | default | description | | -------------- | ----------------- | ------- | --------------------------------------------------- | | `children` | `React.ReactNode` | - | Children elements to be rendered inside the content | | `value` | `string` | - | The value of the tab this content belongs to | | `className` | `string` | - | Additional CSS classes | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ## Hooks ### useTabs Hook to access tabs root context values within custom components or compound components. ```tsx import { useTabs } from 'heroui-native'; const CustomComponent = () => { const { value, onValueChange, nativeID } = useTabs(); // ... your implementation }; ``` **Returns:** `UseTabsReturn` | property | type | description | | --------------- | ------------------------- | ------------------------------------------ | | `value` | `string` | Currently active tab value | | `onValueChange` | `(value: string) => void` | Callback function to change the active tab | | `nativeID` | `string` | Unique identifier for the tabs instance | **Note:** This hook must be used within a `Tabs` component. It will throw an error if called outside of the tabs context. ### useTabsMeasurements Hook to access tab measurements context values for managing tab trigger positions and dimensions. ```tsx import { useTabsMeasurements } from 'heroui-native'; const CustomIndicator = () => { const { measurements, variant } = useTabsMeasurements(); // ... your implementation }; ``` **Returns:** `UseTabsMeasurementsReturn` | property | type | description | | ----------------- | ------------------------------------------------------- | ------------------------------------------------- | | `measurements` | `Record` | Record of measurements for each tab trigger | | `setMeasurements` | `(key: string, measurements: ItemMeasurements) => void` | Function to update measurements for a tab trigger | | `variant` | `'pill' \| 'line'` | Visual variant of the tabs | #### ItemMeasurements | property | type | description | | -------- | -------- | ----------------------------------- | | `width` | `number` | Width of the tab trigger in pixels | | `height` | `number` | Height of the tab trigger in pixels | | `x` | `number` | X position of the tab trigger | **Note:** This hook must be used within a `Tabs` component. It will throw an error if called outside of the tabs context. ### useTabsTrigger Hook to access tab trigger context values within custom components or compound components. ```tsx import { useTabsTrigger } from 'heroui-native'; const CustomLabel = () => { const { value, isSelected, nativeID } = useTabsTrigger(); // ... your implementation }; ``` **Returns:** `UseTabsTriggerReturn` | property | type | description | | ------------ | --------- | ------------------------------------------ | | `value` | `string` | The value of this trigger | | `nativeID` | `string` | Unique identifier for this trigger | | `isSelected` | `boolean` | Whether this trigger is currently selected | **Note:** This hook must be used within a `Tabs.Trigger` component. It will throw an error if called outside of the trigger context. # Dialog **Category**: native **URL**: https://v3.heroui.com/docs/native/components/dialog **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/native/components/(overlays)/dialog.mdx > Displays a modal overlay with animated transitions and gesture-based dismissal. ## Import ```tsx import { Dialog, useDialog, useDialogAnimation } from 'heroui-native'; ``` ## Anatomy ```tsx ... ... ... ... ... ``` * **Dialog**: Root component that manages open state and provides context to child components. * **Dialog.Trigger**: Pressable element that opens the dialog when pressed. * **Dialog.Portal**: Renders dialog content in a portal with centered layout and animation control. * **Dialog.Overlay**: Background overlay that appears behind the dialog content, typically closes dialog when pressed. * **Dialog.Content**: Main dialog container with gesture support for drag-to-dismiss. * **Dialog.Close**: Close button that dismisses the dialog when pressed. * **Dialog.Title**: Dialog title text with semantic heading role. * **Dialog.Description**: Dialog description text that provides additional context. ## Usage ### Basic Dialog Simple dialog with title, description, and close button. ```tsx ... ... ``` ### Custom Animations Configure open and close animations with spring or timing. The `closeDelay` should typically match your closing animation duration. ```tsx ... ... ``` ### Custom Backdrop Replace the default overlay with custom content. ```tsx ... ... ``` ### Scrollable Content Handle long content with scroll views. ```tsx ... ... ... ``` ### Form Dialog Dialog with text inputs and keyboard handling. ```tsx ... ... ... ``` ## 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 ( Confirm Action Are you sure you want to proceed with this action? This cannot be undone. ); } ``` ## API Reference ### Dialog | prop | type | default | description | | -------------------------- | -------------------------- | ------- | ------------------------------------------------------------------------------------ | | `children` | `React.ReactNode` | - | Dialog content and trigger elements | | `isOpen` | `boolean` | - | Controlled open state of the dialog | | `isDefaultOpen` | `boolean` | `false` | Initial open state when uncontrolled | | `closeDelay` | `number` | `300` | Delay in milliseconds before dialog closes (should match closing animation duration) | | `isDismissKeyboardOnClose` | `boolean` | `true` | Whether to dismiss keyboard when dialog closes | | `animation` | `DialogRootAnimation` | - | Animation configuration | | `onOpenChange` | `(value: boolean) => void` | - | Callback when open state changes | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | #### DialogRootAnimation Animation configuration for dialog root component. Can be: * `false` or `"disabled"`: Disable only root animations * `"disable-all"`: Disable all animations including children * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ---------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------- | | `entering.value` | `SpringAnimationConfig \| TimingAnimationConfig` | `{ type: 'timing',`
`config: { duration: 200,`
`easing: Easing.out(Easing.ease) } }` | Animation configuration for opening | | `exiting.value` | `SpringAnimationConfig \| TimingAnimationConfig` | `{ type: 'timing',`
`config: { duration: 150,`
`easing: Easing.bezier(0.4, 0, 1, 1) } }` | Animation configuration for closing | #### 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 | ### Dialog.Trigger | prop | type | default | description | | ------------------- | ----------------- | ------- | ------------------------------------------------------------ | | `children` | `React.ReactNode` | - | Trigger element content | | `asChild` | `boolean` | - | Render as child element without wrapper | | `...PressableProps` | `PressableProps` | - | All standard React Native PressableProps props are supported | ### Dialog.Portal | prop | type | default | description | | ------------ | ---------------------- | ------- | ------------------------------------------------ | | `children` | `React.ReactNode` | - | Portal content (overlay and dialog) | | `className` | `string` | - | Additional CSS classes for portal container | | `style` | `StyleProp` | - | Additional styles for portal container | | `hostName` | `string` | - | Optional portal host name for specific container | | `forceMount` | `boolean` | - | Force mount when closed for animation purposes | ### Dialog.Overlay | prop | type | default | description | | ------------------- | ------------------------ | ------- | ------------------------------------------------------- | | `children` | `React.ReactNode` | - | Custom overlay content | | `className` | `string` | - | Additional CSS classes for overlay | | `style` | `ViewStyle` | - | Additional styles for overlay container | | `animation` | `DialogOverlayAnimation` | - | Animation configuration | | `isCloseOnPress` | `boolean` | `true` | Whether pressing overlay closes dialog | | `forceMount` | `boolean` | - | Force mount when closed for animation purposes | | `...PressableProps` | `PressableProps` | - | All standard React Native Pressable props are supported | #### DialogOverlayAnimation Animation configuration for dialog overlay component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | --------------- | -------------------------- | ----------- | ----------------------------------- | | `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values \[idle, open, close] | ### Dialog.Content | prop | type | default | description | | ----------------------- | ------------------------------------ | ------- | --------------------------------------------------- | | `children` | `React.ReactNode` | - | Dialog content | | `className` | `string` | - | Additional CSS classes for content container | | `style` | `StyleProp` | - | Additional styles for content container | | `onLayout` | `(event: LayoutChangeEvent) => void` | - | Layout event handler | | `animation` | `DialogContentAnimation` | - | Animation configuration | | `isSwipeable` | `boolean` | `true` | Whether the dialog content can be swiped to dismiss | | `forceMount` | `boolean` | - | Force mount when closed for animation purposes | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | #### DialogContentAnimation Animation configuration for dialog content component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | --------------- | -------------------------- | ----------------- | ----------------------------------- | | `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values \[idle, open, close] | | `scale.value` | `[number, number, number]` | `[0.97, 1, 0.97]` | Scale values \[idle, open, close] | ### Dialog.Close | prop | type | default | description | | -------------------------- | ----------------------- | ------- | -------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Custom close button content | | `className` | `string` | - | Additional CSS classes for close button | | `iconProps` | `DialogCloseIconProps` | - | Configuration for default close icon | | `hitSlop` | `number` | `12` | Hit slop area for the close button | | `asChild` | `boolean` | - | Render as child element without wrapper | | `...TouchableOpacityProps` | `TouchableOpacityProps` | - | All standard React Native TouchableOpacity props are supported | #### DialogCloseIconProps | prop | type | description | | ------- | -------- | --------------------------------------- | | `size` | `number` | Icon size (default: 18) | | `color` | `string` | Icon color (default: theme color muted) | ### Dialog.Title | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Title content | | `className` | `string` | - | Additional CSS classes for title | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### Dialog.Description | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Description content | | `className` | `string` | - | Additional CSS classes for description | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ## Hooks ### useDialog Hook to access dialog primitive context. ```tsx const { isOpen, onOpenChange } = useDialog(); ``` | property | type | description | | -------------- | -------------------------- | ----------------------------- | | `isOpen` | `boolean` | Current open state | | `onOpenChange` | `(value: boolean) => void` | Function to change open state | ### useDialogAnimation Hook to access dialog animation context for advanced customization. ```tsx const { dialogState, progress, isDragging, isGestureReleaseAnimationRunning } = useDialogAnimation(); ``` | property | type | description | | ---------------------------------- | ----------------------------- | -------------------------------------------- | | `dialogState` | `'idle' \| 'open' \| 'close'` | Internal dialog state | | `progress` | `SharedValue` | Animation progress (0=idle, 1=open, 2=close) | | `isDragging` | `SharedValue` | Whether dialog is being dragged | | `isGestureReleaseAnimationRunning` | `SharedValue` | Whether gesture release animation is running | # 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**: Main container that manages open/close state, positioning, and provides context to child components. * **Popover.Trigger**: Clickable element that toggles popover visibility. Wraps any child element with press handlers. * **Popover.Portal**: Renders popover content in a portal layer above other content. Ensures proper stacking and positioning. * **Popover.Overlay**: Optional background overlay. Can be transparent or semi-transparent to capture outside clicks. * **Popover.Content**: Container for popover content with positioning, styling, and collision detection. Supports both popover and bottom-sheet presentations. * **Popover.Arrow**: Optional arrow element pointing to the trigger. Automatically positioned based on placement. * **Popover.Close**: Close button that dismisses the popover when pressed. Renders a default X icon if no children provided. * **Popover.Title**: Optional title text with pre-styled typography. * **Popover.Description**: Optional description text with muted styling. ## Usage ### Basic Usage The Popover component uses compound parts to create floating content panels. ```tsx ... ... ``` ### With Title and Description Structure popover content with title and description for better information hierarchy. ```tsx ... ... ... ``` ### With Arrow Add an arrow pointing to the trigger element for better visual connection. ```tsx ... ... ``` ### Width Control Control the width of the popover content using the `width` prop. ```tsx { /* Fixed width in pixels */ } ... ... ; { /* Match trigger width */ } ... ... ; { /* Full width (100%) */ } ... ... ; { /* Auto-size to content (default) */ } ... ... ; ``` ### Bottom Sheet Presentation Use bottom sheet presentation for mobile-optimized interaction patterns. ```tsx ... ... ... ``` ### Placement Options Control where the popover appears relative to the trigger element. ```tsx ... ... ``` ### Alignment Options Fine-tune content alignment along the placement axis. ```tsx ... ... ``` ### Custom Animation Configure custom animations for open and close transitions using the `animation` prop on `Popover.Root`. ```tsx ... ... ``` ### Programmatic control ```tsx // Open or close popover programmatically using ref const popoverRef = useRef(null); // Open programmatically popoverRef.current?.open(); // Close programmatically popoverRef.current?.close(); // Full example Content ; ``` ## 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 ( Information This popover includes a title and description to provide more structured information to users. ); } ``` ## API Reference ### Popover | prop | type | default | description | | --------------- | --------------------------- | ------- | ------------------------------------------------------------------------- | | `children` | `ReactNode` | - | Children elements to be rendered inside the popover | | `isOpen` | `boolean` | - | Whether the popover is open (controlled mode) | | `isDefaultOpen` | `boolean` | - | The open state of the popover when initially rendered (uncontrolled mode) | | `onOpenChange` | `(isOpen: boolean) => void` | - | Callback when the popover open state changes | | `closeDelay` | `number` | `400` | Delay in milliseconds before closing the popover | | `animation` | `PopoverRootAnimation` | - | Animation configuration | | `asChild` | `boolean` | `false` | Whether to render as a child element | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | #### PopoverRootAnimation Animation configuration for popover root component. Can be: * `false` or `"disabled"`: Disable only root animations * `"disable-all"`: Disable all animations including children * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ---------------- | ------------------------------------------------ | -------------------------------------------------------------------------------------------------- | ----------------------------------- | | `entering.value` | `SpringAnimationConfig \| TimingAnimationConfig` | `{ type: 'timing',`
`config: { duration: 200,`
`easing: Easing.out(Easing.ease) } }` | Animation configuration for opening | | `exiting.value` | `SpringAnimationConfig \| TimingAnimationConfig` | `{ type: 'timing',`
`config: { duration: 150,`
`easing: Easing.bezier(0.4, 0, 1, 1) } }` | Animation configuration for closing | #### 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 | ### 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) | | `hostName` | `string` | - | Optional name of the host element for the portal | | `forceMount` | `boolean` | - | Whether to force mount the component in the DOM | | `className` | `string` | - | Additional CSS classes for the portal container | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Popover.Overlay | prop | type | default | description | | ----------------------- | ------------------------- | ------- | ---------------------------------------------------- | | `className` | `string` | - | Additional CSS classes for the overlay | | `closeOnPress` | `boolean` | `true` | Whether to close the popover when overlay is pressed | | `forceMount` | `boolean` | - | Whether to force mount the component in the DOM | | `animation` | `PopoverOverlayAnimation` | - | Animation configuration | | `asChild` | `boolean` | `false` | Whether to render as a child element | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | #### PopoverOverlayAnimation Animation configuration for popover overlay component. Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | --------------- | -------------------------- | ----------- | ----------------------------------- | | `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values \[idle, open, close] | ### Popover.Content (Popover Presentation) | prop | type | default | description | | ------------------------- | ------------------------------------------------ | --------------- | ------------------------------------------------------ | | `children` | `ReactNode` | - | The popover content | | `width` | `number \| 'trigger' \| 'content-fit' \| 'full'` | `'content-fit'` | Width sizing strategy for the content | | `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | Placement of the popover relative to trigger | | `align` | `'start' \| 'center' \| 'end'` | `'center'` | Alignment along the placement axis | | `avoidCollisions` | `boolean` | `true` | Whether to flip placement when close to viewport edges | | `offset` | `number` | `8` | Distance from trigger element in pixels | | `alignOffset` | `number` | `0` | Offset along the alignment axis in pixels | | `disablePositioningStyle` | `boolean` | `false` | Whether to disable automatic positioning styles | | `forceMount` | `boolean` | - | Whether to force mount the component in the DOM | | `insets` | `Insets` | - | Screen edge insets to respect when positioning | | `className` | `string` | - | Additional CSS classes for the content container | | `presentation` | `'popover'` | - | Presentation mode for the popover | | `animation` | `PopupPopoverContentAnimation` | - | Animation configuration | | `asChild` | `boolean` | `false` | Whether to render as a child element | | `...Animated.ViewProps` | `Animated.ViewProps` | - | All Reanimated Animated.View props are supported | ### Popover.Content (Bottom Sheet Presentation) | prop | type | default | description | | -------------------------- | ---------------------- | ------- | ------------------------------------------------ | | `children` | `ReactNode` | - | The bottom sheet content | | `presentation` | `'bottom-sheet'` | - | Presentation mode for the popover | | `bottomSheetViewClassName` | `string` | - | Additional CSS classes for the bottom sheet view | | `bottomSheetViewProps` | `BottomSheetViewProps` | - | Props for the bottom sheet view | | `enablePanDownToClose` | `boolean` | `true` | Whether pan down gesture closes the sheet | | `backgroundStyle` | `ViewStyle` | - | Style for the bottom sheet background | | `handleIndicatorStyle` | `ViewStyle` | - | Style for the bottom sheet handle indicator | | `...BottomSheetProps` | `BottomSheetProps` | - | All @gorhom/bottom-sheet props are supported | #### PopupPopoverContentAnimation Animation configuration for popover content component (popover presentation). Can be: * `false` or `"disabled"`: Disable all animations * `true` or `undefined`: Use default animations * `object`: Custom animation configuration | prop | type | default | description | | ----------------------- | -------------------------- | ---------------------------------------------------------------- | -------------------------------------- | | `opacity.value` | `[number, number, number]` | `[0, 1, 0]` | Opacity values \[idle, open, close] | | `scale.value` | `[number, number, number]` | `[0.95, 1, 0.95]` | Scale values \[idle, open, close] | | `translateX.value` | `[number, number, number]` | Based on placement
`(4, 0, 4)` or `(-4, 0, -4)` | TranslateX values \[idle, open, close] | | `translateY.value` | `[number, number, number]` | Based on placement
`(4, 0, 4)` or `(-4, 0, -4)` | TranslateY values \[idle, open, close] | | `transformOrigin.value` | `string` | Based on placement
`'top'`, `'bottom'`, `'left'`, `'right'` | Transform origin value | ### Popover.Arrow | prop | type | default | description | | --------------------- | ---------------------------------------- | ------- | --------------------------------------------------------------------- | | `className` | `string` | - | Additional CSS classes for the arrow | | `height` | `number` | `8` | Height of the arrow in pixels | | `width` | `number` | `16` | Width of the arrow in pixels | | `fill` | `string` | - | Fill color of the arrow (defaults to content background) | | `stroke` | `string` | - | Stroke (border) color of the arrow (defaults to content border color) | | `strokeWidth` | `number` | `1` | Stroke width of the arrow border in pixels | | `strokeBaselineInset` | `number` | `1` | Baseline inset in pixels for stroke alignment | | `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | - | Placement of the popover (inherited from content) | | `children` | `ReactNode` | - | Custom arrow content (replaces default SVG arrow) | | `style` | `StyleProp` | - | Additional styles for the arrow container | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | ### Popover.Close | prop | type | default | description | | ------------------- | ----------------------- | ------- | ------------------------------------------------------- | | `children` | `ReactNode` | - | The close button content | | `className` | `string` | - | Additional CSS classes for the close button | | `iconProps` | `PopoverCloseIconProps` | - | Close icon configuration | | `hitSlop` | `number \| Insets` | `12` | Additional touch area around the button | | `asChild` | `boolean` | - | Whether to render as a child element | | `...PressableProps` | `PressableProps` | - | All standard React Native Pressable props are supported | #### PopoverCloseIconProps | prop | type | default | description | | ------- | -------- | ---------------- | ----------------- | | `size` | `number` | `18` | Size of the icon | | `color` | `string` | `--colors.muted` | Color of the icon | ### Popover.Title | prop | type | default | description | | -------------- | ----------- | ------- | -------------------------------------------------- | | `children` | `ReactNode` | - | The title text content | | `className` | `string` | - | Additional CSS classes for the title | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### Popover.Description | prop | type | default | description | | -------------- | ----------- | ------- | -------------------------------------------------- | | `children` | `ReactNode` | - | The description text content | | `className` | `string` | - | Additional CSS classes for the description | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ## Hooks ### usePopover Hook to access popover context values within custom components or compound components. ```tsx import { usePopover } from 'heroui-native'; const CustomContent = () => { const { isOpen, onOpenChange, triggerPosition } = usePopover(); // ... your implementation }; ``` **Returns:** `UsePopoverReturn` | property | type | description | | -------------------- | --------------------------------------------------- | ----------------------------------------------------------------- | | `isOpen` | `boolean` | Whether the popover is currently open | | `onOpenChange` | `(open: boolean) => void` | Callback function to change the popover open state | | `isDefaultOpen` | `boolean \| undefined` | Whether the popover should be open by default (uncontrolled mode) | | `isDisabled` | `boolean \| undefined` | Whether the popover is disabled | | `triggerPosition` | `LayoutPosition \| null` | The position of the trigger element relative to the viewport | | `setTriggerPosition` | `(triggerPosition: LayoutPosition \| null) => void` | Function to update the trigger element's position | | `contentLayout` | `LayoutRectangle \| null` | The layout measurements of the popover content | | `setContentLayout` | `(contentLayout: LayoutRectangle \| null) => void` | Function to update the content layout measurements | | `nativeID` | `string` | Unique identifier for the popover instance | | `closeDelay` | `number \| undefined` | Delay in milliseconds before the popover closes | **Note:** This hook must be used within a `Popover` component. It will throw an error if called outside of the popover context. ### usePopoverAnimation Hook to access popover animation state values within custom components or compound components. ```tsx import { usePopoverAnimation } from 'heroui-native'; const CustomContent = () => { const { popoverState, progress, isDragging } = usePopoverAnimation(); // ... your implementation }; ``` **Returns:** `UsePopoverAnimationReturn` | property | type | description | | -------------- | ----------------------------- | ------------------------------------------------------------------ | | `popoverState` | `'idle' \| 'open' \| 'close'` | Extended internal state for coordinating animations | | `progress` | `SharedValue` | Progress value for the popover animation (0=idle, 1=open, 2=close) | | `isDragging` | `SharedValue` | 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. # 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**: 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: , 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) => ( Custom Toast This is a custom toast component ), }); ``` **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) => ( No animations This toast has all animations disabled Action ), }); ``` ## 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 ( ); } ``` ## 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 {children} ``` ### 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) => ( {children} ), [] ); return ( {children} ); } ``` ### Default Props Set global defaults for variant, placement, animation, and swipe behavior: ```tsx {children} ``` ## API Reference ### Toast | prop | type | default | description | | -------------- | ------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------- | | `variant` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Visual variant of the toast | | `placement` | `'top' \| 'bottom'` | `'top'` | Placement of the toast on screen | | `isSwipeable` | `boolean` | `true` | Whether the toast can be swiped to dismiss and dragged with rubber effect | | `animation` | `ToastRootAnimation` | - | Animation configuration | | `className` | `string` | - | Additional CSS class for the toast container | | `...ViewProps` | `ViewProps` | - | All standard React Native View props are supported | #### ToastRootAnimation Animation configuration for Toast component. Can be: * `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 | | ------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | | `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`
`.springify()`
`.withInitialValues({ opacity: 1, transform: [{ translateY: -100 }] })`
`.mass(3)` | Custom entering animation for top placement | | `entering.bottom` | `EntryOrExitLayoutType` | `FadeInDown`
`.springify()`
`.withInitialValues({ opacity: 1, transform: [{ translateY: 100 }] })`
`.mass(3)` | Custom entering animation for bottom placement | | `exiting.top` | `EntryOrExitLayoutType` | Keyframe animation with
`translateY: -100, scale: 0.97, opacity: 0.5` | Custom exiting animation for top placement | | `exiting.bottom` | `EntryOrExitLayoutType` | Keyframe animation with
`translateY: 100, scale: 0.97, opacity: 0.5` | Custom exiting animation for bottom placement | ### Toast.Title | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Content to be rendered as title | | `className` | `string` | - | Additional CSS classes | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### Toast.Description | prop | type | default | description | | -------------- | ----------------- | ------- | -------------------------------------------------- | | `children` | `React.ReactNode` | - | Content to be rendered as description | | `className` | `string` | - | Additional CSS classes | | `...TextProps` | `TextProps` | - | All standard React Native Text props are supported | ### Toast.Action Toast.Action extends all props from [Button](button) component. Button variant is automatically determined based on toast variant but can be overridden. | prop | type | default | description | | ----------- | ---------------------- | ------- | ---------------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Content to be rendered as action button label | | `variant` | `ButtonVariant` | - | Button variant. If not provided, automatically determined from toast variant | | `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Size of the action button | | `className` | `string` | - | Additional CSS classes | For inherited props including `onPress`, `isDisabled`, and all Button props, see [Button API Reference](button#api-reference). ### Toast.Close Toast.Close extends all props from [Button](button) component. | prop | type | default | description | | ----------- | ----------------------------------- | ------- | ---------------------------------------------- | | `children` | `React.ReactNode` | - | Custom close icon. Defaults to CloseIcon | | `iconProps` | `{ size?: number; color?: string }` | - | Props for the default close icon | | `size` | `'sm' \| 'md' \| 'lg'` | `'sm'` | Size of the close button | | `className` | `string` | - | Additional CSS classes | | `onPress` | `(event: any) => void` | - | Custom press handler. Defaults to hiding toast | For inherited props including `isDisabled` and all Button props, see [Button API Reference](button#api-reference). ### ToastProviderProps Props for configuring toast behavior globally via `HeroUINativeProvider` config prop. | prop | type | default | description | | ------------------ | --------------------------------------------------- | ------- | ---------------------------------------------------------------- | | `defaultProps` | `ToastGlobalConfig` | - | Global toast configuration used as defaults for all toasts | | `insets` | `ToastInsets` | - | Insets for spacing from screen edges (added to safe area insets) | | `maxVisibleToasts` | `number` | `3` | Maximum number of visible toasts before opacity starts fading | | `contentWrapper` | `(children: React.ReactNode) => React.ReactElement` | - | Custom wrapper function to wrap toast content | | `children` | `React.ReactNode` | - | Children to render | #### ToastGlobalConfig Global toast configuration used as defaults for all toasts unless overridden locally. | prop | type | description | | ------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------- | | `variant` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | Visual variant of the toast | | `placement` | `'top' \| 'bottom'` | Placement of the toast on screen | | `isSwipeable` | `boolean` | Whether the toast can be swiped to dismiss and dragged with rubber effect | | `animation` | `ToastRootAnimation` | Animation configuration for toast | #### ToastInsets Insets for spacing from screen edges. Values are added to safe area insets. | prop | type | default | description | | -------- | -------- | ------- | --------------------------------------------------------------------------------------------------------- | | `top` | `number` | - | Inset from the top edge in pixels (added to safe area inset). Platform-specific: iOS = 0, Android = 12 | | `bottom` | `number` | - | Inset from the bottom edge in pixels (added to safe area inset). Platform-specific: iOS = 6, Android = 12 | | `left` | `number` | - | Inset from the left edge in pixels (added to safe area inset). Default: 12 | | `right` | `number` | - | Inset from the right edge in pixels (added to safe area inset). Default: 12 | ## Hooks ### useToast Hook to access toast functionality. Must be used within a `ToastProvider` (provided by `HeroUINativeProvider`). | return value | type | description | | ---------------- | -------------- | ---------------------------------------- | | `toast` | `ToastManager` | Toast manager with show and hide methods | | `isToastVisible` | `boolean` | Whether any toast is currently visible | #### ToastManager | method | type | description | | ------ | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | `show` | `(options: string \| ToastShowOptions) => string` | Show a toast. Returns the ID of the shown toast. Supports three usage patterns: simple string, config object, or custom component | | `hide` | `(ids?: string \| string[] \| 'all') => void` | Hide one or more toasts. No argument hides the last toast, 'all' hides all toasts, single ID or array of IDs hides specific toast(s) | #### ToastShowOptions Options for showing a toast. Can be either a config object with default styling or a custom component. **When using config object (without component):** | prop | type | default | description | | --------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- | | `variant` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | Visual variant of the toast | | `placement` | `'top' \| 'bottom'` | - | Placement of the toast on screen | | `isSwipeable` | `boolean` | - | Whether the toast can be swiped to dismiss | | `animation` | `ToastRootAnimation \| false \| "disabled" \| "disable-all"` | - | Animation configuration for toast | | `duration` | `number \| 'persistent'` | `4000` | Duration in milliseconds before auto-hide. Set to 'persistent' to prevent auto-hide | | `id` | `string` | - | Optional ID for the toast. If not provided, one will be generated | | `label` | `string` | - | Label text for the toast | | `description` | `string` | - | Description text for the toast | | `actionLabel` | `string` | - | Action button label text | | `onActionPress` | `(helpers: { show: (options: string \| ToastShowOptions) => string; hide: (ids?: string \| string[] \| 'all') => void }) => void` | - | Callback function called when the action button is pressed | | `icon` | `React.ReactNode` | - | Icon element to display in the toast | | `onShow` | `() => void` | - | Callback function called when the toast is shown | | `onHide` | `() => void` | - | Callback function called when the toast is hidden | **When using custom component:** | prop | type | default | description | | ----------- | ---------------------------------------------------- | ------- | ----------------------------------------------------------------------------------- | | `id` | `string` | - | Optional ID for the toast. If not provided, one will be generated | | `component` | `(props: ToastComponentProps) => React.ReactElement` | - | A function that receives toast props and returns a React element | | `duration` | `number \| 'persistent'` | `4000` | Duration in milliseconds before auto-hide. Set to 'persistent' to prevent auto-hide | | `onShow` | `() => void` | - | Callback function called when the toast is shown | | `onHide` | `() => void` | - | Callback function called when the toast is hidden | ## Special Notes ### Styling Notes #### Border as Padding Toast uses `border-[16px]` class which serves as padding. This is intentional because when visible toasts have different heights, the toast adapts to the last visible toast height. In cases where a toast originally has one height and gets smaller when a new toast comes to stack, content might be visible behind the last toast without proper padding. The border ensures consistent spacing regardless of toast height changes. For padding, use `border` classes. For actual borders, use `outline` classes. # 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 ... ``` ### Highlight Variant Default iOS-style highlight feedback effect with automatic scale animation. ```tsx ... ``` ### Ripple Variant Android-style ripple feedback effect that emanates from the press point, combined with scale animation. ```tsx ... ``` ### Custom Highlight Animation Configure highlight overlay opacity and background color while maintaining the default scale effect. ```tsx ... ``` ### Custom Ripple Animation Configure ripple effect color, opacity, and duration along with scale animation. ```tsx ... ``` ### Feedback Position Control whether the feedback effect renders above or below content. ```tsx ... ... ``` ### Custom Scale Animation Customize or disable the default scale animation on press. ```tsx ... ... ``` ### Disabled State Disable press interactions and all feedback animations. ```tsx ... ``` ## Example ```tsx import { PressableFeedback, Card } from 'heroui-native'; import { View, Text, Image } from 'react-native'; export default function PressableFeedbackExample() { return ( Indie Hackers 148 members @indiehackers AI Builders 362 members @aibuilders ); } ``` ## API Reference ### PressableFeedback | prop | type | default | description | | ------------------ | --------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Content to be wrapped with press feedback | | `feedbackVariant` | `'highlight' \| 'ripple'` | `'highlight'` | Type of feedback effect to display | | `feedbackPosition` | `'behind' \| 'top'` | `'top'` | Controls z-index positioning of feedback effect relative to children | | `isDisabled` | `boolean` | `false` | Whether the pressable component is disabled | | `className` | `string` | - | Additional CSS classes | | `animation` | `PressableFeedbackHighlightRootAnimation \| PressableFeedbackRippleRootAnimation` | - | Animation configuration | | `...AnimatedProps` | `AnimatedProps` | - | All Reanimated Animated Pressable props are supported | #### PressableFeedbackHighlightRootAnimation Animation configuration for PressableFeedback component with highlight variant. 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 | | ------------------------------------------------- | ------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------- | | `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 | | `highlight`
`.opacity`
`.value` | `[number, number]` | `[0, 0.1]` | Opacity values \[unpressed, pressed] | | `highlight`
`.opacity`
`.timingConfig` | `WithTimingConfig` | `{ duration: 200 }` | Animation timing configuration | | `highlight`
`.backgroundColor`
`.value` | `string` | Computed based on theme | Background color of highlight overlay | #### PressableFeedbackRippleRootAnimation Animation configuration for PressableFeedback component with ripple variant. 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 | | ----------------------------------------------------------- | -------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------- | | `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 | | `ripple`
`.backgroundColor`
`.value` | `string` | Computed based on theme | Background color of ripple effect | | `ripple`
`.progress`
`.baseDuration` | `number` | `1000` | Base duration for ripple progress (automatically adjusted based on diagonal) | | `ripple`
`.progress`
`.minBaseDuration` | `number` | - | Minimum base duration for the ripple progress animation | | `ripple`
`.progress`
`.ignoreDurationCoefficient` | `boolean` | `false` | Ignore automatic duration coefficient and use base duration directly | | `ripple`
`.opacity`
`.value` | `[number, number, number]` | `[0, 0.1, 0]` | Opacity values \[start, peak, end] for ripple animation | | `ripple`
`.opacity`
`.timingConfig` | `WithTimingConfig` | `{ duration: 30 }` | Animation timing configuration | | `ripple`
`.scale`
`.value` | `[number, number, number]` | `[0, 1, 1]` | Scale values \[start, peak, end] for ripple animation | | `ripple`
`.scale`
`.timingConfig` | `WithTimingConfig` | `{ duration: 30 }` | Animation timing configuration | # 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**: 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 ... ``` ### Horizontal Scrolling The component auto-detects horizontal scrolling from the child's `horizontal` prop. ```tsx ``` ### Custom Shadow Size Control the gradient shadow height/width with the `size` prop. ```tsx ... ``` ### Visibility Control Specify which shadows to display using the `visibility` prop. ```tsx ... ... ... ``` ### Custom Shadow Color Override the default shadow color which uses the theme's background. ```tsx ... ``` ### 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); }, }); ... ; ``` ## 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 ( Horizontal List ( {item.title} )} showsHorizontalScrollIndicator={false} contentContainerClassName="p-5 gap-4" /> Vertical Content Long Content 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. 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. ); } ``` ## 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<`
`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: * `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 | | --------------- | ------------------ | -------- | ------------------------------------------------------------------------------------ | | `opacity.value` | `[number, number]` | `[0, 1]` | `Opacity values [initial, active].`
`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` (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. # 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 (
{/* Single button with dropdown */}
All commits from this branch will be added to the base branch The 14 commits from this branch will be combined into one commit in the base branch The 14 commits from this branch will be rebased and added to the base branch
{/* Individual buttons */}
{/* Previous/Next Button Group */}
{/* Content Selection Button Group */}
{/* Text Alignment Button Group */}
{/* Icon-Only Alignment Button Group */}
); } ``` ### Anatomy ```tsx import { ButtonGroup, Button } from '@heroui/react'; export default () => ( ) ``` > **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 (

Primary

Secondary

Tertiary

Ghost

Danger

); } ``` ### Sizes ```tsx import {Button, ButtonGroup} from "@heroui/react"; export function Sizes() { return (

Small

Medium (default)

Large

); } ``` ### With Icons ```tsx import {Globe, Plus, TrashBin} from "@gravity-ui/icons"; import {Button, ButtonGroup} from "@heroui/react"; export function WithIcons() { return (

With icons

Icon only buttons

); } ``` ### Full Width ```tsx import {TextAlignCenter, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons"; import {Button, ButtonGroup} from "@heroui/react"; export function FullWidth() { return (
); } ``` ### Disabled State ```tsx import {Button, ButtonGroup} from "@heroui/react"; export function Disabled() { return (

All buttons disabled

Group disabled, but one button overrides

); } ``` ### Without Separator ```tsx import {Button, ButtonGroup} from "@heroui/react"; export function WithoutSeparator() { return ( ); } ``` ## 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 ( ); } ``` ### Customizing the component classes To customize the ButtonGroup component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .button-group { @apply gap-2 rounded-lg; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The ButtonGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)): #### Base Classes * `.button-group` - Base button group container The ButtonGroup component automatically applies border radius to buttons: * First button gets rounded left/start edge * Last button gets rounded right/end edge * Middle buttons have no border radius * Single button gets full border radius on all edges Separators are automatically added between buttons using a pseudo-element (`:before`) on buttons that are not the first child. ## API Reference ### ButtonGroup Props | Prop | Type | Default | Description | | --------------- | --------------------------------------------------------------- | ------- | --------------------------------------------------------------------------------------- | | `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'` | - | Visual style variant applied to all buttons in the group | | `size` | `'sm' \| 'md' \| 'lg'` | - | Size applied to all buttons in the group | | `fullWidth` | `boolean` | `false` | Whether the button group should take full width of its container | | `isDisabled` | `boolean` | `false` | Whether all buttons in the group are disabled (can be overridden on individual buttons) | | `hideSeparator` | `boolean` | `false` | Hide separator lines between buttons | | `className` | `string` | - | Additional CSS classes | | `children` | `React.ReactNode` | - | Button components to group together | ### Notes * ButtonGroup uses React Context to pass `size`, `variant`, and `isDisabled` props to all child Button components * Individual Button components can override the group's `isDisabled` prop by setting `isDisabled={false}` * The component automatically handles border radius and separators between buttons * Buttons in a group have their active/pressed scale transform removed for a more cohesive appearance # 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 ; } ``` ### Variants ```tsx import {Button} from "@heroui/react"; export function Variants() { return (
); } ``` ### With Icons ```tsx import {Envelope, Globe, Plus, TrashBin} from "@gravity-ui/icons"; import {Button} from "@heroui/react"; export function WithIcons() { return (
); } ``` ### Icon Only ```tsx import {Ellipsis, Gear, TrashBin} from "@gravity-ui/icons"; import {Button} from "@heroui/react"; export function IconOnly() { return (
); } ``` ### Loading ```tsx "use client"; import {Button, Spinner} from "@heroui/react"; import React from "react"; export function Loading() { return ( ); } ``` ### 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 ( ); } ``` ### Sizes ```tsx import {Button} from "@heroui/react"; export function Sizes() { return (
); } ``` ### Full Width ```tsx import {Plus} from "@gravity-ui/icons"; import {Button} from "@heroui/react"; export function FullWidth() { return (
); } ``` ### Disabled State ```tsx import {Button} from "@heroui/react"; export function Disabled() { return (
); } ``` ### Social Buttons ```tsx import {Button} from "@heroui/react"; import {Icon} from "@iconify/react"; export function Social() { return (
); } ``` ## 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 ( ); } ``` ### Customizing the component classes To customize the Button component classes, you can use the `@layer components` directive.
[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; export type MyButtonProps = Omit & MyButtonVariants & {className?: string}; function CustomButton({className, radius, variant, ...props}: MyButtonProps) { return console.log(`Selected: ${key}`)}> ); } ``` ### 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 () => (
Select a fruit
 ); } ``` ### 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(new Set(["apple"])); const CustomCheckmarkIcon = ( ); return (
Select a fruit
{({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)} {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)} {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)} {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)} {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)} ); } ``` ### 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(new Set(["apple"])); return (
Select a fruit
 ); } ``` ### 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(new Set(["bold", "italic"])); const [textAlignment, setTextAlignment] = useState(new Set(["left"])); return (
Actions
X C U
Text Style
B I U
Text Alignment
A H D ); } ``` ### With Keyboard Shortcuts ```tsx "use client"; import {Button, Dropdown, Kbd, Label} from "@heroui/react"; export function WithKeyboardShortcuts() { return ( console.log(`Selected: ${key}`)}> N O S D ); } ``` ### 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 ( console.log(`Selected: ${key}`)}> N O S D ); } ``` ### Long Press Trigger ```tsx import {Button, Dropdown, Label} from "@heroui/react"; export function LongPressTrigger() { return ( ); } ``` ### 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 ( console.log(`Selected: ${key}`)}>
Create a new file
N
Open an existing file
O
Save the current file
S
Move to trash
D ); } ``` ### 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 ( console.log(`Selected: ${key}`)}>
Actions
Create a new file
N
Make changes
E
Danger zone
Move to trash
D ); } ``` ### 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 ( console.log(`Selected: ${key}`)} >
Actions
Create a new file
N
Make changes
E
Danger zone
Move to trash
D ); } ``` ### With Submenus ```tsx "use client"; import {Button, Dropdown, Label} from "@heroui/react"; export function WithSubmenus() { return ( console.log(`Selected: ${key}`)}> ); } ``` ### With Custom Submenu Indicator ```tsx "use client"; import {ArrowRight} from "@gravity-ui/icons"; import {Button, Dropdown, Label} from "@heroui/react"; export function WithCustomSubmenuIndicator() { return ( console.log(`Selected: ${key}`)}> ); } ``` ### 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(new Set(["bold"])); const selectedItems = Array.from(selected); return (

Selected: {selectedItems.length > 0 ? selectedItems.join(", ") : "None"}

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

Dropdown is: {open ? "open" : "closed"}

); } ``` ### Custom Trigger ```tsx import {ArrowRightFromSquare, Gear, Persons} from "@gravity-ui/icons"; import {Avatar, Dropdown, Label} from "@heroui/react"; export function CustomTrigger() { return ( JD
JD

Jane Doe

jane@example.com
); } ``` ## 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 ( Item 1 ); } ``` ### Customizing the component classes To customize the Dropdown component classes, you can use the `@layer components` directive.
[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` | - | The currently selected keys (controlled) | | `defaultSelectedKeys` | `Iterable` | - | The initial selected keys (uncontrolled) | | `onSelectionChange` | `(keys: Selection) => void` | - | Handler called when the selection changes | | `disabledKeys` | `Iterable` | - | 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` | - | The currently selected keys (controlled) | | `defaultSelectedKeys` | `Iterable` | - | The initial selected keys (uncontrolled) | | `onSelectionChange` | `(keys: Selection) => void` | - | Handler called when the selection changes | | `disabledKeys` | `Iterable` | - | 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'; alert(`Selected: ${key}`)}> ``` ### With Sections ```tsx import { Dropdown, Button, Label, Header, Separator } from '@heroui/react'; alert(`Selected: ${key}`)}>
Actions
Danger zone
 ``` ### 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(new Set(['bold'])); return ( ); } ``` ### With Submenus ```tsx import { Dropdown, Button, Label } from '@heroui/react'; alert(`Selected: ${key}`)}> ``` ## 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). # ListBox **Category**: react **URL**: https://v3.heroui.com/docs/react/components/listbox **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(collections)/listbox.mdx > A listbox displays a list of options and allows a user to select one or more of them ## Import ```tsx import { ListBox } from '@heroui/react'; ``` ### Usage ```tsx import {Avatar, Description, Label, ListBox} from "@heroui/react"; export function Default() { return ( B
bob@heroui.com
F
fred@heroui.com
M
martha@heroui.com
); } ``` ### Anatomy Import the ListBox component and access all parts using dot notation. ```tsx import { ListBox, Label, Description, Header } from '@heroui/react'; export default () => (
) ``` ### 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 ( alert(`Selected item: ${key}`)} >
Actions
Create a new file
N
Make changes
E
Danger zone
Move to trash
D ); } ``` ### Multi Select ```tsx import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react"; export function MultiSelect() { return ( B
bob@heroui.com
F
fred@heroui.com
M
martha@heroui.com
); } ``` ### 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 ( alert(`Selected item: ${key}`)} >
Actions
Create a new file
N
Make changes
E
Danger zone
Move to trash
D ); } ``` ### 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 ( B
bob@heroui.com
{({isSelected}) => (isSelected ? : null)} F
fred@heroui.com
{({isSelected}) => (isSelected ? : null)} M
martha@heroui.com
{({isSelected}) => (isSelected ? : null)} ); } ``` ### 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(new Set(["1"])); const selectedItems = Array.from(selected); return (
B
bob@heroui.com
{({isSelected}) => (isSelected ? : null)} F
fred@heroui.com
{({isSelected}) => (isSelected ? : null)} M
martha@heroui.com
{({isSelected}) => (isSelected ? : null)}

Selected: {selectedItems.length > 0 ? selectedItems.join(", ") : "None"}

); } ``` ## 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 ( Item 1 ); } ``` ### Customizing the component classes To customize the ListBox component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .listbox { @apply rounded-lg border border-border bg-surface p-2; } .listbox-item { @apply rounded px-2 py-1 cursor-pointer; } .listbox-item--danger { @apply text-danger; } .listbox-item__indicator { @apply text-accent; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The ListBox component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/listbox.css)): #### Base Classes * `.listbox` - Base listbox container * `.listbox-item` - Individual listbox item * `.listbox-item__indicator` - Selection indicator icon * `.listbox-section` - Section container for grouping items #### Variant Classes * `.listbox--default` - Default variant styling * `.listbox--danger` - Danger variant styling * `.listbox-item--default` - Default item variant * `.listbox-item--danger` - Danger item variant #### State Classes * `.listbox-item[data-selected="true"]` - Selected item state * `.listbox-item[data-focus-visible="true"]` - Focused item state * `.listbox-item[data-disabled="true"]` - Disabled item state * `.listbox-item__indicator[data-visible="true"]` - Visible indicator state ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Hover**: `:hover` or `[data-hovered="true"]` on item * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on item * **Selected**: `[data-selected="true"]` on item * **Disabled**: `:disabled` or `[data-disabled="true"]` on item ## API Reference ### ListBox Props | Prop | Type | Default | Description | | --------------------- | ---------------------------------- | ----------- | ---------------------------------------- | | `aria-label` | `string` | - | Accessibility label for the listbox | | `aria-labelledby` | `string` | - | ID of element that labels the listbox | | `selectionMode` | `"none" \| "single" \| "multiple"` | `"single"` | Selection behavior | | `selectedKeys` | `Selection` | - | Controlled selected keys | | `defaultSelectedKeys` | `Selection` | - | Initial selected keys | | `onSelectionChange` | `(keys: Selection) => void` | - | Handler called when selection changes | | `disabledKeys` | `Iterable` | - | Keys of disabled items | | `onAction` | `(key: Key) => void` | - | Handler called when an item is activated | | `variant` | `"default" \| "danger"` | `"default"` | Visual variant | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | ListBox items and sections | ### ListBox.Item Props | Prop | Type | Default | Description | | ------------ | ----------------------------- | ----------- | ------------------------------------------ | | `id` | `Key` | - | Unique identifier for the item | | `textValue` | `string` | - | Text value for accessibility and typeahead | | `isDisabled` | `boolean` | `false` | Whether this item is disabled | | `variant` | `"default" \| "danger"` | `"default"` | Visual variant | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Item content or render function | ### ListBox.ItemIndicator Props | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | ------------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Custom indicator content or render function | ### ListBox.Section Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Section content including Header and Items | ### RenderProps When using render functions with ListBox.Item or ListBox.ItemIndicator, these values are provided: | 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 { ListBox, Label, Description } from '@heroui/react'; bob@heroui.com alice@heroui.com ``` ### With Sections ```tsx import { ListBox, Header, Separator } from '@heroui/react'; console.log(key)}>
Actions
New file Edit file
Danger zone
Delete ``` ### Controlled Selection ```tsx import { ListBox, Selection } from '@heroui/react'; import { useState } from 'react'; function ControlledListBox() { const [selected, setSelected] = useState(new Set(["1"])); return ( Option 1 Option 2 Option 3 ); } ``` ### Custom Indicator ```tsx import { ListBox, ListBoxItemIndicator } from '@heroui/react'; import { Icon } from '@iconify/react'; Option 1 {({isSelected}) => isSelected ? : null } ``` ## 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). # 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 ( News Travel Gaming Shopping ); } ``` ### Anatomy ```tsx import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react'; export default () => ( ) ``` ### Sizes ```tsx "use client"; import {Label, Tag, TagGroup} from "@heroui/react"; export function TagGroupSizes() { return (
News Travel Gaming News Travel Gaming News Travel Gaming
); } ``` ### Disabled ```tsx "use client"; import {Description, Label, Tag, TagGroup} from "@heroui/react"; export function TagGroupDisabled() { return (
News Travel Gaming Some tags are disabled News Travel Gaming Tags disabled via disabledKeys prop
); } ``` ### 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>(new Set(["news"])); const [multipleSelected, setMultipleSelected] = useState>( new Set(["news", "travel"]), ); return (
setSingleSelected(keys)} > News Travel Gaming Shopping Choose one category setMultipleSelected(keys)} > News Travel Gaming Shopping Choose multiple categories
); } ``` ### 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>(new Set(["news", "travel"])); return (
setSelected(keys)} > News Travel Gaming Shopping Selected: {Array.from(selected).length > 0 ? Array.from(selected).join(", ") : "None"}
); } ``` ### On Surface ```tsx "use client"; import {Description, Label, Surface, Tag, TagGroup} from "@heroui/react"; export function TagGroupOnSurface() { return (
News Travel Gaming Tags on surface component
); } ``` ### 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>(new Set()); const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]); return ( setSelected(keys)} > Laundry Fitness center Parking Swimming pool Breakfast {isInvalid ? "Select at least one category" : "Selected: " + Array.from(selected).join(", ")} {!!isInvalid && <>Please select at least one category} ); } ``` ### 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 (
News Travel Gaming Shopping Tags with icons F Fred M Michael J Jane Tags with avatars
); } ``` ### 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([ {id: "news", name: "News"}, {id: "travel", name: "Travel"}, {id: "gaming", name: "Gaming"}, {id: "shopping", name: "Shopping"}, ]); const [frameworks, setFrameworks] = useState([ {id: "react", name: "React"}, {id: "vue", name: "Vue"}, {id: "angular", name: "Angular"}, {id: "svelte", name: "Svelte"}, ]); const onRemoveTags = (keys: Set) => { setTags(tags.filter((tag) => !keys.has(tag.id))); }; const onRemoveFrameworks = (keys: Set) => { setFrameworks(frameworks.filter((framework) => !keys.has(framework.id))); }; return (
No categories found} > {(tag) => ( {tag.name} )} Click the X to remove tags
No frameworks found} > {(tag) => ( {(renderProps) => ( <> {tag.name} {!!renderProps.allowsRemoving && ( )} )} )} Custom remove button with icon
); } ``` ### 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({ 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) => { list.remove(...keys); }; return (
list.setSelectedKeys(keys)} > No team members} > {(user) => ( {user.fallback} {user.name} )} Select team members for your project {list.selectedKeys !== "all" && Array.from(list.selectedKeys).length > 0 && (

Selected:

{Array.from(list.selectedKeys).map((key) => { const user = list.getItem(key); if (!user) return null; return (
{user.fallback} {user.name}
); })}
)}
); } ``` ## 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 ( Custom Styled ); } ``` ### Customizing the component classes To customize the TagGroup component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .tag-group { @apply flex flex-col gap-2; } .tag-group__list { @apply flex flex-wrap gap-2; } .tag { @apply rounded-full px-3 py-1; } .tag__remove-button { @apply ml-1; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The TagGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag-group.css) and [tag.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag.css)): #### Base Classes * `.tag-group` - Base tag group container * `.tag-group__list` - Container for the list of tags * `.tag` - Base tag styles * `.tag__remove-button` - Remove button trigger #### Slot Classes * `.tag-group [slot="description"]` - Description slot styles * `.tag-group [slot="errorMessage"]` - ErrorMessage slot styles #### Size Classes * `.tag--sm` - Small size tag * `.tag--md` - Medium size tag (default) * `.tag--lg` - Large size tag #### Variant Classes * `.tag--default` - Default variant with field-on-background styling * `.tag--surface` - Surface variant with surface background * `.tag--on-surface` - On-surface variant for use on surface components #### Modifier Classes * `.tag__remove-button--on-surface` - Remove button modifier for on-surface variant #### State Classes * `.tag[data-selected="true"]` - Selected tag state * `.tag[data-disabled="true"]` - Disabled tag state * `.tag[data-hovered="true"]` - Hovered tag state * `.tag[data-pressed="true"]` - Pressed tag state * `.tag[data-focus-visible="true"]` - Focused tag state (keyboard focus) ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Hover**: `:hover` or `[data-hovered="true"]` on tag * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on tag * **Pressed**: `:active` or `[data-pressed="true"]` on tag * **Selected**: `[data-selected="true"]` or `[aria-selected="true"]` on tag * **Disabled**: `:disabled` or `[data-disabled="true"]` on tag ## API Reference ### TagGroup Props | Prop | Type | Default | Description | | --------------------- | ---------------------------------- | ----------- | ------------------------------------------------- | | `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | The type of selection that is allowed | | `selectedKeys` | `Selection` | - | The currently selected keys (controlled) | | `defaultSelectedKeys` | `Selection` | - | The initial selected keys (uncontrolled) | | `onSelectionChange` | `(keys: Selection) => void` | - | Handler called when the selection changes | | `disabledKeys` | `Iterable` | - | Keys of disabled tags | | `isDisabled` | `boolean` | - | Whether the tag group is disabled | | `onRemove` | `(keys: Set) => 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 | | `isOnSurface` | `boolean` | - | Whether tags are displayed on a surface component | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | TagGroup content or render function | ### TagGroup.List Props | Prop | Type | Default | Description | | ------------------ | ----------------------------- | ------- | ----------------------------------------- | | `items` | `Iterable` | - | The items to display in the tag list | | `renderEmptyState` | `() => ReactNode` | - | Function to render when the list is empty | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | TagList content or render function | ### Tag Props | Prop | Type | Default | Description | | ------------ | ----------------------------- | ------- | -------------------------------------------------------------------- | | `id` | `Key` | - | The unique identifier for the tag | | `textValue` | `string` | - | A string representation of the tag's content, used for accessibility | | `isDisabled` | `boolean` | - | Whether the tag is disabled | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Tag content or render function | **Note**: `size`, `variant`, and `isOnSurface` are inherited from the parent `TagGroup` component and cannot be set directly on individual `Tag` components. ### Tag.RemoveButton Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ----------------------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom remove button content (defaults to close icon) | ### RenderProps When using render functions with TagGroup.List, these values are provided: | Prop | Type | Description | | ---------------- | --------- | ---------------------------------- | | `isSelected` | `boolean` | Whether the tag is selected | | `isDisabled` | `boolean` | Whether the tag is disabled | | `isHovered` | `boolean` | Whether the tag is hovered | | `isPressed` | `boolean` | Whether the tag is pressed | | `isFocused` | `boolean` | Whether the tag is focused | | `isFocusVisible` | `boolean` | Whether the tag has keyboard focus | # 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 ( ); } ``` ### Anatomy Import the Slider component and access all parts using dot notation. ```tsx import { Slider, Label } from '@heroui/react'; export default () => ( ) ``` ### Range Slider Anatomy ```tsx import { Slider, Label } from '@heroui/react'; export default () => ( ) ``` ### Vertical ```tsx import {Label, Slider} from "@heroui/react"; export function Vertical() { return (
); } ``` ### Range ```tsx "use client"; import {Label, Slider} from "@heroui/react"; export function Range() { return ( {({state}) => ( <> {state.values.map((_, i) => ( ))} )} ); } ``` ### Disabled ```tsx import {Label, Slider} from "@heroui/react"; export function Disabled() { return ( ); } ``` ## 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 ( ); } ``` ### Customizing the component classes To customize the Slider component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .slider { @apply flex flex-col gap-2; } .slider__output { @apply text-muted-fg text-sm; } .slider-track { @apply relative h-2 w-full rounded-full bg-surface-secondary; } .slider-fill { @apply absolute h-full rounded-full bg-accent; } .slider-thumb { @apply size-4 rounded-full bg-accent border-2 border-background; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Slider component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/slider.css)): #### Base Classes * `.slider` - Base slider container * `.slider__output` - Output element displaying current value(s) * `.slider-track` - Track element containing fill and thumbs * `.slider-fill` - Fill element showing selected range * `.slider-thumb` - Individual thumb element #### State Classes * `.slider[data-disabled="true"]` - Disabled slider state * `.slider[data-orientation="vertical"]` - Vertical orientation * `.slider-thumb[data-dragging="true"]` - Thumb being dragged * `.slider-thumb[data-focus-visible="true"]` - Thumb keyboard focused * `.slider-thumb[data-disabled="true"]` - Disabled thumb state * `.slider-track[data-fill-start="true"]` - Fill starts at beginning * `.slider-track[data-fill-end="true"]` - Fill ends at end ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Hover**: `:hover` or `[data-hovered="true"]` on thumb * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on thumb * **Dragging**: `[data-dragging="true"]` on thumb * **Disabled**: `:disabled` or `[data-disabled="true"]` on slider or thumb ## API Reference ### Slider Props | Prop | Type | Default | Description | | ----------------- | ------------------------------------- | -------------- | ------------------------------------- | | `value` | `number \| number[]` | - | The current value (controlled) | | `defaultValue` | `number \| number[]` | - | The default value (uncontrolled) | | `onChange` | `(value: number \| number[]) => void` | - | Handler called when the value changes | | `onChangeEnd` | `(value: number \| number[]) => void` | - | Handler called when dragging ends | | `minValue` | `number` | `0` | The slider's minimum value | | `maxValue` | `number` | `100` | The slider's maximum value | | `step` | `number` | `1` | The slider's step value | | `formatOptions` | `Intl.NumberFormatOptions` | - | The display format of the value label | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the slider | | `isDisabled` | `boolean` | - | Whether the slider is disabled | | `aria-label` | `string` | - | Accessibility label for the slider | | `aria-labelledby` | `string` | - | ID of element that labels the slider | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Slider content or render function | ### Slider.Output Props | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | --------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Output content or render function | ### Slider.Track Props | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | -------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Track content or render function | ### Slider.Fill Props | Prop | Type | Default | Description | | ----------- | --------------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `style` | `CSSProperties` | - | Inline styles | ### Slider.Thumb Props | Prop | Type | Default | Description | | ------------ | ----------------------------- | ------- | ---------------------------------------------------------------- | | `index` | `number` | `0` | Index of the thumb within the slider | | `isDisabled` | `boolean` | - | Whether this thumb is disabled | | `name` | `string` | - | The name of the input element, used when submitting an HTML form | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Thumb content or render function | ### RenderProps When using render functions with Slider.Output or Slider.Track, these values are provided: | Prop | Type | Description | | -------------------- | ---------------------------- | -------------------------------------------------------- | | `state` | `SliderState` | The state of the slider | | `values` | `number[]` | Values managed by the slider by thumb index | | `getThumbValueLabel` | `(index: number) => string` | Returns the string label for the specified thumb's value | | `orientation` | `"horizontal" \| "vertical"` | The orientation of the slider | | `isDisabled` | `boolean` | Whether the slider is disabled | ## Examples ### Basic Usage ```tsx import { Slider, Label } from '@heroui/react'; ``` ### Range Slider ```tsx import { Slider, Label } from '@heroui/react'; {({state}) => ( <> {state.values.map((_, i) => ( ))} )} ``` ### Controlled Value ```tsx import { Slider, Label } from '@heroui/react'; import { useState } from 'react'; function ControlledSlider() { const [value, setValue] = useState(25); return ( <>

Current value: {value}

); } ``` ### Custom Value Formatting ```tsx import { Slider, Label } from '@heroui/react'; ``` ### Vertical Orientation ```tsx import { Slider, Label } from '@heroui/react'; ``` ### Custom Output Display ```tsx import { Slider, Label } from '@heroui/react'; {({state}) => state.values.map((_, i) => state.getThumbValueLabel(i)).join(' – ') } {({state}) => ( <> {state.values.map((_, i) => ( ))} )} ``` ## Accessibility The Slider component implements the ARIA slider pattern and provides: * Full keyboard navigation support (Arrow keys, Home, End, Page Up/Down) * Screen reader announcements for value changes * Proper focus management * Support for disabled states * HTML form integration via hidden input elements * Internationalization support with locale-aware value formatting * Right-to-left (RTL) language support For more information, see the [React Aria Slider documentation](https://react-spectrum.adobe.com/react-aria/Slider.html). # 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 ( ); } ``` ### Anatomy Import the Switch component and access all parts using dot notation. ```tsx import { Switch, Label } from '@heroui/react'; export default () => ( {/* Optional */} ); ``` For grouping multiple switches, use the `SwitchGroup` component: ```tsx import { Switch, SwitchGroup, Label } from '@heroui/react'; export default () => ( ); ``` ### Disabled ```tsx import {Label, Switch} from "@heroui/react"; export function Disabled() { return ( ); } ``` ### Default Selected ```tsx import {Label, Switch} from "@heroui/react"; export function DefaultSelected() { return ( ); } ``` ### Controlled ```tsx "use client"; import {Label, Switch} from "@heroui/react"; import React from "react"; export function Controlled() { const [isSelected, setIsSelected] = React.useState(false); return (

Switch is {isSelected ? "on" : "off"}

); } ``` ### Without Label ```tsx import {Switch} from "@heroui/react"; export function WithoutLabel() { return ( ); } ``` ### Sizes ```tsx import {Label, Switch} from "@heroui/react"; export function Sizes() { return (
); } ``` ### Label Position ```tsx import {Label, Switch} from "@heroui/react"; export function LabelPosition() { return (
); } ``` ### 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 (
{Object.entries(icons).map(([key, value]) => ( {({isSelected}) => ( <> {isSelected ? ( ) : ( )} )} ))}
); } ``` ### With Description ```tsx import {Description, Label, Switch} from "@heroui/react"; export function WithDescription() { return (
Allow others to see your profile information
); } ``` ### Group ```tsx import {Label, Switch, SwitchGroup} from "@heroui/react"; export function Group() { return ( ); } ``` ### Group Horizontal ```tsx import {Label, Switch, SwitchGroup} from "@heroui/react"; export function GroupHorizontal() { return ( ); } ``` ### Render Props ```tsx "use client"; import {Label, Switch} from "@heroui/react"; export function RenderProps() { return ( {({isSelected}) => ( <> )} ); } ``` ### 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 (
); } ``` ### Custom Styles ```tsx "use client"; import {Check, Power} from "@gravity-ui/icons"; import {Switch} from "@heroui/react"; export function CustomStyles() { return ( {({isSelected}) => ( <> {isSelected ? ( ) : ( )} )} ); } ``` ## 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 ( {({isSelected}) => ( <> )} ); } ``` Or customize the SwitchGroup layout: ```tsx import { Switch, SwitchGroup, Label } from '@heroui/react'; function CustomSwitchGroup() { return ( ); } ``` ### Customizing the component classes To customize the Switch component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .switch { @apply inline-flex gap-3 items-center; } .switch__control { @apply h-5 w-8 bg-gray-400 data-[selected=true]:bg-blue-500; } .switch__thumb { @apply bg-white shadow-sm; } .switch__icon { @apply h-3 w-3 text-current; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes #### Switch Classes The Switch component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch.css)): * `.switch` - Base switch container * `.switch__control` - Switch control track * `.switch__thumb` - Switch thumb that moves * `.switch__icon` - Optional icon inside the thumb * `.switch--sm` - Small size variant * `.switch--md` - Medium size variant (default) * `.switch--lg` - Large size variant #### SwitchGroup Classes The SwitchGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch-group.css)): * `.switch-group` - Switch group container * `.switch-group__items` - Container for switch items * `.switch-group--horizontal` - Horizontal layout * `.switch-group--vertical` - Vertical layout (default) ### Interactive States The switch supports both CSS pseudo-classes and data attributes for flexibility: * **Selected**: `[data-selected="true"]` (thumb position and background color change) * **Hover**: `:hover` or `[data-hovered="true"]` * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring) * **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events) * **Pressed**: `:active` or `[data-pressed="true"]` ## API Reference ### Switch Props Inherits from [React Aria Switch](https://react-spectrum.adobe.com/react-aria/Switch.html). | Prop | Type | Default | Description | | ----------------- | ------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | The size of the switch | | `isSelected` | `boolean` | `false` | Whether the switch is on | | `defaultSelected` | `boolean` | `false` | Whether the switch is on by default (uncontrolled) | | `isDisabled` | `boolean` | `false` | Whether the switch is disabled | | `name` | `string` | - | The name of the input element, used when submitting an HTML form | | `value` | `string` | - | The value of the input element, used when submitting an HTML form | | `onChange` | `(isSelected: boolean) => void` | - | Handler called when the switch value changes | | `onPress` | `(e: PressEvent) => void` | - | Handler called when the switch is pressed | | `children` | `React.ReactNode \| (values: SwitchRenderProps) => React.ReactNode` | - | Switch content or render prop | ### SwitchRenderProps When using the render prop pattern, these values are provided: | Prop | Type | Description | | ---------------- | --------- | --------------------------------------- | | `isSelected` | `boolean` | Whether the switch is currently on | | `isHovered` | `boolean` | Whether the switch is hovered | | `isPressed` | `boolean` | Whether the switch is currently pressed | | `isFocused` | `boolean` | Whether the switch is focused | | `isFocusVisible` | `boolean` | Whether the switch is keyboard focused | | `isDisabled` | `boolean` | Whether the switch is disabled | | `isReadOnly` | `boolean` | Whether the switch is read only | | `state` | `-` | State of the switch. | ### SwitchGroup Props | Prop | Type | Default | Description | | ------------- | ---------------------------- | ------------ | ----------------------------------- | | `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | The orientation of the switch group | | `children` | `React.ReactNode` | - | The switch items to render | | `className` | `string` | - | Additional CSS class names | # Chip **Category**: react **URL**: https://v3.heroui.com/docs/react/components/chip **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(data-display)/chip.mdx > Small informational badges for displaying labels, statuses, and categories ## Import ```tsx import { Chip } from '@heroui/react'; ``` ### Usage ```tsx import {Chip} from "@heroui/react"; export function ChipBasic() { return (
Default Accent Success Warning Danger
); } ``` ### 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 (
{sizes.map((size, index) => (

{size}

{/* Color labels header */}
{colors.map((color) => (
{color}
))}
{variants.map((variant) => (
{variant}
{colors.map((color) => (
Label
))}
))}
{index < sizes.length - 1 && } ))}
); } ``` ### With Icons ```tsx import {ChevronDown, CircleCheckFill, CircleFill, Clock, Xmark} from "@gravity-ui/icons"; import {Chip} from "@heroui/react"; export function ChipWithIcon() { return (
Information Completed Pending Failed Label
); } ``` ### Statuses ```tsx import {Ban, Check, CircleFill, CircleInfo, TriangleExclamation} from "@gravity-ui/icons"; import {Chip} from "@heroui/react"; export function ChipStatuses() { return (
Default Active Pending Inactive
New Feature Available Beta Deprecated
); } ``` ## Related Components * **Avatar**: Display user profile images * **CloseButton**: Button for dismissing overlays * **Separator**: Visual divider between content ## Styling ### Passing Tailwind CSS classes ```tsx import {Chip} from '@heroui/react'; function CustomChip() { return ( Custom Styled ); } ``` ### Customizing the component classes To customize the Chip component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .chip { @apply rounded-full text-xs; } .chip--accent { @apply border-accent/20; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Chip component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/chip.css)): #### Base Classes * `.chip` - Base chip styles #### Color Classes * `.chip--accent` - Accent color variant * `.chip--danger` - Danger color variant * `.chip--default` - Default color variant * `.chip--success` - Success color variant * `.chip--warning` - Warning color variant #### Variant Classes * `.chip--primary` - Primary variant with filled background * `.chip--secondary` - Secondary variant with border * `.chip--tertiary` - Tertiary variant with transparent background * `.chip--soft` - Soft variant with lighter background #### Size Classes * `.chip--sm` - Small size * `.chip--md` - Medium size (default) * `.chip--lg` - Large size #### Compound Variant Classes Chips support combining variant and color classes (e.g., `.chip--secondary.chip--accent`). The following combinations have default styles defined: **Primary Variants:** * `.chip--primary.chip--accent` - Primary accent combination with filled background * `.chip--primary.chip--success` - Primary success combination with filled background * `.chip--primary.chip--warning` - Primary warning combination with filled background * `.chip--primary.chip--danger` - Primary danger combination with filled background **Soft Variants:** * `.chip--accent.chip--soft` - Soft accent combination with lighter background * `.chip--success.chip--soft` - Soft success combination with lighter background * `.chip--warning.chip--soft` - Soft warning combination with lighter background * `.chip--danger.chip--soft` - Soft danger combination with lighter background **Note:** You can apply custom styles to any variant-color combination (e.g., `.chip--secondary.chip--accent`, `.chip--tertiary.chip--success`) using the `@layer components` directive in your CSS. ## API Reference ### Chip Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------- | ------------- | ---------------------------------- | | `children` | `React.ReactNode` | - | Content to display inside the chip | | `className` | `string` | - | Additional CSS classes | | `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Color variant of the chip | | `variant` | `"primary" \| "secondary" \| "tertiary" \| "soft"` | `"secondary"` | Visual style variant | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the chip | # Alert **Category**: react **URL**: https://v3.heroui.com/docs/react/components/alert **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(feedback)/alert.mdx > Display important messages and notifications to users with status indicators ## Import ```tsx import { Alert } from '@heroui/react'; ``` ### Usage ```tsx import {Alert, Button, CloseButton, Spinner} from "@heroui/react"; import React from "react"; export function Basic() { return (
{/* Default - General information */} New features available Check out our latest updates including dark mode support and improved accessibility features. {/* Accent - Important information with action */} Update available A new version of the application is available. Please refresh to get the latest features and bug fixes. {/* Danger - Error with detailed steps */} Unable to connect to server We're experiencing connection issues. Please try the following:
  • Check your internet connection
  • Refresh the page
  • Clear your browser cache
 {/* Without description */} Profile updated successfully {/* Custom indicator - Loading state */} Processing your request Please wait while we sync your data. This may take a few moments. {/* Without close button */} Scheduled maintenance Our services will be unavailable on Sunday, March 15th from 2:00 AM to 6:00 AM UTC for scheduled maintenance.
); } ``` ### Anatomy Import the Alert component and access all parts using dot notation. ```tsx import { Alert } from '@heroui/react'; export default () => ( ) ``` ## Related Components * **CloseButton**: Button for dismissing overlays * **Button**: Allows a user to perform an action * **Spinner**: Loading indicator ## Styling ### Passing Tailwind CSS classes ```tsx import { Alert } from "@heroui/react"; function CustomAlert() { return ( Custom Alert This alert has custom styling applied ); } ``` ### Customizing the component classes To customize the Alert component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .alert { @apply rounded-2xl shadow-lg; } .alert__title { @apply font-bold text-lg; } .alert--danger { @apply border-l-4 border-red-600; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Alert component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert.css)): #### Base Classes * `.alert` - Base alert container * `.alert__indicator` - Icon/indicator container * `.alert__content` - Content wrapper for title and description * `.alert__title` - Alert title text * `.alert__description` - Alert description text #### Status Variant Classes * `.alert--default` - Default gray status * `.alert--accent` - Accent blue status * `.alert--success` - Success green status * `.alert--warning` - Warning yellow/orange status * `.alert--danger` - Danger red status ### Interactive States The Alert component is primarily informational and doesn't have interactive states on the base component. However, it can contain interactive elements like buttons or close buttons. ## API Reference ### Alert Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------- | ----------- | ------------------------------ | | `status` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | The visual status of the alert | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | The alert content | ### Alert.Indicator Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ----------------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom indicator icon (defaults to status icon) | ### Alert.Content Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ----------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Content (typically Title and Description) | ### Alert.Title Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | The alert title text | ### Alert.Description Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | -------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | The alert description text | # Skeleton **Category**: react **URL**: https://v3.heroui.com/docs/react/components/skeleton **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(feedback)/skeleton.mdx > Skeleton is a placeholder to show a loading state and the expected shape of a component. ## Import ```tsx import { Skeleton } from '@heroui/react'; ``` ### Usage ```tsx import {Skeleton} from "@heroui/react"; export function Basic() { return (
); } ``` ### Text Content ```tsx import {Skeleton} from "@heroui/react"; export function TextContent() { return (
); } ``` ### User Profile ```tsx import {Skeleton} from "@heroui/react"; export function UserProfile() { return (
); } ``` ### List Items ```tsx import {Skeleton} from "@heroui/react"; export function List() { return (
{Array.from({length: 3}).map((_, index) => (
))}
); } ``` ### Animation Types ```tsx import {Skeleton} from "@heroui/react"; export function AnimationTypes() { return (

Shimmer

Pulse

None

); } ``` ### Grid ```tsx import {Skeleton} from "@heroui/react"; export function Grid() { return (
); } ``` ### Single Shimmer A synchronized shimmer effect that passes over all skeleton elements at once. Apply the `skeleton--shimmer` class to a parent container and set `animationType="none"` on child skeletons. ```tsx import {Skeleton} from "@heroui/react"; export function SingleShimmer() { return (
); } ``` ## Related Components * **Card**: Content container with header, body, and footer * **Avatar**: Display user profile images ## Styling ### Global Animation Configuration You can set a default animation type for all Skeleton components in your application by defining the `--skeleton-animation` CSS variable: ```css /* In your global CSS file */ :root { /* Possible values: shimmer, pulse, none */ --skeleton-animation: pulse; } /* You can also set different values for light/dark themes */ .light, [data-theme="light"] { --skeleton-animation: shimmer; } .dark, [data-theme="dark"] { --skeleton-animation: pulse; } ``` This global setting will be overridden by the `animationType` prop when specified on individual components. ### Passing Tailwind CSS classes ```tsx import { Skeleton } from '@heroui/react'; function CustomSkeleton() { return ( ); } ``` ### Customizing the component classes To customize the Skeleton component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { /* Base skeleton styles */ .skeleton { @apply bg-surface-secondary/50; /* Change base background */ } /* Shimmer animation gradient */ .skeleton--shimmer:before { @apply viasurface; /* Change shimmer gradient color */ } /* Pulse animation */ .skeleton--pulse { @apply animate-pulse opacity-75; /* Customize pulse animation */ } /* No animation variant */ .skeleton--none { @apply opacity-50; /* Style for static skeleton */ } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Skeleton component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/skeleton.css)): #### Base Class `.skeleton` - Base skeleton styles with background and rounded corners #### Animation Variant Classes * `.skeleton--shimmer` - Adds shimmer animation with gradient effect (default) * `.skeleton--pulse` - Adds pulse animation using Tailwind's animate-pulse * `.skeleton--none` - No animation, static skeleton ### Animation The Skeleton component supports three animation types, each with different visual effects: #### Shimmer Animation The shimmer effect creates a gradient that moves across the skeleton element: ```css .skeleton--shimmer:before { @apply animate-skeleton via-surface-3 absolute inset-0 -translate-x-full bg-gradient-to-r from-transparent to-transparent content-['']; } ``` The shimmer animation is defined in the theme using: ```css @theme inline { --animate-skeleton: skeleton 2s linear infinite; @keyframes skeleton { 100% { transform: translateX(200%); } } } ``` #### Pulse Animation The pulse animation uses Tailwind's built-in `animate-pulse` utility: ```css .skeleton--pulse { @apply animate-pulse; } ``` #### No Animation For static skeletons without any animation: ```css .skeleton--none { /* No animation styles applied */ } ``` ## API Reference ### Skeleton Props | Prop | Type | Default | Description | | --------------- | -------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------- | | `animationType` | `"shimmer" \| "pulse" \| "none"` | `"shimmer"` or CSS variable | The animation type for the skeleton. Can be globally configured via `--skeleton-animation` CSS variable | | `className` | `string` | - | Additional CSS classes | # Spinner **Category**: react **URL**: https://v3.heroui.com/docs/react/components/spinner **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(feedback)/spinner.mdx > A loading indicator component to show pending states ## Import ```tsx import { Spinner } from '@heroui/react'; ``` ### Usage ```tsx import {Spinner} from "@heroui/react"; export function SpinnerBasic() { return (
); } ``` ### Colors ```tsx import {Spinner} from "@heroui/react"; export function SpinnerColors() { return (
Current
Accent
Success
Warning
Danger
); } ``` ### Sizes ```tsx import {Spinner} from "@heroui/react"; export function SpinnerSizes() { return (
Small
Medium
Large
Extra Large
); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import {Spinner} from '@heroui/react'; function CustomSpinner() { return ( ); } ``` ### Customizing the component classes To customize the Spinner component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .spinner { @apply animate-spin; } .spinner--accent { color: var(--accent); } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Spinner component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/spinner.css)): #### Base & Size Classes * `.spinner` - Base spinner styles with default size * `.spinner--sm` - Small size variant * `.spinner--md` - Medium size variant (default) * `.spinner--lg` - Large size variant * `.spinner--xl` - Extra large size variant #### Color Classes * `.spinner--current` - Inherits current text color * `.spinner--accent` - Accent color variant * `.spinner--danger` - Danger color variant * `.spinner--success` - Success color variant * `.spinner--warning` - Warning color variant ## API Reference ### Spinner Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------- | ----------- | ---------------------------- | | `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Size of the spinner | | `color` | `"current" \| "accent" \| "success" \| "warning" \| "danger"` | `"current"` | Color variant of the spinner | | `className` | `string` | - | Additional CSS classes | # CheckboxGroup **Category**: react **URL**: https://v3.heroui.com/docs/react/components/checkbox-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/checkbox-group.mdx > A checkbox group component for managing multiple checkbox selections ## Import ```tsx import { CheckboxGroup, Checkbox, Label, Description } from '@heroui/react'; ``` ### Usage ```tsx import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function Basic() { return ( Choose all that apply Love building software Enjoy creating beautiful interfaces Passionate about content creation ); } ``` ### Anatomy Import the CheckboxGroup component and access all parts using dot notation. ```tsx import {CheckboxGroup, Checkbox, Label, Description, FieldError} from '@heroui/react'; export default () => ( ); ``` ### On Surface When used inside a [Surface](/docs/components/surface) component, CheckboxGroup automatically applies on-surface styling. ```tsx import {Checkbox, CheckboxGroup, Description, Label, Surface} from "@heroui/react"; export function OnSurface() { return ( Choose all that apply Love building software Enjoy creating beautiful interfaces Passionate about content creation ); } ``` ### With Custom Indicator ```tsx "use client"; import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function WithCustomIndicator() { return ( Select the features you want {({isSelected}) => isSelected ? ( ) : null } Receive updates via email {({isSelected}) => isSelected ? ( ) : null } Get weekly newsletters ); } ``` ### Indeterminate ```tsx "use client"; import {Checkbox, CheckboxGroup, Label} from "@heroui/react"; import {useState} from "react"; export function Indeterminate() { const [selected, setSelected] = useState(["coding"]); const allOptions = ["coding", "design", "writing"]; return (
0 && selected.length < allOptions.length} isSelected={selected.length === allOptions.length} name="select-all" onChange={(isSelected: boolean) => { setSelected(isSelected ? allOptions : []); }} >
); } ``` ### Controlled ```tsx "use client"; import {Checkbox, CheckboxGroup, Label} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [selected, setSelected] = useState(["coding", "design"]); return ( ); } ``` ### Validation ```tsx "use client"; import {Button, Checkbox, CheckboxGroup, FieldError, Form, Label} from "@heroui/react"; export function Validation() { return (
{ e.preventDefault(); const formData = new FormData(e.currentTarget); const values = formData.getAll("preferences"); alert(`Selected preferences: ${values.join(", ")}`); }} > Please select at least one notification method.
); } ``` ### Disabled ```tsx import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function Disabled() { return ( Feature selection is temporarily disabled This feature is coming soon This feature is coming soon ); } ``` ### Features and Add-ons Example ```tsx import {Bell, Comment, Envelope} from "@gravity-ui/icons"; import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; import clsx from "clsx"; export function FeaturesAndAddOns() { const addOns = [ { description: "Receive updates via email", icon: Envelope, title: "Email Notifications", value: "email", }, { description: "Get instant SMS notifications", icon: Comment, title: "SMS Alerts", value: "sms", }, { description: "Browser and mobile push alerts", icon: Bell, title: "Push Notifications", value: "push", }, ]; return (
Choose how you want to receive updates
{addOns.map((addon) => (
{addon.description}
))}
); } ``` ## Related Components * **Checkbox**: Binary choice input control * **Label**: Accessible label for form controls * **Fieldset**: Group related form controls with legends ## Styling ### Passing Tailwind CSS classes You can customize the CheckboxGroup component: ```tsx import { CheckboxGroup, Checkbox, Label } from '@heroui/react'; function CustomCheckboxGroup() { return ( ); } ``` ### Customizing the component classes To customize the CheckboxGroup component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .checkbox-group { @apply flex flex-col gap-2; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The CheckboxGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox-group.css)): * `.checkbox-group` - Base checkbox group container ## API Reference ### CheckboxGroup Props Inherits from [React Aria CheckboxGroup](https://react-spectrum.adobe.com/react-aria/CheckboxGroup.html). | Prop | Type | Default | Description | | -------------- | -------------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- | | `value` | `string[]` | - | The current selected values (controlled) | | `defaultValue` | `string[]` | - | The default selected values (uncontrolled) | | `onChange` | `(value: string[]) => void` | - | Handler called when the selected values change | | `isDisabled` | `boolean` | `false` | Whether the checkbox group is disabled | | `isRequired` | `boolean` | `false` | Whether the checkbox group is required | | `isReadOnly` | `boolean` | `false` | Whether the checkbox group is read only | | `isInvalid` | `boolean` | `false` | Whether the checkbox group is in an invalid state | | `name` | `string` | - | The name of the checkbox group, used when submitting an HTML form | | `children` | `React.ReactNode \| (values: CheckboxGroupRenderProps) => React.ReactNode` | - | Checkbox group content or render prop | ### CheckboxGroupRenderProps When using the render prop pattern, these values are provided: | Prop | Type | Description | | ------------ | ---------- | ------------------------------------------------- | | `value` | `string[]` | The currently selected values | | `isDisabled` | `boolean` | Whether the checkbox group is disabled | | `isReadOnly` | `boolean` | Whether the checkbox group is read only | | `isInvalid` | `boolean` | Whether the checkbox group is in an invalid state | | `isRequired` | `boolean` | Whether the checkbox group is required | # Checkbox **Category**: react **URL**: https://v3.heroui.com/docs/react/components/checkbox **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/checkbox.mdx > Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected. ## Import ```tsx import { Checkbox, Label } from '@heroui/react'; ``` ### Usage ```tsx import {Checkbox, Label} from "@heroui/react"; export function Basic() { return (
); } ``` ### Anatomy Import the Checkbox component and access all parts using dot notation. ```tsx import { Checkbox, Label, Description } from '@heroui/react'; export default () => ( ); ``` ### Disabled ```tsx import {Checkbox, Description, Label} from "@heroui/react"; export function Disabled() { return (
This feature is coming soon
); } ``` ### Default Selected ```tsx import {Checkbox, Label} from "@heroui/react"; export function DefaultSelected() { return (
); } ``` ### Controlled ```tsx "use client"; import {Checkbox, Label} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [isSelected, setIsSelected] = useState(true); return (

Status: {isSelected ? "Enabled" : "Disabled"}

); } ``` ### Indeterminate ```tsx "use client"; import {Checkbox, Description, Label} from "@heroui/react"; import {useState} from "react"; export function Indeterminate() { const [isIndeterminate, setIsIndeterminate] = useState(true); const [isSelected, setIsSelected] = useState(false); return (
{ setIsSelected(selected); setIsIndeterminate(false); }} >
Shows indeterminate state (dash icon)
); } ``` ### With Label ```tsx import {Checkbox, Label} from "@heroui/react"; export function WithLabel() { return ( ); } ``` ### With Description ```tsx import {Checkbox, Description, Label} from "@heroui/react"; export function WithDescription() { return (
Get notified when someone mentions you in a comment
); } ``` ### Render Props ```tsx "use client"; import {Checkbox, Description, Label} from "@heroui/react"; export function RenderProps() { return ( {({isSelected}) => ( <> {isSelected ? "Thank you for accepting" : "Please read and accept the terms"} )} ); } ``` ### Form Integration ```tsx "use client"; import {Button, Checkbox, Label} from "@heroui/react"; import React from "react"; export function Form() { const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); const formData = new FormData(e.target as HTMLFormElement); alert( `Form submitted with:\n${Array.from(formData.entries()) .map(([key, value]) => `${key}: ${value}`) .join("\n")}`, ); }; return (
); } ``` ### Invalid ```tsx import {Checkbox, Description, Label} from "@heroui/react"; export function Invalid() { return ( You must accept the terms to continue ); } ``` ### Custom Indicator ```tsx "use client"; import {Checkbox, Label} from "@heroui/react"; export function CustomIndicator() { return (
{({isSelected}) => isSelected ? ( ) : null } {({isSelected}) => isSelected ? ( ) : null } {({isIndeterminate}) => isIndeterminate ? ( ) : null }
); } ``` ### Full Rounded ```tsx import {Checkbox, Label} from "@heroui/react"; export function FullRounded() { return (
); } ``` ## Related Components * **Label**: Accessible label for form controls * **CheckboxGroup**: Group of checkboxes with shared state * **Description**: Helper text for form fields ## Styling ### Passing Tailwind CSS classes You can customize individual Checkbox components: ```tsx import { Checkbox, Label } from '@heroui/react'; function CustomCheckbox() { return ( ); } ``` ### Customizing the component classes To customize the Checkbox component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .checkbox { @apply inline-flex gap-3 items-center; } .checkbox__control { @apply size-5 border-2 border-gray-400 rounded data-[selected=true]:bg-blue-500 data-[selected=true]:border-blue-500; /* Animated background indicator */ &::before { @apply bg-accent pointer-events-none absolute inset-0 z-0 origin-center scale-50 rounded-md opacity-0 content-['']; transition: scale 200ms linear, opacity 200ms linear, background-color 200ms ease-out; } /* Show indicator when selected */ &[data-selected="true"]::before { @apply scale-100 opacity-100; } } .checkbox__indicator { @apply text-white; } .checkbox__content { @apply flex flex-col gap-1; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Checkbox component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox.css)): * `.checkbox` - Base checkbox container * `.checkbox__control` - Checkbox control box * `.checkbox__indicator` - Checkbox checkmark indicator * `.checkbox__content` - Optional content container ### Interactive States The checkbox supports both CSS pseudo-classes and data attributes for flexibility: * **Selected**: `[data-selected="true"]` or `[aria-checked="true"]` (shows checkmark and background color change) * **Indeterminate**: `[data-indeterminate="true"]` (shows indeterminate state with dash) * **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` (shows error state with danger colors) * **Hover**: `:hover` or `[data-hovered="true"]` * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring) * **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events) * **Pressed**: `:active` or `[data-pressed="true"]` ## API Reference ### Checkbox Props Inherits from [React Aria Checkbox](https://react-spectrum.adobe.com/react-aria/Checkbox.html). | Prop | Type | Default | Description | | ----------------- | --------------------------------------------------------------------- | ------- | ----------------------------------------------------------------- | | `isSelected` | `boolean` | `false` | Whether the checkbox is checked | | `defaultSelected` | `boolean` | `false` | Whether the checkbox is checked by default (uncontrolled) | | `isIndeterminate` | `boolean` | `false` | Whether the checkbox is in an indeterminate state | | `isDisabled` | `boolean` | `false` | Whether the checkbox is disabled | | `isInvalid` | `boolean` | `false` | Whether the checkbox is invalid | | `isReadOnly` | `boolean` | `false` | Whether the checkbox is read only | | `isOnSurface` | `boolean` | `false` | Whether the checkbox is displayed on a surface (affects styling) | | `name` | `string` | - | The name of the input element, used when submitting an HTML form | | `value` | `string` | - | The value of the input element, used when submitting an HTML form | | `onChange` | `(isSelected: boolean) => void` | - | Handler called when the checkbox value changes | | `children` | `React.ReactNode \| (values: CheckboxRenderProps) => React.ReactNode` | - | Checkbox content or render prop | ### CheckboxRenderProps When using the render prop pattern, these values are provided: | Prop | Type | Description | | ----------------- | --------- | ------------------------------------------------- | | `isSelected` | `boolean` | Whether the checkbox is currently checked | | `isIndeterminate` | `boolean` | Whether the checkbox is in an indeterminate state | | `isHovered` | `boolean` | Whether the checkbox is hovered | | `isPressed` | `boolean` | Whether the checkbox is currently pressed | | `isFocused` | `boolean` | Whether the checkbox is focused | | `isFocusVisible` | `boolean` | Whether the checkbox is keyboard focused | | `isDisabled` | `boolean` | Whether the checkbox is disabled | | `isReadOnly` | `boolean` | Whether the checkbox is read only | # DateField **Category**: react **URL**: https://v3.heroui.com/docs/react/components/date-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/date-field.mdx > Date input field with labels, descriptions, and validation built on React Aria DateField ## Import ```tsx import { DateField } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {DateField, DateInputGroup, Label} from "@heroui/react"; export function Basic() { return ( {(segment) => } ); } ``` ### Anatomy ```tsx import {DateField, Label, DateInputGroup, Description, FieldError} from '@heroui/react'; export default () => ( ) ``` > **DateField** combines label, date input, description, and error into a single accessible component. ### With Description ```tsx "use client"; import {DateField, DateInputGroup, Description, Label} from "@heroui/react"; export function WithDescription() { return (
{(segment) => } Enter your date of birth {(segment) => } Enter a date for your appointment
); } ``` ### Required Field ```tsx "use client"; import {DateField, DateInputGroup, Description, Label} from "@heroui/react"; export function Required() { return (
{(segment) => } {(segment) => } Required field
); } ``` ### Validation Use `isInvalid` together with `FieldError` to surface validation messages. ```tsx "use client"; import {DateField, DateInputGroup, FieldError, Label} from "@heroui/react"; export function Invalid() { return (
{(segment) => } Please enter a valid date {(segment) => } Date must be in the future
); } ``` ### With Validation DateField supports validation with `minValue`, `maxValue`, and custom validation logic. ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {DateField, DateInputGroup, Description, FieldError, Label} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; export function WithValidation() { const [value, setValue] = useState(null); const todayDate = today(getLocalTimeZone()); const isInvalid = value !== null && value.compare(todayDate) < 0; return (
{(segment) => } {isInvalid ? ( Date must be today or in the future ) : ( Enter a date from today onwards )}
); } ``` ### Controlled Control the value to synchronize with other components or state management. ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Button, DateField, DateInputGroup, Description, Label} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; export function Controlled() { const [value, setValue] = useState(null); return (
{(segment) => } Current value: {value ? value.toString() : "(empty)"}
); } ``` ### Disabled State ```tsx "use client"; import {DateField, DateInputGroup, Description, Label} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function Disabled() { return (
{(segment) => } This date field is disabled {(segment) => } This date field is disabled
); } ``` ### With Icons Add prefix or suffix icons to enhance the date field. ```tsx "use client"; import {Calendar} from "@gravity-ui/icons"; import {DateField, DateInputGroup, Label} from "@heroui/react"; export function WithPrefixIcon() { return ( {(segment) => } ); } ``` ```tsx "use client"; import {Calendar} from "@gravity-ui/icons"; import {DateField, DateInputGroup, Label} from "@heroui/react"; export function WithSuffixIcon() { return ( {(segment) => } ); } ``` ```tsx "use client"; import {Calendar, ChevronDown} from "@gravity-ui/icons"; import {DateField, DateInputGroup, Description, Label} from "@heroui/react"; export function WithPrefixAndSuffix() { return ( {(segment) => } Enter a date ); } ``` ### Full Width ```tsx "use client"; import {Calendar, ChevronDown} from "@gravity-ui/icons"; import {DateField, DateInputGroup, Label} from "@heroui/react"; export function FullWidth() { return (
{(segment) => } {(segment) => }
); } ``` ### On Surface When used inside a [Surface](/docs/components/surface) component, DateField and its child DateInputGroup automatically apply on-surface styling. ```tsx "use client"; import {Calendar} from "@gravity-ui/icons"; import {DateField, DateInputGroup, Description, Label, Surface} from "@heroui/react"; export function OnSurface() { return ( {(segment) => } Enter a date {(segment) => } Enter a date for your appointment ); } ``` ### Form Example Complete form example with validation and submission handling. ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Calendar} from "@gravity-ui/icons"; import { Button, DateField, DateInputGroup, Description, FieldError, Form, Label, } from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; export function FormExample() { const [value, setValue] = useState(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 (
{(segment) => } {isInvalid ? ( Date must be today or in the future ) : ( Enter a date from today onwards )}
); } ``` ## Related Components * **Label**: Accessible label for form controls * **FieldError**: Inline validation messages for form fields * **Description**: Helper text for form fields ## Styling ### Passing Tailwind CSS classes ```tsx import {DateField, Label, DateInputGroup, Description} from '@heroui/react'; function CustomDateField() { return ( {(segment) => } Select a date for your appointment. ); } ``` ### Customizing the component classes DateField has minimal default styling. Override the `.date-field` class to customize the container styling. ```css @layer components { .date-field { @apply flex flex-col gap-1; &[data-invalid="true"], &[aria-invalid="true"] { [data-slot="description"] { @apply hidden; } } [data-slot="label"] { @apply w-fit; } [data-slot="description"] { @apply px-1; } } } ``` ### CSS Classes * `.date-field` – Root container with minimal styling (`flex flex-col gap-1`) > **Note:** Child components ([Label](/docs/components/label), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options. DateInputGroup styling is documented below in the API Reference section. ### Interactive States DateField automatically manages these data attributes based on its state: * **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid * **Required**: `[data-required="true"]` - Applied when `isRequired` is true * **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true * **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused ## API Reference ### DateField Props DateField inherits all props from React Aria's [DateField](https://react-aria.adobe.com/DateField.md) component. #### Base Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------ | | `children` | `React.ReactNode \| (values: DateFieldRenderProps) => React.ReactNode` | - | Child components (Label, DateInputGroup, etc.) or render function. | | `className` | `string \| (values: DateFieldRenderProps) => string` | - | CSS classes for styling, supports render props. | | `style` | `React.CSSProperties \| (values: DateFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. | | `fullWidth` | `boolean` | `false` | Whether the date field should take full width of its container | | `id` | `string` | - | The element's unique identifier. | #### Value Props | Prop | Type | Default | Description | | ------------------ | ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------- | | `value` | `DateValue \| null` | - | Current value (controlled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. | | `defaultValue` | `DateValue \| null` | - | Default value (uncontrolled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. | | `onChange` | `(value: DateValue \| null) => void` | - | Handler called when the value changes. | | `placeholderValue` | `DateValue \| null` | - | Placeholder date that influences the format of the placeholder. | #### Validation Props | Prop | Type | Default | Description | | -------------------- | -------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `isRequired` | `boolean` | `false` | Whether user input is required before form submission. | | `isInvalid` | `boolean` | - | Whether the value is invalid. | | `minValue` | `DateValue \| null` | - | The minimum allowed date that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. | | `maxValue` | `DateValue \| null` | - | The maximum allowed date that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. | | `isDateUnavailable` | `(date: DateValue) => boolean` | - | Callback that is called for each date. If it returns true, the date is unavailable. | | `validate` | `(value: DateValue) => ValidationError \| true \| null \| undefined` | - | Custom validation function. | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. | #### Format Props | Prop | Type | Default | Description | | ------------------------- | ------------- | ------- | -------------------------------------------------------------------------------------------- | | `granularity` | `Granularity` | - | Determines the smallest unit displayed. Defaults to `"day"` for dates, `"minute"` for times. | | `hourCycle` | `12 \| 24` | - | Whether to display time in 12 or 24 hour format. By default, determined by locale. | | `hideTimeZone` | `boolean` | `false` | Whether to hide the time zone abbreviation. | | `shouldForceLeadingZeros` | `boolean` | - | Whether to always show leading zeros in month, day, and hour fields. | #### State Props | Prop | Type | Default | Description | | ------------ | --------- | ------- | -------------------------------------------------- | | `isDisabled` | `boolean` | - | Whether the input is disabled. | | `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed. | #### Form Props | Prop | Type | Default | Description | | -------------- | --------- | ------- | -------------------------------------------------------------------------------- | | `name` | `string` | - | Name of the input element, for HTML form submission. Submits as ISO 8601 string. | | `autoFocus` | `boolean` | - | Whether the element should receive focus on render. | | `autoComplete` | `string` | - | Type of autocomplete functionality the input should provide. | #### Accessibility Props | Prop | Type | Default | Description | | ------------------ | -------- | ------- | ----------------------------------------------------- | | `aria-label` | `string` | - | Accessibility label when no visible label is present. | | `aria-labelledby` | `string` | - | ID of elements that label this field. | | `aria-describedby` | `string` | - | ID of elements that describe this field. | | `aria-details` | `string` | - | ID of elements with additional details. | ### Composition Components DateField works with these separate components that should be imported and used directly: * **Label** - Field label component from `@heroui/react` * **DateInputGroup** - Date input component with segmented editing from `@heroui/react` (documented below) * **Description** - Helper text component from `@heroui/react` * **FieldError** - Validation error message from `@heroui/react` Each of these components has its own props API. Use them directly within DateField for composition: ```tsx import {parseDate} from '@internationalized/date'; import {DateField, Label, DateInputGroup, Description, FieldError} from '@heroui/react'; {(segment) => } Select a date from today onwards. Please select a valid date. ``` ### 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 {/* ... */} ``` > **Note:** DateField uses the [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) package for date manipulation, parsing, and type definitions. See the [Internationalized Date documentation](https://react-aria.adobe.com/internationalized/date/) for more information about available types and functions. ### DateFieldRenderProps When using render props with `className`, `style`, or `children`, these values are available: | Prop | Type | Description | | ---------------- | --------- | ----------------------------------------------- | | `isDisabled` | `boolean` | Whether the field is disabled. | | `isInvalid` | `boolean` | Whether the field is currently invalid. | | `isReadOnly` | `boolean` | Whether the field is read-only. | | `isRequired` | `boolean` | Whether the field is required. | | `isFocused` | `boolean` | Whether the field is currently focused. | | `isFocusWithin` | `boolean` | Whether any child element is focused. | | `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). | ### DateInputGroup Props DateInputGroup accepts all props from React Aria's `Group` component plus the following: | Prop | Type | Default | Description | | ------------- | --------- | ------- | -------------------------------------------------------------------- | | `className` | `string` | - | Tailwind classes merged with the component styles. | | `fullWidth` | `boolean` | `false` | Whether the date input group should take full width of its container | | `isOnSurface` | `boolean` | `false` | Whether the input is displayed on a surface (affects styling) | ### DateInputGroup.Input Props DateInputGroup.Input accepts all props from React Aria's `DateInput` component plus the following: | Prop | Type | Default | Description | | ------------- | --------- | ------- | ------------------------------------------------------------- | | `className` | `string` | - | Tailwind classes merged with the component styles. | | `isOnSurface` | `boolean` | `false` | Whether the input is displayed on a surface (affects styling) | The `DateInput` component accepts a render prop function that receives date segments. Each segment represents a part of the date (year, month, day, etc.). ### DateInputGroup.Segment Props DateInputGroup.Segment accepts all props from React Aria's `DateSegment` component: | Prop | Type | Default | Description | | ----------- | ------------- | ------- | ------------------------------------------------------- | | `segment` | `DateSegment` | - | The date segment object from the DateInput render prop. | | `className` | `string` | - | Tailwind classes merged with the component styles. | ### DateInputGroup.Prefix Props DateInputGroup.Prefix accepts standard HTML `div` attributes: | Prop | Type | Default | Description | | ----------- | ----------- | ------- | -------------------------------------------------- | | `className` | `string` | - | Tailwind classes merged with the component styles. | | `children` | `ReactNode` | - | Content to display in the prefix slot. | ### DateInputGroup.Suffix Props DateInputGroup.Suffix accepts standard HTML `div` attributes: | Prop | Type | Default | Description | | ----------- | ----------- | ------- | -------------------------------------------------- | | `className` | `string` | - | Tailwind classes merged with the component styles. | | `children` | `ReactNode` | - | Content to display in the suffix slot. | ## DateInputGroup Styling ### Customizing the component classes The base classes power every instance. Override them once with `@layer components`. ```css @layer components { .date-input-group { @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none; &:hover, &[data-hovered="true"] { @apply bg-field-hover; } &[data-focus-within="true"], &:focus-within { @apply status-focused-field; } &[data-invalid="true"] { @apply status-invalid-field; } &[data-disabled="true"], &[aria-disabled="true"] { @apply status-disabled; } } .date-input-group__input { @apply flex flex-1 items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none; } .date-input-group__segment { @apply inline-block rounded-md px-0.5 text-end tabular-nums outline-none; &:focus, &[data-focused="true"] { @apply bg-accent-soft text-accent-soft-foreground; } } .date-input-group__prefix, .date-input-group__suffix { @apply pointer-events-none shrink-0 text-field-placeholder flex items-center; } } ``` ### DateInputGroup CSS Classes * `.date-input-group` – Root container styling * `.date-input-group__input` – Input wrapper styling * `.date-input-group__segment` – Individual date segment styling * `.date-input-group__prefix` – Prefix element styling * `.date-input-group__suffix` – Suffix element styling ### DateInputGroup Interactive States * **Hover**: `:hover` or `[data-hovered="true"]` * **Focus Within**: `[data-focus-within="true"]` or `:focus-within` * **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`) * **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]` * **Segment Focus**: `:focus` or `[data-focused="true"]` on segment elements * **Segment Placeholder**: `[data-placeholder="true"]` on segment elements # Description **Category**: react **URL**: https://v3.heroui.com/docs/react/components/description **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/description.mdx > Provides supplementary text for form fields and other components ## Import ```tsx import { Description } from '@heroui/react'; ``` ## Usage ```tsx import {Description, Input, Label} from "@heroui/react"; export function Basic() { return (
We'll never share your email with anyone else.
); } ``` ## Related Components * **TextField**: Composition-friendly fields with labels and validation * **Input**: Single-line text input built on React Aria * **TextArea**: Multiline text input with focus management ## API ### Description Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | The content of the description | ## Accessibility The Description component enhances accessibility by: * Using semantic HTML that screen readers can identify * Providing the `slot="description"` attribute for React Aria integration * Supporting proper text contrast ratios ## Styling The Description component uses the following CSS classes: * `.description` - Base description styles with `muted` text color ## Examples ### With Form Fields ```tsx
Must be at least 8 characters with one uppercase letter
``` ### Integration with TextField ```tsx import {TextField, Label, Input, Description} from '@heroui/react'; We'll never share your email ``` When using the [TextField](./text-field) component, accessibility attributes are automatically applied to the label and description. # ErrorMessage **Category**: react **URL**: https://v3.heroui.com/docs/react/components/error-message **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/error-message.mdx > A low-level error message component for displaying errors ## Import ```tsx import { ErrorMessage } from '@heroui/react'; ``` ## Usage `ErrorMessage` is a low-level component built on React Aria's `Text` component with an `errorMessage` slot. It's designed for displaying error messages in **non-form components** such as `TagGroup`, `Calendar`, and other collection-based components. ```tsx "use client"; import type {Key} from "@heroui/react"; import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react"; import {useMemo, useState} from "react"; export function ErrorMessageBasic() { const [selected, setSelected] = useState>(new Set()); const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]); return ( setSelected(keys)} > News Travel Gaming Shopping Select at least one category {!!isInvalid && <>Please select at least one category} ); } ``` ### Anatomy ```tsx import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react'; ``` ## Related Components * **TagGroup**: Focusable list of tags with selection and removal support ## When to Use `ErrorMessage` is **not tied to forms**. It's a generic error display component for non-form contexts. * **Recommended for** non-form components (e.g., `TagGroup`, `Calendar`, collection components) * **For form fields**, we recommend using [`FieldError`](/docs/components/field-error) instead, which provides form-specific validation features and automatic error handling, following standardized form validation patterns. ## ErrorMessage vs FieldError | Component | Use Case | Form Integration | Example Components | | -------------- | ------------------------- | ---------------- | ------------------------------------ | | `ErrorMessage` | Non-form components | No | `TagGroup`, `Calendar` | | `FieldError` | Form fields (recommended) | Yes | `TextField`, `NumberField`, `Select` | For form validation, we recommend using `FieldError` as it follows standardized form validation patterns and provides form-specific features. See the [FieldError documentation](/docs/components/field-error) and the [Form guide](/docs/components/form) for examples and best practices. ## API Reference ### ErrorMessage Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | The error message content | **Note**: `ErrorMessage` is built on React Aria's `Text` component with `slot="errorMessage"`. It can be targeted using the `[slot=errorMessage]` CSS selector. ## Accessibility The ErrorMessage component enhances accessibility by: * Using semantic HTML that screen readers can identify * Providing the `slot="errorMessage"` attribute for React Aria integration * Supporting proper text contrast ratios for error states * Following WAI-ARIA best practices for error messaging ## Styling ### Passing Tailwind CSS classes ```tsx import { ErrorMessage } from '@heroui/react'; function CustomErrorMessage() { return ( Custom styled error message ); } ``` ### Customizing the component classes To customize the ErrorMessage component classes, you can use the `@layer components` directive.
[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .error-message { @apply text-red-600 text-sm font-medium; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The ErrorMessage component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/error-message.css)): #### Base Classes * `.error-message` - Base error message styles with danger color and text truncation #### Slot Classes * `[slot="errorMessage"]` - ErrorMessage slot styles for React Aria integration # FieldError **Category**: react **URL**: https://v3.heroui.com/docs/react/components/field-error **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/field-error.mdx > Displays validation error messages for form fields ## Import ```tsx import { FieldError } from '@heroui/react'; ``` ## Usage The FieldError component displays validation error messages for form fields. It automatically appears when the parent field is marked as invalid and provides smooth opacity transitions. ```tsx "use client"; import {FieldError, Input, Label, TextField} from "@heroui/react"; import {useState} from "react"; export function Basic() { const [value, setValue] = useState("jr"); const isInvalid = value.length > 0 && value.length < 3; return ( setValue(e.target.value)} /> Username must be at least 3 characters ); } ``` ## Related Components * **TextField**: Composition-friendly fields with labels and validation * **Input**: Single-line text input built on React Aria * **TextArea**: Multiline text input with focus management ## API ### FieldError Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------ | ------- | ---------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| ((validation: ValidationResult) => ReactNode)` | - | Error message content or render function | ## Accessibility The FieldError component ensures accessibility by: * Using proper ARIA attributes for error announcement * Supporting screen readers with semantic HTML * Providing visual and programmatic error indication * Automatically managing visibility based on validation state ## Styling The FieldError component uses the following CSS classes: * `.field-error` - Base error styles with danger color * Only shows when the `data-visible` attribute is present * Text is truncated with ellipsis for long messages ## Examples ### Basic Validation ```tsx export function Basic() { const [value, setValue] = useState(""); const isInvalid = value.length > 0 && value.length < 3; return ( setValue(e.target.value)} /> Username must be at least 3 characters ); } ``` ### With Dynamic Messages ```tsx 0}> {(validation) => validation.validationErrors.join(', ')} ``` ### Custom Validation Logic ```tsx function EmailField() { const [email, setEmail] = useState(''); const isInvalid = email.length > 0 && !email.includes('@'); return ( setEmail(e.target.value)} /> Email must include @ symbol ); } ``` ### Multiple Error Messages ```tsx {errors.map((error, i) => (
{error}
))} ``` # Fieldset **Category**: react **URL**: https://v3.heroui.com/docs/react/components/fieldset **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/fieldset.mdx > Group related form controls with legends, descriptions, and actions ## Import ```tsx import { Fieldset } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {FloppyDisk} from "@gravity-ui/icons"; import { Button, Description, FieldError, FieldGroup, Fieldset, Form, Input, Label, TextArea, TextField, } from "@heroui/react"; export function Basic() { const onSubmit = (e: React.FormEvent) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record = {}; // Convert FormData to plain object formData.forEach((value, key) => { data[key] = value.toString(); }); alert("Form submitted successfully!"); }; return (
Profile Settings Update your profile information. { if (value.length < 3) { return "Name must be at least 3 characters"; } return null; }} > { if (value.length < 10) { return "Bio must be at least 10 characters"; } return null; }} >