} startName="startDate" > Trip dates {(segment) => } {(segment) => } {(day) => {day}} {(date) => } {({year}) => } ); } ``` ## Related Components * **RangeCalendar**: Interactive month grid for selecting date ranges * **Calendar**: Interactive month grid for selecting dates * **DateField**: Date input field with labels, descriptions, and validation ## Styling ### Passing Tailwind CSS classes You can style each composition part independently: ```tsx import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react'; function CustomDateRangePicker() { return ( Trip dates {(segment) => } {(segment) => } {/* RangeCalendar parts */} ); } ``` ### Customizing the component classes To customize DateRangePicker base classes, use `@layer components`. ```css @layer components { .date-range-picker { @apply inline-flex flex-col gap-1; } .date-range-picker__trigger { @apply inline-flex items-center justify-between; } .date-range-picker__trigger-indicator { @apply text-muted; } .date-range-picker__range-separator { @apply px-2 text-default; } .date-range-picker__popover { @apply min-w-[var(--trigger-width)] p-0; } } ``` HeroUI follows [BEM](https://getbem.com/) naming for reusable customization. ### CSS Classes DateRangePicker uses these classes in `packages/styles/components/date-range-picker.css`: * `.date-range-picker` - Root wrapper. * `.date-range-picker__trigger` - Trigger part that opens the popover. * `.date-range-picker__trigger-indicator` - Default/custom indicator slot. * `.date-range-picker__range-separator` - Separator between start and end date inputs. * `.date-range-picker__popover` - Popover content wrapper. ### Interactive States DateRangePicker supports React Aria data attributes and pseudo states: * **Open**: `[data-open="true"]` on trigger. * **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]` on trigger. * **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]` on trigger. * **Hover**: `:hover` or `[data-hovered="true"]` on trigger. ## API Reference ### DateRangePicker Props DateRangePicker inherits all props from React Aria [DateRangePicker](https://react-aria.adobe.com/DateRangePicker). | Prop | Type | Default | Description | | -------------- | ---------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | `value` | `{ start: DateValue; end: DateValue } \| null` | - | Controlled selected date range value. | | `defaultValue` | `{ start: DateValue; end: DateValue } \| null` | - | Default selected range in uncontrolled mode. | | `onChange` | `(value: { start: DateValue; end: DateValue } \| null) => void` | - | Called when selected range changes. | | `isOpen` | `boolean` | - | Controlled popover open state. | | `defaultOpen` | `boolean` | `false` | Initial popover open state. | | `onOpenChange` | `(isOpen: boolean) => void` | - | Called when popover open state changes. | | `isDisabled` | `boolean` | `false` | Disables range selection and trigger interactions. | | `isInvalid` | `boolean` | - | Marks the field as invalid for validation state. | | `minValue` | `DateValue` | - | Minimum selectable date. | | `maxValue` | `DateValue` | - | Maximum selectable date. | | `startName` | `string` | - | Name used for the start date in HTML form submission. | | `endName` | `string` | - | Name used for the end date in HTML form submission. | | `children` | `ReactNode \| (values: DateRangePickerRenderProps) => ReactNode` | - | Composed content or render function. | | `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. | ### Composition Parts | Component | Description | | ---------------------------------- | ----------------------------------------------------------- | | `DateRangePicker.Root` | Root date range picker container and state owner. | | `DateRangePicker.Trigger` | Trigger button, usually rendered inside `DateField.Suffix`. | | `DateRangePicker.TriggerIndicator` | Indicator slot with default calendar icon. | | `DateRangePicker.RangeSeparator` | Separator part between start and end date inputs. | | `DateRangePicker.Popover` | Popover wrapper for `RangeCalendar` content. | ### Related packages * [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components * [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree * [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction # RangeCalendar **Category**: react **URL**: https://v3.heroui.com/docs/react/components/range-calendar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(date-and-time)/range-calendar.mdx > Composable date range picker with month grid, navigation, and year picker support built on React Aria RangeCalendar ## Import ```tsx import { RangeCalendar } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {RangeCalendar} from "@heroui/react"; export function Basic() { return ( {(day) => {day}} {(date) => } ); } ``` ### Anatomy ```tsx import {RangeCalendar} from '@heroui/react'; export default () => ( {(day) => {day}} {(date) => } ) ``` ### Year Picker `RangeCalendar.YearPickerTrigger`, `RangeCalendar.YearPickerGrid`, and their body/cell subcomponents provide an integrated year navigation pattern. ```tsx "use client"; import {RangeCalendar} from "@heroui/react"; export function YearPicker() { return ( {(day) => {day}} {(date) => } {({year}) => } ); } ``` ### Default Value ```tsx "use client"; import {RangeCalendar} from "@heroui/react"; import {parseDate} from "@internationalized/date"; export function DefaultValue() { return ( {(day) => {day}} {(date) => } ); } ``` ### Controlled ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Button, ButtonGroup, Description, RangeCalendar} from "@heroui/react"; import { getLocalTimeZone, parseDate, startOfMonth, startOfWeek, today, } from "@internationalized/date"; import {useState} from "react"; import {useLocale} from "react-aria-components"; type DateRange = { start: DateValue; end: DateValue; }; export function Controlled() { const [value, setValue] = useState(null); const [focusedDate, setFocusedDate] = useState(parseDate("2025-12-25")); const {locale} = useLocale(); return (

{ const start = today(getLocalTimeZone()); setFocusedDate(start); }} > This week { const nextWeekStart = startOfWeek(today(getLocalTimeZone()).add({weeks: 1}), locale); setFocusedDate(nextWeekStart); }} > Next week { const nextMonthStart = startOfMonth(today(getLocalTimeZone()).add({months: 1})); setFocusedDate(nextMonthStart); }} > Next month {(day) => {day}} {(date) => } Selected range: {value ? `${value.start.toString()} -> ${value.end.toString()}` : "(none)"}

{ const start = today(getLocalTimeZone()); setValue({end: start.add({days: 6}), start}); setFocusedDate(start); }} > Set 1 week { const start = parseDate("2025-12-20"); setValue({end: parseDate("2025-12-31"), start}); setFocusedDate(start); }} > Set Holidays setValue(null)}> Clear

); } ``` ### Min and Max Dates ```tsx "use client"; import {Description, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function MinMaxDates() { const now = today(getLocalTimeZone()); const minDate = now; const maxDate = now.add({months: 3}); return (

{(day) => {day}} {(date) => } Select dates between today and {maxDate.toString()}

); } ``` ### Unavailable Dates Use `isDateUnavailable` to block dates such as weekends, holidays, or booked slots. ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Description, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function UnavailableDates() { const now = today(getLocalTimeZone()); const blockedRanges = [ [now.add({days: 2}), now.add({days: 5})], [now.add({days: 12}), now.add({days: 13})], ] as const; const isDateUnavailable = (date: DateValue) => { return blockedRanges.some(([start, end]) => date.compare(start) >= 0 && date.compare(end) <= 0); }; return (

{(day) => {day}} {(date) => } Some days are unavailable

); } ``` ### Allows Non-Contiguous Ranges Enable `allowsNonContiguousRanges` to allow selection across unavailable dates. ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Description, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function AllowsNonContiguousRanges() { const now = today(getLocalTimeZone()); const blockedRanges = [ [now.add({days: 2}), now.add({days: 5})], [now.add({days: 12}), now.add({days: 13})], ] as const; const isDateUnavailable = (date: DateValue) => { return blockedRanges.some(([start, end]) => date.compare(start) >= 0 && date.compare(end) <= 0); }; return (

{(day) => {day}} {(date) => } Non-contiguous ranges are allowed across unavailable dates

); } ``` ### Disabled ```tsx "use client"; import {Description, RangeCalendar} from "@heroui/react"; export function Disabled() { return (

{(day) => {day}} {(date) => } Range calendar is disabled

); } ``` ### Read Only ```tsx "use client"; import {Description, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function ReadOnly() { return (

{(day) => {day}} {(date) => } Range calendar is read-only

); } ``` ### Invalid ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Description, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; type DateRange = { start: DateValue; end: DateValue; }; export function Invalid() { const now = today(getLocalTimeZone()); const [value, setValue] = useState({ end: now.add({days: 14}), start: now.add({days: 6}), }); const isInvalid = value.end.compare(value.start) > 7; return (

{(day) => {day}} {(date) => } {isInvalid ? (

Maximum stay duration is 1 week

) : ( Select a stay of up to 7 days )}

); } ``` ### Focused Value ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Button, Description, RangeCalendar} from "@heroui/react"; import {parseDate} from "@internationalized/date"; import {useState} from "react"; export function FocusedValue() { const [focusedDate, setFocusedDate] = useState(parseDate("2025-06-15")); return (

{(day) => {day}} {(date) => } Focused: {focusedDate.toString()}

setFocusedDate(parseDate("2025-01-01"))} > Go to Jan setFocusedDate(parseDate("2025-06-15"))} > Go to Jun setFocusedDate(parseDate("2025-12-25"))} > Go to Christmas

); } ``` ### Cell Indicators You can customize `RangeCalendar.Cell` children and use `RangeCalendar.CellIndicator` to display metadata like events. ```tsx "use client"; import {RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, isToday} from "@internationalized/date"; const datesWithEvents = [3, 7, 12, 15, 21, 28]; export function WithIndicators() { return ( {(day) => {day}} {(date) => ( {({formattedDate}) => ( <> {formattedDate} {(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && ( )} )} )} ); } ``` ### Multiple Months Render multiple grids with `visibleDuration` and `offset` for booking and planning experiences. ```tsx "use client"; import {RangeCalendar} from "@heroui/react"; import {getLocalTimeZone} from "@internationalized/date"; import React from "react"; import {RangeCalendarStateContext, useLocale} from "react-aria-components"; function RangeCalendarMonthHeading({offset = 0}: {offset?: number}) { const state = React.useContext(RangeCalendarStateContext)!; const {locale} = useLocale(); const startDate = state.visibleRange.start; const monthDate = startDate.add({months: offset}); const dateObj = monthDate.toDate(getLocalTimeZone()); const monthYear = new Intl.DateTimeFormat(locale, {month: "long", year: "numeric"}).format( dateObj, ); return {monthYear}; } export function MultipleMonths() { return (

{(day) => {day}} {(date) => }

{(day) => {day}} {(date) => }

); } ``` ### International Calendars By default, RangeCalendar displays dates using the calendar system for the user's locale. You can override this by wrapping your RangeCalendar with `I18nProvider` and setting the [Unicode calendar locale extension](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string). The example below shows the Indian calendar system: ```tsx "use client"; import {RangeCalendar} from "@heroui/react"; import {I18nProvider} from "react-aria-components"; export function InternationalCalendar() { return ( {(day) => {day}} {(date) => } {({year}) => } ); } ``` **Note:** The `onChange` event always returns a date in the same calendar system as the `value` or `defaultValue` (Gregorian if no value is provided), regardless of the displayed locale. ### Real-World Example ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Button, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, isWeekend, today} from "@internationalized/date"; import {useState} from "react"; import {useLocale} from "react-aria-components"; type DateRange = { start: DateValue; end: DateValue; }; export function BookingCalendar() { const [selectedRange, setSelectedRange] = useState(null); const {locale} = useLocale(); const blockedDates = [5, 6, 12, 13, 14, 20]; const isDateUnavailable = (date: DateValue) => { return isWeekend(date, locale) || blockedDates.includes(date.day); }; return (

{(day) => {day}} {(date) => ( {({formattedDate, isUnavailable}) => ( <> {formattedDate} {!isUnavailable && !isWeekend(date, locale) && blockedDates.includes(date.day) && } )} )}

Blocked dates Weekend/Unavailable

{selectedRange ? ( Book {selectedRange.start.toString()} -> {selectedRange.end.toString()} ) : null}

); } ``` ## Related Components * **Calendar**: Interactive month grid for selecting dates * **DateField**: Date input field with labels, descriptions, and validation * **DatePicker**: Composable date picker with date field trigger and calendar popover ## Styling ### Passing Tailwind CSS classes ```tsx import {RangeCalendar} from '@heroui/react'; function CustomRangeCalendar() { return ( {(day) => {day}} {(date) => } ); } ``` ### Customizing the component classes ```css @layer components { .range-calendar { @apply w-80 rounded-2xl border border-border bg-surface p-3 shadow-sm; } .range-calendar__heading { @apply text-sm font-semibold text-default; } .range-calendar__cell[data-selected="true"] .range-calendar__cell-button { @apply bg-accent text-accent-foreground; } } ``` ### CSS Classes RangeCalendar uses these classes in `packages/styles/components/range-calendar.css` and `packages/styles/components/calendar-year-picker.css`: * `.range-calendar` - Root container. * `.range-calendar__header` - Header row containing nav buttons and heading. * `.range-calendar__heading` - Current month label. * `.range-calendar__nav-button` - Previous/next navigation controls. * `.range-calendar__grid` - Main day grid. * `.range-calendar__grid-header` - Weekday header row wrapper. * `.range-calendar__grid-body` - Date rows wrapper. * `.range-calendar__header-cell` - Weekday header cell. * `.range-calendar__cell` - Interactive day cell wrapper. * `.range-calendar__cell-button` - Interactive day button inside each cell. * `.range-calendar__cell-indicator` - Dot indicator inside a day cell. * `.calendar-year-picker__trigger` - Year picker toggle button. * `.calendar-year-picker__trigger-heading` - Heading text inside year picker trigger. * `.calendar-year-picker__trigger-indicator` - Indicator icon inside year picker trigger. * `.calendar-year-picker__year-grid` - Overlay grid of selectable years. * `.calendar-year-picker__year-cell` - Individual year option. ### Interactive States RangeCalendar supports both pseudo-classes and React Aria data attributes: * **Selected**: `[data-selected="true"]` * **Selection start**: `[data-selection-start="true"]` * **Selection end**: `[data-selection-end="true"]` * **Range middle**: `[data-selection-in-range="true"]` * **Today**: `[data-today="true"]` * **Unavailable**: `[data-unavailable="true"]` * **Outside month**: `[data-outside-month="true"]` * **Hovered**: `:hover` or `[data-hovered="true"]` * **Pressed**: `:active` or `[data-pressed="true"]` * **Focus visible**: `:focus-visible` or `[data-focus-visible="true"]` * **Disabled**: `:disabled` or `[data-disabled="true"]` ## API Reference ### RangeCalendar Props RangeCalendar inherits all props from React Aria [RangeCalendar](https://react-spectrum.adobe.com/react-aria/RangeCalendar.html). | Prop | Type | Default | Description | | --------------------------- | ---------------------------------------- | --------------------------- | ------------------------------------------------------ | | `value` | `RangeValue \| null` | - | Controlled selected range. | | `defaultValue` | `RangeValue \| null` | - | Initial selected range (uncontrolled). | | `onChange` | `(value: RangeValue) => void` | - | Called when selection changes. | | `focusedValue` | `DateValue` | - | Controlled focused date. | | `onFocusChange` | `(value: DateValue) => void` | - | Called when focus moves to another date. | | `minValue` | `DateValue` | Calendar-aware `1900-01-01` | Earliest selectable date. | | `maxValue` | `DateValue` | Calendar-aware `2099-12-31` | Latest selectable date. | | `isDateUnavailable` | `(date: DateValue) => boolean` | - | Marks dates as unavailable. | | `allowsNonContiguousRanges` | `boolean` | `false` | Allows ranges that span unavailable dates. | | `isDisabled` | `boolean` | `false` | Disables interaction and selection. | | `isReadOnly` | `boolean` | `false` | Keeps content readable but prevents selection changes. | | `isInvalid` | `boolean` | `false` | Marks the calendar as invalid for validation UI. | | `visibleDuration` | `{months?: number}` | `{months: 1}` | Number of visible months. | | `defaultYearPickerOpen` | `boolean` | `false` | Initial open state of internal year picker. | | `isYearPickerOpen` | `boolean` | - | Controlled year picker open state. | | `onYearPickerOpenChange` | `(isOpen: boolean) => void` | - | Called when year picker open state changes. | ### Composition Parts | Component | Description | | ------------------------------------------ | ---------------------------------------------------------------------- | | `RangeCalendar.Header` | Header container for navigation and heading. | | `RangeCalendar.Heading` | Current month/year heading. | | `RangeCalendar.NavButton` | Previous/next navigation control (`slot="previous"` or `slot="next"`). | | `RangeCalendar.Grid` | Day grid for one month (`offset` supported for multi-month layouts). | | `RangeCalendar.GridHeader` | Weekday header container. | | `RangeCalendar.GridBody` | Date cell body container. | | `RangeCalendar.HeaderCell` | Weekday label cell. | | `RangeCalendar.Cell` | Individual date cell. | | `RangeCalendar.CellIndicator` | Optional indicator element for custom metadata. | | `RangeCalendar.YearPickerTrigger` | Trigger to toggle year-picker mode. | | `RangeCalendar.YearPickerTriggerHeading` | Localized heading content inside the year-picker trigger. | | `RangeCalendar.YearPickerTriggerIndicator` | Toggle icon inside the year-picker trigger. | | `RangeCalendar.YearPickerGrid` | Overlay year selection grid container. | | `RangeCalendar.YearPickerGridBody` | Body renderer for year grid cells. | | `RangeCalendar.YearPickerCell` | Individual year option cell. | ### RangeCalendar.Cell Render Props When `RangeCalendar.Cell` children is a function, React Aria render props are available: | Prop | Type | Description | | ------------------ | --------- | ---------------------------------------------------- | | `formattedDate` | `string` | Localized day label for the cell. | | `isSelected` | `boolean` | Whether the date is selected. | | `isSelectionStart` | `boolean` | Whether the date is the start of the selected range. | | `isSelectionEnd` | `boolean` | Whether the date is the end of the selected range. | | `isUnavailable` | `boolean` | Whether the date is unavailable. | | `isDisabled` | `boolean` | Whether the cell is disabled. | | `isOutsideMonth` | `boolean` | Whether the date belongs to adjacent month. | For a complete list of supported calendar systems and their identifiers, see: * [React Aria Calendar Implementations](https://react-aria.adobe.com/internationalized/date/Calendar#implementations) * [React Aria International Calendars](https://react-aria.adobe.com/Calendar#international-calendars) ### Related packages * [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — date types (`CalendarDate`, `CalendarDateTime`, `ZonedDateTime`) and utilities used by all date components * [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — override locale for a subtree * [`useLocale`](https://react-aria.adobe.com/useLocale) — read the current locale and layout direction # TimeField **Category**: react **URL**: https://v3.heroui.com/docs/react/components/time-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(date-and-time)/time-field.mdx > Time input field with labels, descriptions, and validation built on React Aria TimeField ## Import ```tsx import { TimeField } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {Label, TimeField} from "@heroui/react"; export function Basic() { return ( Time {(segment) => } ); } ``` ### Anatomy ```tsx import {TimeField, Label, Description, FieldError} from '@heroui/react'; export default () => ( {(segment) => } ) ``` > **TimeField** combines label, time input, description, and error into a single accessible component. ### With Description ```tsx "use client"; import {Description, Label, TimeField} from "@heroui/react"; export function WithDescription() { return (

Start time {(segment) => } Enter the start time End time {(segment) => } Enter the end time

); } ``` ### Required Field ```tsx "use client"; import {Description, Label, TimeField} from "@heroui/react"; export function Required() { return (

Time {(segment) => } Appointment time {(segment) => } Required field

); } ``` ### Validation Use `isInvalid` together with `FieldError` to surface validation messages. ```tsx "use client"; import {FieldError, Label, TimeField} from "@heroui/react"; export function Invalid() { return (

Time {(segment) => } Please enter a valid time Time {(segment) => } Time must be within business hours

); } ``` ### With Validation TimeField supports validation with `minValue`, `maxValue`, and custom validation logic. ```tsx "use client"; import type {Time} from "@internationalized/date"; import {Description, FieldError, Label, TimeField} from "@heroui/react"; import {parseTime} from "@internationalized/date"; import {useState} from "react"; export function WithValidation() { const [value, setValue] = useState(null); const minTime = parseTime("09:00"); const maxTime = parseTime("17:00"); const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0); return (

Time {(segment) => } {isInvalid ? ( Time must be between 9:00 AM and 5:00 PM ) : ( Enter a time between 9:00 AM and 5:00 PM )}

); } ``` ### Controlled Control the value to synchronize with other components or state management. ```tsx "use client"; import type {TimeValue} from "@heroui/react"; import {Button, Description, Label, TimeField} from "@heroui/react"; import {Time, getLocalTimeZone, now} from "@internationalized/date"; import {useState} from "react"; export function Controlled() { const [value, setValue] = useState(null); return (

Time {(segment) => } Current value: {value ? value.toString() : "(empty)"}

{ const currentTime = now(getLocalTimeZone()); setValue(new Time(currentTime.hour, currentTime.minute, currentTime.second)); }} > Set now setValue(null)}> Clear

); } ``` ### Disabled State ```tsx "use client"; import {Description, Label, TimeField} from "@heroui/react"; import {Time, getLocalTimeZone, now} from "@internationalized/date"; export function Disabled() { const currentTime = now(getLocalTimeZone()); const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second); return (

Time {(segment) => } This time field is disabled Time {(segment) => } This time field is disabled

); } ``` ### With Icons Add prefix or suffix icons to enhance the time field. ```tsx "use client"; import {Clock} from "@gravity-ui/icons"; import {Label, TimeField} from "@heroui/react"; export function WithPrefixIcon() { return ( Time {(segment) => } ); } ``` ```tsx "use client"; import {Clock} from "@gravity-ui/icons"; import {Label, TimeField} from "@heroui/react"; export function WithSuffixIcon() { return ( Time {(segment) => } ); } ``` ```tsx "use client"; import {ChevronDown, Clock} from "@gravity-ui/icons"; import {Description, Label, TimeField} from "@heroui/react"; export function WithPrefixAndSuffix() { return ( Time {(segment) => } Enter a time ); } ``` ### Full Width ```tsx "use client"; import {ChevronDown, Clock} from "@gravity-ui/icons"; import {Label, TimeField} from "@heroui/react"; export function FullWidth() { return (

Time {(segment) => } Time {(segment) => }

); } ``` ### On Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on TimeField.Group to apply the lower emphasis variant suitable for surface backgrounds. ```tsx "use client"; import {Clock} from "@gravity-ui/icons"; import {Description, Label, Surface, TimeField} from "@heroui/react"; export function OnSurface() { return ( Time {(segment) => } Enter a time Appointment time {(segment) => } Enter a time for your appointment ); } ``` ### Form Example Complete form example with validation and submission handling. ```tsx "use client"; import type {Time} from "@internationalized/date"; import {Clock} from "@gravity-ui/icons"; import {Button, Description, FieldError, Form, Label, TimeField} from "@heroui/react"; import {parseTime} from "@internationalized/date"; import {useState} from "react"; export function FormExample() { const [value, setValue] = useState(null); const [isSubmitting, setIsSubmitting] = useState(false); const minTime = parseTime("09:00"); const maxTime = parseTime("17:00"); const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); if (!value || isInvalid) { return; } setIsSubmitting(true); // Simulate API call setTimeout(() => { console.log("Time submitted:", {time: value}); setValue(null); setIsSubmitting(false); }, 1500); }; return (

Appointment time {(segment) => } {isInvalid ? ( Time must be between 9:00 AM and 5:00 PM ) : ( Enter a time between 9:00 AM and 5:00 PM )} {isSubmitting ? "Submitting..." : "Submit"}

); } ``` ## Related Components * **Label**: Accessible label for form controls * **FieldError**: Inline validation messages for form fields * **Description**: Helper text for form fields ### Custom Render Function ```tsx "use client"; import {Label, TimeField} from "@heroui/react"; export function CustomRenderFunction() { return (

} > Time {(segment) => } ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import {TimeField, Label, Description} from '@heroui/react'; function CustomTimeField() { return ( Appointment time {(segment) => } Select a time for your appointment. ); } ``` ### Customizing the component classes TimeField has minimal default styling. Override the `.time-field` class to customize the container styling. ```css @layer components { .time-field { @apply flex flex-col gap-1; &[data-invalid="true"], &[aria-invalid="true"] { [data-slot="description"] { @apply hidden; } } [data-slot="label"] { @apply w-fit; } [data-slot="description"] { @apply px-1; } } } ``` ### CSS Classes * `.time-field` – Root container with minimal styling (`flex flex-col gap-1`) > **Note:** Child components ([Label](/docs/components/label), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options. TimeField.Group styling is documented below in the API Reference section. ### Interactive States TimeField automatically manages these data attributes based on its state: * **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 ### TimeField Props TimeField inherits all props from React Aria's [TimeField](https://react-aria.adobe.com/TimeField) component. #### Base Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------------------------ | ------- | ------------------------------------------------------------------- | | `children` | `React.ReactNode \| (values: TimeFieldRenderProps) => React.ReactNode` | - | Child components (Label, TimeField.Group, etc.) or render function. | | `className` | `string \| (values: TimeFieldRenderProps) => string` | - | CSS classes for styling, supports render props. | | `style` | `React.CSSProperties \| (values: TimeFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. | | `fullWidth` | `boolean` | `false` | Whether the time field should take full width of its container | | `id` | `string` | - | The element's unique identifier. | | `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. | #### Value Props | Prop | Type | Default | Description | | ------------------ | ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------- | | `value` | `TimeValue \| null` | - | Current value (controlled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. | | `defaultValue` | `TimeValue \| null` | - | Default value (uncontrolled). Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. | | `onChange` | `(value: TimeValue \| null) => void` | - | Handler called when the value changes. | | `placeholderValue` | `TimeValue \| null` | - | Placeholder time that influences the format of the placeholder. Defaults to 12:00 AM or 00:00 depending on the hour cycle. | #### Validation Props | Prop | Type | Default | Description | | -------------------- | -------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `isRequired` | `boolean` | `false` | Whether user input is required before form submission. | | `isInvalid` | `boolean` | - | Whether the value is invalid. | | `minValue` | `TimeValue \| null` | - | The minimum allowed time that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. | | `maxValue` | `TimeValue \| null` | - | The maximum allowed time that a user may select. Uses [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) types. | | `validate` | `(value: TimeValue) => ValidationError \| true \| null \| undefined` | - | Custom validation function. | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. | #### Format Props | Prop | Type | Default | Description | | ------------------------- | -------------------------------- | ---------- | ----------------------------------------------------------------------------------------- | | `granularity` | `'hour' \| 'minute' \| 'second'` | `'minute'` | Determines the smallest unit displayed in the time picker. | | `hourCycle` | `12 \| 24` | - | Whether to display time in 12 or 24 hour format. By default, determined by locale. | | `hideTimeZone` | `boolean` | `false` | Whether to hide the time zone abbreviation. | | `shouldForceLeadingZeros` | `boolean` | - | Whether to always show leading zeros in the hour field. By default, determined by locale. | #### State Props | 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. | #### 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 TimeField works with these separate components that should be imported and used directly: * **Label** - Field label component from `@heroui/react` * **TimeField.Group** - Time input group component (documented below) * **TimeField.Input** - Input component with segmented editing from `@heroui/react` * **TimeField.Segment** - Individual time segment (hour, minute, second, etc.) * **TimeField.Prefix** / **TimeField.Suffix** - Prefix and suffix slots for the input group * **Description** - Helper text component from `@heroui/react` * **FieldError** - Validation error message from `@heroui/react` Each of these components has its own props API. Use them directly within TimeField for composition: ```tsx import {parseTime} from '@internationalized/date'; import {TimeField, Label, Description, FieldError} from '@heroui/react'; Appointment Time {(segment) => } Select a time between 9:00 AM and 5:00 PM. Please select a valid time. ``` ### TimeValue Types TimeField uses types from [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/): * `Time` - Time only (hour, minute, second) * `CalendarDateTime` - Date with time but no timezone (TimeField displays only the time portion) * `ZonedDateTime` - Date with time and timezone (TimeField displays only the time portion) Example: ```tsx import {parseTime, Time, getLocalTimeZone, now} from '@internationalized/date'; // Parse from string const time = parseTime('14:30'); // Create from current time const currentTime = now(getLocalTimeZone()); const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second); // Use in TimeField {/* ... */} ``` > **Note:** TimeField uses the [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) package for time manipulation, parsing, and type definitions. See the [Internationalized Date documentation](https://react-aria.adobe.com/internationalized/date/) for more information about available types and functions. ### TimeFieldRenderProps When using render props with `className`, `style`, or `children`, these values are available: | 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). | ### TimeField.Group Props TimeField.Group accepts all props from React Aria's `Group` component plus the following: | Prop | Type | Default | Description | | ----------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `className` | `string` | - | Tailwind classes merged with the component styles. | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | ### TimeField.Input Props TimeField.Input accepts all props from React Aria's `DateInput` component plus the following: | Prop | Type | Default | Description | | ----------- | -------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `className` | `string` | - | Tailwind classes merged with the component styles. | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | The `TimeField.Input` component accepts a render prop function that receives date segments. Each segment represents a part of the time (hour, minute, second, etc.). ### TimeField.Segment Props TimeField.Segment accepts all props from React Aria's `DateSegment` component: | Prop | Type | Default | Description | | ----------- | ------------- | ------- | ------------------------------------------------------------- | | `segment` | `DateSegment` | - | The date segment object from the TimeField.Input render prop. | | `className` | `string` | - | Tailwind classes merged with the component styles. | ### TimeField.Prefix Props TimeField.Prefix accepts standard HTML `div` attributes: | Prop | Type | Default | Description | | ----------- | ----------- | ------- | -------------------------------------------------- | | `className` | `string` | - | Tailwind classes merged with the component styles. | | `children` | `ReactNode` | - | Content to display in the prefix slot. | ### TimeField.Suffix Props TimeField.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. | ## TimeField.Group Styling ### Customizing the component classes The base classes power every instance. Override them once with `@layer components`. ```css @layer components { .date-input-group { @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none; &:hover, &[data-hovered="true"] { @apply bg-field-hover; } &[data-focus-within="true"], &:focus-within { @apply status-focused-field; } &[data-invalid="true"] { @apply status-invalid-field; } &[data-disabled="true"], &[aria-disabled="true"] { @apply status-disabled; } } .date-input-group__input { @apply flex flex-1 items-center gap-px rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none; } .date-input-group__segment { @apply inline-block rounded-md px-0.5 text-end tabular-nums outline-none; &:focus, &[data-focused="true"] { @apply bg-accent-soft text-accent-soft-foreground; } } .date-input-group__prefix, .date-input-group__suffix { @apply pointer-events-none shrink-0 text-field-placeholder flex items-center; } } ``` ### TimeField.Group CSS Classes * `.date-input-group` – Root container styling * `.date-input-group__input` – Input wrapper styling * `.date-input-group__segment` – Individual time segment styling * `.date-input-group__prefix` – Prefix element styling * `.date-input-group__suffix` – Suffix element styling ### TimeField.Group Interactive States * **Hover**: `:hover` or `[data-hovered="true"]` * **Focus Within**: `[data-focus-within="true"]` or `:focus-within` * **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`) * **Disabled**: `[data-disabled="true"]` or `[aria-disabled="true"]` * **Segment Focus**: `:focus` or `[data-focused="true"]` on segment elements * **Segment Placeholder**: `[data-placeholder="true"]` on segment elements # 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. Refresh Refresh {/* 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

Retry Retry {/* 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 ( Select your interests Choose all that apply Coding Love building software Design Enjoy creating beautiful interfaces Writing 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 () => ( {/* Optional */} {/* Optional */} {/* Optional */} ); ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx import {Checkbox, CheckboxGroup, Description, Label, Surface} from "@heroui/react"; export function OnSurface() { return ( Select your interests Choose all that apply Coding Love building software Design Enjoy creating beautiful interfaces Writing Passionate about content creation ); } ``` ### With Custom Indicator ```tsx "use client"; import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function WithCustomIndicator() { return ( Features Select the features you want {({isSelected}) => isSelected ? ( ) : null } Email notifications Receive updates via email {({isSelected}) => isSelected ? ( ) : null } Newsletter 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 : []); }} > Select all

Coding Design Writing

); } ``` ### 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 ( Your skills Coding Design Writing Selected: {selected.join(", ") || "None"} ); } ``` ### 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(", ")}`); }} > Preferences Email notifications SMS notifications Push notifications Please select at least one notification method. Submit

); } ``` ### Disabled ```tsx import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function Disabled() { return ( Features Feature selection is temporarily disabled Feature 1 This feature is coming soon Feature 2 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 (

Notification preferences Choose how you want to receive updates

{addOns.map((addon) => (

{addon.title} {addon.description}

))}

); } ``` ### Custom Render Function ```tsx "use client"; import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function CustomRenderFunction() { return (

}> Select your interests Choose all that apply Coding Love building software Design Enjoy creating beautiful interfaces Writing Passionate about content creation ); } ``` ## 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 ( Option 1 ); } ``` ### 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 | | `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. | ### 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 ( Accept terms and conditions ); } ``` ### Anatomy Import the Checkbox component and access all parts using dot notation. ```tsx import { Checkbox, Label, Description } from '@heroui/react'; export default () => ( {/* Optional */} ); ``` ### Disabled ```tsx import {Checkbox, Description, Label} from "@heroui/react"; export function Disabled() { return ( Premium Feature This feature is coming soon ); } ``` ### Default Selected ```tsx import {Checkbox, Label} from "@heroui/react"; export function DefaultSelected() { return ( Enable email notifications ); } ``` ### Controlled ```tsx "use client"; import {Checkbox, Label} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [isSelected, setIsSelected] = useState(true); return (

Email notifications

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); }} > Select all Shows indeterminate state (dash icon) ); } ``` ### With Label ```tsx import {Checkbox, Label} from "@heroui/react"; export function WithLabel() { return ( Send me marketing emails ); } ``` ### With Description ```tsx import {Checkbox, Description, Label} from "@heroui/react"; export function WithDescription() { return ( Email notifications 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 ? "Terms accepted" : "Accept terms"} {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 (

Enable notifications

Subscribe to newsletter

Receive marketing updates

Submit

); } ``` ### Invalid ```tsx import {Checkbox, Description, Label} from "@heroui/react"; export function Invalid() { return ( I agree to the terms 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 } Heart {({isSelected}) => isSelected ? ( ) : null } Plus {({isIndeterminate}) => isIndeterminate ? ( ) : null } Indeterminate

); } ``` ### Full Rounded ```tsx import {Checkbox, Label} from "@heroui/react"; export function FullRounded() { return (

Rounded checkboxes Small size

Default size

Large size

Extra large size

); } ``` ### Variants The Checkbox component supports two visual variants: * **`primary`** (default) - Standard styling with default background, suitable for most use cases * **`secondary`** - Lower emphasis variant, suitable for use in Surface components ```tsx import {Checkbox, Description, Label} from "@heroui/react"; export function Variants() { return (

Primary variant

Primary checkbox Standard styling with default background

Secondary variant

Secondary checkbox Lower emphasis variant for use in surfaces

); } ``` ### Custom Render Function ```tsx "use client"; import {Checkbox, Label} from "@heroui/react"; export function CustomRenderFunction() { return (

}> Accept terms and conditions

); } ``` ## 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 ( Custom Checkbox ); } ``` ### 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 | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | | `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 | | `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. | ### 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 | # 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 (

Email 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

Password Must be at least 8 characters with one uppercase letter

``` ### Integration with TextField ```tsx import {TextField, Label, Input, Description} from '@heroui/react'; Email 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)} > Required Categories 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 ( Username 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 ( Username setValue(e.target.value)} /> Username must be at least 3 characters ); } ``` ### With Dynamic Messages ```tsx 0}> Password {(validation) => validation.validationErrors.join(', ')} ``` ### Custom Validation Logic ```tsx function EmailField() { const [email, setEmail] = useState(''); const isInvalid = email.length > 0 && !email.includes('@'); return ( Email setEmail(e.target.value)} /> Email must include @ symbol ); } ``` ### Multiple Error Messages ```tsx Username {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; }} > Name Email { if (value.length < 10) { return "Bio must be at least 10 characters"; } return null; }} > Bio <Description>Minimum 10 characters</Description> <FieldError /> </TextField> </FieldGroup> <Fieldset.Actions> <Button type="submit"> <FloppyDisk /> Save changes </Button> <Button type="reset" variant="secondary"> Cancel </Button> </Fieldset.Actions> </Fieldset> </Form> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on form controls (Input, TextArea, etc.) to apply the lower emphasis variant suitable for surface backgrounds. ```tsx "use client"; import {FloppyDisk} from "@gravity-ui/icons"; import { Button, Description, FieldError, Fieldset, Form, Input, Label, Surface, TextArea, TextField, } from "@heroui/react"; import React from "react"; export function OnSurface() { const onSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record<string, string> = {}; // Convert FormData to plain object formData.forEach((value, key) => { data[key] = value.toString(); }); alert("Form submitted successfully!"); }; return ( <div className="flex items-center justify-center rounded-3xl bg-surface p-6"> <Surface className="w-full min-w-[380px]"> <Form onSubmit={onSubmit}> <Fieldset className="w-full"> <Fieldset.Legend>Profile Settings</Fieldset.Legend> <Description>Update your profile information.</Description> <Fieldset.Group> <TextField isRequired name="name" validate={(value) => { if (value.length < 3) { return "Name must be at least 3 characters"; } return null; }} > <Label>Name</Label> <Input placeholder="John Doe" variant="secondary" /> <FieldError /> </TextField> <TextField isRequired name="email" type="email"> <Label>Email</Label> <Input placeholder="john@example.com" variant="secondary" /> <FieldError /> </TextField> <TextField isRequired name="bio" validate={(value) => { if (value.length < 10) { return "Bio must be at least 10 characters"; } return null; }} > <Label>Bio</Label> <TextArea placeholder="Tell us about yourself..." variant="secondary" /> <Description>Minimum 10 characters</Description> <FieldError /> </TextField> </Fieldset.Group> <Fieldset.Actions> <Button type="submit"> <FloppyDisk /> Save changes </Button> <Button type="reset" variant="tertiary"> Cancel </Button> </Fieldset.Actions> </Fieldset> </Form> </Surface> </div> ); } ``` ### Anatomy Import the Fieldset component and access all parts using dot notation. ```tsx import { Fieldset } from '@heroui/react'; export default () => ( <Fieldset> <Fieldset.Legend /> <Fieldset.Group> {/* form fields go here */} </Fieldset.Group> <Fieldset.Actions> {/* action buttons go here */} </Fieldset.Actions> </Fieldset> ) ``` ## Related Components * **TextField**: Composition-friendly fields with labels and validation * **Label**: Accessible label for form controls * **CheckboxGroup**: Group of checkboxes with shared state ## Styling ### Passing Tailwind CSS classes ```tsx import { Fieldset, TextField, Label, Input } from '@heroui/react'; function CustomFieldset() { return ( <Fieldset className="rounded-xl border border-border bg-surface p-6 shadow-sm"> <Fieldset.Legend className="text-lg font-semibold">Team members</Fieldset.Legend> <Fieldset.Group className="grid gap-4 md:grid-cols-2"> <TextField> <Label>First name</Label> <Input className="rounded-full border-border/60" placeholder="Jane" /> </TextField> <TextField> <Label>Last name</Label> <Input className="rounded-full border-border/60" placeholder="Doe" /> </TextField> </Fieldset.Group> <Fieldset.Actions className="justify-end gap-3"> {/* Action buttons */} </Fieldset.Actions> </Fieldset> ); } ``` ### Customizing the component classes Use the `@layer components` directive to target Fieldset [BEM](https://getbem.com/)-style classes. ```css @layer components { .fieldset { @apply gap-5 rounded-xl border border-border/60 bg-surface p-6 shadow-field; } .fieldset__legend { @apply text-lg font-semibold; } .fieldset__field_group { @apply gap-3 md:grid md:grid-cols-2; } .fieldset__actions { @apply flex justify-end gap-2 pt-2; } } ``` ### CSS Classes The Fieldset compound component exposes these CSS selectors: * `.fieldset` – Root container * `.fieldset__legend` – Legend element * `.fieldset__field_group` – Wrapper for grouped fields * `.fieldset__actions` – Action bar below the fields ## API Reference ### Fieldset Props | Prop | Type | Default | Description | | ------------- | ------------------------------------------- | ----------------------------------------------- | --------------------------------------------------------- | | `className` | `string` | - | Tailwind CSS classes applied to the root element. | | `children` | `React.ReactNode` | - | Fieldset content (legend, groups, descriptions, actions). | | `nativeProps` | `React.HTMLAttributes<HTMLFieldSetElement>` | Supports native fieldset attributes and events. | | ### Fieldset.Legend Props | Prop | Type | Default | Description | | ------------- | ----------------------------------------- | ------- | ---------------------------------------- | | `className` | `string` | - | Tailwind classes for the legend element. | | `children` | `React.ReactNode` | - | Legend content, usually plain text. | | `nativeProps` | `React.HTMLAttributes<HTMLLegendElement>` | - | Native legend attributes. | ### Fieldset.Group Props | Prop | Type | Default | Description | | ------------- | -------------------------------------- | ------- | ---------------------------------------------- | | `className` | `string` | - | Layout and spacing classes for grouped fields. | | `children` | `React.ReactNode` | - | Form controls to group inside the fieldset. | | `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | Native div attributes. | ### Fieldset.Actions Props | Prop | Type | Default | Description | | ------------- | -------------------------------------- | ------- | ------------------------------------------------- | | `className` | `string` | - | Tailwind classes to align action buttons or text. | | `children` | `React.ReactNode` | - | Action buttons or helper text. | | `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | Native div attributes. | </page> <page url="/docs/react/components/form"> # Form **Category**: react **URL**: https://v3.heroui.com/docs/react/components/form **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/form.mdx > Wrapper component for form validation and submission handling ## Import ```tsx import { Form } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {Check} from "@gravity-ui/icons"; import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react"; export function Basic() { const onSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record<string, string> = {}; // Convert FormData to plain object formData.forEach((value, key) => { data[key] = value.toString(); }); alert(`Form submitted with: ${JSON.stringify(data, null, 2)}`); }; return ( <Form className="flex w-96 flex-col gap-4" onSubmit={onSubmit}> <TextField isRequired name="email" type="email" validate={(value) => { if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(value)) { return "Please enter a valid email address"; } return null; }} > <Label>Email</Label> <Input placeholder="john@example.com" /> <FieldError /> </TextField> <TextField isRequired minLength={8} name="password" type="password" validate={(value) => { if (value.length < 8) { return "Password must be at least 8 characters"; } if (!/[A-Z]/.test(value)) { return "Password must contain at least one uppercase letter"; } if (!/[0-9]/.test(value)) { return "Password must contain at least one number"; } return null; }} > <Label>Password</Label> <Input placeholder="Enter your password" /> <Description>Must be at least 8 characters with 1 uppercase and 1 number</Description> <FieldError /> </TextField> <div className="flex gap-2"> <Button type="submit"> <Check /> Submit </Button> <Button type="reset" variant="secondary"> Reset </Button> </div> </Form> ); } ``` ### Anatomy Import all parts and piece them together. ```tsx import {Form, Button} from '@heroui/react'; export default () => ( <Form> {/* Form fields go here */} <Button type="submit"/> <Button type="reset"/> </Form> ) ``` ### Custom Render Function ```tsx "use client"; import {Check} from "@gravity-ui/icons"; import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react"; export function CustomRenderFunction() { const onSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record<string, string> = {}; // Convert FormData to plain object formData.forEach((value, key) => { data[key] = value.toString(); }); alert(`Form submitted with: ${JSON.stringify(data, null, 2)}`); }; return ( <Form className="flex w-96 flex-col gap-4" render={(props) => <form {...props} data-custom="foo" />} onSubmit={onSubmit} > <TextField isRequired name="email" type="email" validate={(value) => { if (!/^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i.test(value)) { return "Please enter a valid email address"; } return null; }} > <Label>Email</Label> <Input placeholder="john@example.com" /> <FieldError /> </TextField> <TextField isRequired minLength={8} name="password" type="password" validate={(value) => { if (value.length < 8) { return "Password must be at least 8 characters"; } if (!/[A-Z]/.test(value)) { return "Password must contain at least one uppercase letter"; } if (!/[0-9]/.test(value)) { return "Password must contain at least one number"; } return null; }} > <Label>Password</Label> <Input placeholder="Enter your password" /> <Description>Must be at least 8 characters with 1 uppercase and 1 number</Description> <FieldError /> </TextField> <div className="flex gap-2"> <Button type="submit"> <Check /> Submit </Button> <Button type="reset" variant="secondary"> Reset </Button> </div> </Form> ); } ``` ## Related Components * **Button**: Allows a user to perform an action * **Fieldset**: Group related form controls with legends * **TextField**: Composition-friendly fields with labels and validation ## Styling ### Passing Tailwind CSS classes ```tsx import {Form, TextField, Label, Input, FieldError, Button} from '@heroui/react'; function CustomForm() { return ( <Form className="w-full max-w-md space-y-4 rounded-lg border border-border bg-surface p-6"> <TextField> <Label className="text-sm font-medium">Email</Label> <Input className="rounded-full border-border/60" placeholder="Enter your email" /> <FieldError className="text-xs" /> </TextField> <Button type="submit" className="w-full"> Submit </Button> </Form> ); } ``` ## API Reference ### Form Props The Form component is a wrapper around React Aria's Form primitive that provides form validation and submission handling capabilities. | Prop | Type | Default | Description | | -------------------- | ------------------------------------------------------------------------------ | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | `action` | `string \| FormHTMLAttributes['action']` | - | The URL to submit the form data to. | | `className` | `string` | - | Tailwind CSS classes applied to the form element. | | `children` | `React.ReactNode` | - | Form content (fields, buttons, etc.). | | `encType` | `'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'` | - | The encoding type for form data submission. | | `method` | `'get' \| 'post'` | - | The HTTP method to use when submitting the form. | | `onInvalid` | `(event: FormEvent<HTMLFormElement>) => void` | - | Handler called when the form validation fails. By default, the first invalid field will be focused. Use `preventDefault()` to customize focus behavior. | | `onReset` | `(event: FormEvent<HTMLFormElement>) => void` | - | Handler called when the form is reset. | | `onSubmit` | `(event: FormEvent<HTMLFormElement>) => void` | - | Handler called when the form is submitted. | | `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | - | Where to display the response after submitting the form. | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML validation or ARIA validation. 'native' blocks form submission, 'aria' displays errors in realtime. | | `validationErrors` | `ValidationErrors` | - | Server-side validation errors mapped by field name. Displayed immediately and cleared when user modifies the field. | | `aria-label` | `string` | - | Accessibility label for the form. | | `aria-labelledby` | `string` | - | ID of element that labels the form. Creates a form landmark when provided. | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | Overrides the default DOM element with a custom render function. | ### Form Validation The Form component integrates with React Aria's validation system, allowing you to: * Use built-in HTML5 validation attributes (`required`, `minLength`, `pattern`, etc.) * Provide custom validation functions on TextField components * Display validation errors with FieldError components * Handle form submission with proper validation * Provide server-side validation errors via `validationErrors` prop #### Validation Behavior The `validationBehavior` prop controls how validation is displayed: * **`native`** (default): Uses native HTML validation, blocks form submission on errors * **`aria`**: Uses ARIA attributes for validation, displays errors in realtime as user types, doesn't block submission This behavior can be set at the form level or overridden at individual field level. ### Form Submission Forms can be submitted in several ways: * **Traditional submission**: Set the `action` prop to submit to a URL * **JavaScript handling**: Use the `onSubmit` handler to process form data * **FormData API**: Access form data using the FormData API in your submit handler Example with FormData: ```tsx function handleSubmit(e: FormEvent<HTMLFormElement>) { e.preventDefault(); const formData = new FormData(e.currentTarget); const data = Object.fromEntries(formData); console.log('Form data:', data); } ``` ### Integration with Form Fields The Form component works seamlessly with HeroUI's form field components: * **TextField**: For text inputs with labels and validation * **Checkbox**: For boolean selections * **RadioGroup**: For single selection from multiple options * **Switch**: For toggle controls * **Button**: For form submission and reset actions All field components automatically integrate with the Form's validation and submission behavior when placed inside it. ### Accessibility Forms are accessible by default when using React Aria components. Key features include: * Native `<form>` element semantics * Form landmark creation with `aria-label` or `aria-labelledby` * Automatic focus management on validation errors * ARIA validation attributes when using `validationBehavior="aria"` ### Advanced Usage For more advanced use cases including: * Custom validation context * Form context providers * Integration with third-party libraries * Custom focus management on validation errors Please refer to the [React Aria Form documentation](https://react-spectrum.adobe.com/react-aria/Form.html). </page> <page url="/docs/react/components/input-group"> # InputGroup **Category**: react **URL**: https://v3.heroui.com/docs/react/components/input-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/input-group.mdx > Group related input controls with prefix and suffix elements for enhanced form fields ## Import ```tsx import { InputGroup } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {Envelope} from "@gravity-ui/icons"; import {InputGroup, Label, TextField} from "@heroui/react"; export function Default() { return ( <TextField className="w-full max-w-[280px]" name="email"> <Label>Email address</Label> <InputGroup> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" /> </InputGroup> </TextField> ); } ``` ### Anatomy ```tsx import {InputGroup, TextField, Label} from '@heroui/react'; export default () => ( <TextField> <Label /> <InputGroup> <InputGroup.Prefix /> <InputGroup.Input /> {/* Or use InputGroup.TextArea for multiline input */} <InputGroup.Suffix /> </InputGroup> </TextField> ) ``` > **InputGroup** wraps an input field with optional prefix and suffix elements, creating a visually cohesive group. It's typically used within **[TextField](/docs/components/text-field)** to add icons, text, buttons, or other elements before or after the input. Use **InputGroup.Input** for single-line inputs or **InputGroup.TextArea** for multiline text inputs. ### With Prefix Icon Add an icon before the input field. ```tsx "use client"; import {Envelope} from "@gravity-ui/icons"; import {Description, InputGroup, Label, TextField} from "@heroui/react"; export function WithPrefixIcon() { return ( <TextField className="w-full max-w-[280px]" name="email"> <Label>Email address</Label> <InputGroup> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" /> </InputGroup> <Description>We'll never share this with anyone else</Description> </TextField> ); } ``` ### With Suffix Icon Add an icon after the input field. ```tsx "use client"; import {Envelope} from "@gravity-ui/icons"; import {Description, InputGroup, Label, TextField} from "@heroui/react"; export function WithSuffixIcon() { return ( <TextField className="w-full max-w-[280px]" name="email"> <Label>Email address</Label> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" /> <InputGroup.Suffix> <Envelope className="size-4 text-muted" /> </InputGroup.Suffix> </InputGroup> <Description>We don't send spam</Description> </TextField> ); } ``` ### With Prefix and Suffix Combine both prefix and suffix elements. ```tsx "use client"; import {Description, InputGroup, Label, TextField} from "@heroui/react"; export function WithPrefixAndSuffix() { return ( <TextField className="w-full max-w-[280px]" defaultValue="10" name="price"> <Label>Set a price</Label> <InputGroup> <InputGroup.Prefix>$</InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[200px]" type="number" /> <InputGroup.Suffix>USD</InputGroup.Suffix> </InputGroup> <Description>What customers would pay</Description> </TextField> ); } ``` ### Text Prefix Use text as a prefix, such as currency symbols or protocol prefixes. ```tsx "use client"; import {InputGroup, Label, TextField} from "@heroui/react"; export function WithTextPrefix() { return ( <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website"> <Label>Website</Label> <InputGroup> <InputGroup.Prefix>https://</InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[280px]" /> </InputGroup> </TextField> ); } ``` ### Text Suffix Use text as a suffix, such as domain extensions or units. ```tsx "use client"; import {InputGroup, Label, TextField} from "@heroui/react"; export function WithTextSuffix() { return ( <TextField className="w-full max-w-[280px]" defaultValue="heroui" name="website"> <Label>Website</Label> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" /> <InputGroup.Suffix>.com</InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### Icon Prefix and Text Suffix Combine an icon prefix with a text suffix. ```tsx "use client"; import {Globe} from "@gravity-ui/icons"; import {InputGroup, Label, TextField} from "@heroui/react"; export function WithIconPrefixAndTextSuffix() { return ( <TextField className="w-full max-w-[280px]" defaultValue="heroui" name="website"> <Label>Website</Label> <InputGroup> <InputGroup.Prefix> <Globe className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[280px]" /> <InputGroup.Suffix>.com</InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### Copy Button Suffix Add an interactive button in the suffix, such as a copy button. ```tsx "use client"; import {Copy} from "@gravity-ui/icons"; import {Button, InputGroup, Label, TextField} from "@heroui/react"; export function WithCopySuffix() { return ( <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website"> <Label>Website</Label> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" /> <InputGroup.Suffix className="pr-0"> <Button isIconOnly aria-label="Copy" size="sm" variant="ghost"> <Copy className="size-4" /> </Button> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### Icon Prefix and Copy Button Combine an icon prefix with an interactive button suffix. ```tsx "use client"; import {Copy, Globe} from "@gravity-ui/icons"; import {Button, InputGroup, Label, TextField} from "@heroui/react"; export function WithIconPrefixAndCopySuffix() { return ( <TextField className="w-full max-w-[280px]" defaultValue="heroui.com" name="website"> <Label>Website</Label> <InputGroup> <InputGroup.Prefix> <Globe className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[280px]" /> <InputGroup.Suffix className="pr-0"> <Button isIconOnly aria-label="Copy" size="sm" variant="ghost"> <Copy className="size-4" /> </Button> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### Password Toggle Use a button in the suffix to toggle password visibility. ```tsx "use client"; import {Eye, EyeSlash} from "@gravity-ui/icons"; import {Button, InputGroup, Label, TextField} from "@heroui/react"; import {useState} from "react"; export function PasswordWithToggle() { const [isVisible, setIsVisible] = useState(false); return ( <TextField className="w-full max-w-[280px]" name="password"> <Label>Password</Label> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" type={isVisible ? "text" : "password"} value={isVisible ? "87$2h.3diua" : "••••••••"} /> <InputGroup.Suffix className="pr-0"> <Button isIconOnly aria-label={isVisible ? "Hide password" : "Show password"} size="sm" variant="ghost" onPress={() => setIsVisible(!isVisible)} > {isVisible ? <Eye className="size-4" /> : <EyeSlash className="size-4" />} </Button> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### Loading State Show a loading spinner in the suffix to indicate processing. ```tsx "use client"; import {InputGroup, Spinner, TextField} from "@heroui/react"; export function WithLoadingSuffix() { return ( <TextField className="w-full max-w-[280px]" defaultValue="Sending..." name="status"> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" /> <InputGroup.Suffix> <Spinner className="size-4" /> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### Keyboard Shortcut Display keyboard shortcuts using the [Kbd](/docs/components/kbd) component. ```tsx "use client"; import {InputGroup, Kbd, TextField} from "@heroui/react"; export function WithKeyboardShortcut() { return ( <TextField aria-label="Command" className="w-full max-w-[280px]" name="command"> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" placeholder="Command" /> <InputGroup.Suffix className="pr-2"> <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>K</Kbd.Content> </Kbd> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### Badge Suffix Add a badge or chip in the suffix to show status or labels. ```tsx "use client"; import {Chip, InputGroup, TextField} from "@heroui/react"; export function WithBadgeSuffix() { return ( <TextField aria-label="Email address" className="w-full max-w-[280px]" name="email"> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" placeholder="Email address" /> <InputGroup.Suffix className="pr-2"> <Chip color="accent" size="md" variant="soft"> Pro </Chip> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### Required Field InputGroup respects the required state from its parent TextField. ```tsx "use client"; import {Envelope} from "@gravity-ui/icons"; import {Description, InputGroup, Label, TextField} from "@heroui/react"; export function Required() { return ( <div className="flex flex-col gap-4"> <TextField isRequired className="w-full max-w-[280px]" name="email"> <Label>Email address</Label> <InputGroup> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" /> </InputGroup> </TextField> <TextField isRequired className="w-full max-w-[280px]" name="price"> <Label>Set a price</Label> <InputGroup> <InputGroup.Prefix>$</InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[200px]" placeholder="0" type="number" /> <InputGroup.Suffix>USD</InputGroup.Suffix> </InputGroup> <Description>What customers would pay</Description> </TextField> </div> ); } ``` ### Validation InputGroup automatically reflects invalid state from its parent TextField. ```tsx "use client"; import {Envelope} from "@gravity-ui/icons"; import {FieldError, InputGroup, Label, TextField} from "@heroui/react"; export function Invalid() { return ( <div className="flex flex-col gap-4"> <TextField isInvalid isRequired className="w-full max-w-[280px]" name="email"> <Label>Email address</Label> <InputGroup> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" /> </InputGroup> <FieldError>Please enter a valid email address</FieldError> </TextField> <TextField isInvalid isRequired className="w-full max-w-[280px]" name="price"> <Label>Set a price</Label> <InputGroup> <InputGroup.Prefix>$</InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[200px]" placeholder="0" type="number" /> <InputGroup.Suffix>USD</InputGroup.Suffix> </InputGroup> <FieldError>Price must be greater than 0</FieldError> </TextField> </div> ); } ``` ### Disabled State InputGroup respects the disabled state from its parent TextField. ```tsx "use client"; import {Envelope} from "@gravity-ui/icons"; import {InputGroup, Label, TextField} from "@heroui/react"; export function Disabled() { return ( <div className="flex flex-col gap-4"> <TextField isDisabled className="w-full max-w-[280px]" defaultValue="name@email.com" name="email" > <Label>Email address</Label> <InputGroup> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[280px]" /> </InputGroup> </TextField> <TextField isDisabled className="w-full max-w-[280px]" defaultValue="10" name="price"> <Label>Set a price</Label> <InputGroup> <InputGroup.Prefix>$</InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[200px]" type="number" /> <InputGroup.Suffix>USD</InputGroup.Suffix> </InputGroup> </TextField> </div> ); } ``` ### Full Width ```tsx import {Envelope, Eye} from "@gravity-ui/icons"; import {InputGroup, Label, TextField} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <TextField fullWidth name="email"> <Label>Email address</Label> <InputGroup fullWidth> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input placeholder="name@email.com" /> </InputGroup> </TextField> <TextField fullWidth name="password"> <Label>Password</Label> <InputGroup fullWidth> <InputGroup.Input placeholder="Enter password" type="password" /> <InputGroup.Suffix> <Eye className="size-4 text-muted" /> </InputGroup.Suffix> </InputGroup> </TextField> </div> ); } ``` ### Variants The InputGroup component supports two visual variants: * **`primary`** (default) - Standard styling with shadow, suitable for most use cases * **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components ```tsx import {Envelope} from "@gravity-ui/icons"; import {InputGroup, Label, TextField} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-4"> <TextField className="w-[280px]" name="primary"> <Label>Primary variant</Label> <InputGroup variant="primary"> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input placeholder="name@email.com" /> </InputGroup> </TextField> <TextField className="w-[280px]" name="secondary"> <Label>Secondary variant</Label> <InputGroup variant="secondary"> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input placeholder="name@email.com" /> </InputGroup> </TextField> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx "use client"; import {Envelope} from "@gravity-ui/icons"; import {Description, InputGroup, Label, Surface, TextField} from "@heroui/react"; export function OnSurface() { return ( <Surface className="rounded-2xl p-6"> <TextField className="w-full max-w-[280px]" name="email"> <Label>Email address</Label> <InputGroup variant="secondary"> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[280px]" placeholder="name@email.com" /> </InputGroup> <Description>We'll never share this with anyone else</Description> </TextField> </Surface> ); } ``` ### With TextArea Use **InputGroup.TextArea** for multiline text inputs with prefix and suffix elements. When a textarea is present, the container automatically adjusts its height to accommodate the content and aligns prefix/suffix elements to the top. ```tsx "use client"; import {ArrowUp, At, Microphone, PlugConnection, Plus} from "@gravity-ui/icons"; import {Button, InputGroup, Kbd, Spinner, TextField, Tooltip} from "@heroui/react"; import {useState} from "react"; export function WithTextArea() { const [value, setValue] = useState(""); const [isSubmitting, setIsSubmitting] = useState(false); const handleSubmit = () => { if (!value.trim()) return; setIsSubmitting(true); setTimeout(() => { setIsSubmitting(false); setValue(""); }, 1000); }; return ( <TextField fullWidth aria-label="Prompt input" className="flex w-sm flex-col sm:w-lg" name="prompt" > <InputGroup fullWidth className="flex flex-col gap-2 rounded-3xl py-2"> <InputGroup.Prefix className="px-3 py-0"> <Button aria-label="Add context" size="sm" variant="outline"> <At /> Add Context </Button> </InputGroup.Prefix> <InputGroup.TextArea className="w-full resize-none px-3.5 py-0" placeholder="Assign tasks or ask anything..." rows={5} value={value} onChange={(event) => setValue(event.target.value)} /> <InputGroup.Suffix className="flex w-full items-center gap-1.5 px-3 py-0"> <Tooltip delay={0}> <Button isIconOnly aria-label="Attach file" size="sm" variant="tertiary"> <Plus /> </Button> <Tooltip.Content> <p className="text-xs">Add a files and more</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Button isIconOnly aria-label="Connect Apps" size="sm" variant="tertiary"> <PlugConnection /> </Button> <Tooltip.Content> <p className="text-xs">Connect apps</p> </Tooltip.Content> </Tooltip> <div className="ml-auto flex items-center gap-1.5"> <Tooltip delay={0}> <Button isIconOnly aria-label="Voice input" size="sm" variant="ghost"> <Microphone /> </Button> <Tooltip.Content> <p className="text-xs">Voice input</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Button isIconOnly aria-label="Send prompt" isDisabled={!value.trim()} isPending={isSubmitting} onPress={handleSubmit} > {({isPending}) => (isPending ? <Spinner color="current" size="sm" /> : <ArrowUp />)} </Button> <Tooltip.Content className="flex items-center gap-1"> <p className="text-xs">Send</p> <Kbd className="h-4 rounded-sm px-1"> <Kbd.Abbr keyValue="enter" /> </Kbd> </Tooltip.Content> </Tooltip> </div> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ## Related Components * **TextField**: Composition-friendly fields with labels and validation * **Input**: Single-line text input built on React Aria * **Label**: Accessible label for form controls ## Styling ### Passing Tailwind CSS classes ```tsx import {InputGroup, TextField, Label} from '@heroui/react'; function CustomInputGroup() { return ( <TextField> <Label>Website</Label> <InputGroup className="rounded-xl border-2 border-primary"> <InputGroup.Prefix className="bg-primary/10 text-primary"> https:// </InputGroup.Prefix> <InputGroup.Input className="font-medium" /> <InputGroup.Suffix className="bg-primary/10 text-primary"> .com </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### Customizing the component classes InputGroup uses CSS classes that can be customized. Override the component classes to match your design system. ```css @layer components { .input-group { @apply bg-field text-field-foreground shadow-field rounded-field inline-flex min-h-9 items-center overflow-hidden border text-sm outline-none; } .input-group__input { @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none; } .input-group__prefix { @apply text-field-placeholder rounded-l-field flex h-full items-center justify-center rounded-r-none bg-transparent px-3; } .input-group__suffix { @apply text-field-placeholder rounded-r-field flex h-full items-center justify-center rounded-l-none bg-transparent px-3; } /* Secondary variant */ .input-group--secondary { @apply shadow-none; background-color: var(--color-default); } } ``` ### CSS Classes * `.input-group` – Root container with border, background, and flex layout. Uses `min-h-9` for flexible height and `items-center` by default, switching to `items-start` when a textarea is present. * `.input-group__input` – Input element with transparent background and no border. Also used as the base class for textarea elements. * `.input-group__prefix` – Prefix container with left border radius. Aligns to top when used with textarea. * `.input-group__suffix` – Suffix container with right border radius. Aligns to top when used with textarea. * `.input-group--primary` – Primary variant with shadow (default) * `.input-group--secondary` – Secondary variant without shadow, suitable for use in surfaces **Note**: When using `InputGroup.TextArea`, the container automatically switches from `items-center` to `items-start` alignment and uses `height: auto` instead of a fixed height. Prefix and suffix elements align to the top with additional padding to match the textarea's vertical padding. The textarea uses the same `.input-group__input` base class with textarea-specific styles (minimum height and vertical resize) applied via the `[data-slot="input-group-textarea"]` attribute selector. ### Interactive States InputGroup automatically manages these data attributes based on its state: * **Hover**: `[data-hovered]` - Applied when hovering over the group * **Focus Within**: `[data-focus-within]` - Applied when the input is focused * **Invalid**: `[data-invalid]` - Applied when parent TextField is invalid * **Disabled**: `[data-disabled]` or `[aria-disabled]` - Applied when parent TextField is disabled ## API Reference ### InputGroup Props InputGroup inherits all props from React Aria's [Group](https://react-spectrum.adobe.com/react-aria/Group.html) component. #### Base Props | Prop | Type | Default | Description | | ----------- | -------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------- | | `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | Child components (Input, TextArea, Prefix, Suffix) or render function. | | `className` | `string \| (values: GroupRenderProps) => string` | - | CSS classes for styling, supports render props. | | `style` | `React.CSSProperties \| (values: GroupRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. | | `fullWidth` | `boolean` | `false` | Whether the input group should take full width of its container | | `id` | `string` | - | The element's unique identifier. | #### Variant Props | Prop | Type | Default | Description | | --------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | #### Accessibility Props | Prop | Type | Default | Description | | ------------------ | --------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------- | | `aria-label` | `string` | - | Accessibility label when no visible label is present. | | `aria-labelledby` | `string` | - | ID of elements that label this group. | | `aria-describedby` | `string` | - | ID of elements that describe this group. | | `aria-details` | `string` | - | ID of elements with additional details. | | `role` | `'group' \| 'region' \| 'presentation'` | `'group'` | Accessibility role for the group. Use 'region' for important content, 'presentation' for visual-only grouping. | ### Composition Components InputGroup works with these subcomponents: * **InputGroup.Root** - Root container (also available as `InputGroup`) * **InputGroup.Input** - Single-line input element component * **InputGroup.TextArea** - Multiline textarea element component * **InputGroup.Prefix** - Prefix container component * **InputGroup.Suffix** - Suffix container component #### InputGroup.Input Props InputGroup.Input inherits all props from React Aria's [Input](https://react-spectrum.adobe.com/react-aria/Input.html) component. | Prop | Type | Default | Description | | -------------- | -------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `className` | `string` | - | CSS classes for styling. | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | | `type` | `string` | `'text'` | Input type (text, password, email, etc.). | | `value` | `string` | - | Current value (controlled). | | `defaultValue` | `string` | - | Default value (uncontrolled). | | `placeholder` | `string` | - | Placeholder text. | | `disabled` | `boolean` | - | Whether the input is disabled. | | `readOnly` | `boolean` | - | Whether the input is read-only. | #### InputGroup.TextArea Props InputGroup.TextArea inherits all props from React Aria's [TextArea](https://react-spectrum.adobe.com/react-aria/TextArea.html) component. | Prop | Type | Default | Description | | -------------- | -------------------------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `className` | `string` | - | CSS classes for styling. | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the textarea. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | | `value` | `string` | - | Current value (controlled). | | `defaultValue` | `string` | - | Default value (uncontrolled). | | `placeholder` | `string` | - | Placeholder text. | | `rows` | `number` | - | Number of visible text lines. | | `disabled` | `boolean` | - | Whether the textarea is disabled. | | `readOnly` | `boolean` | - | Whether the textarea is read-only. | #### InputGroup.Prefix Props | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ----------------------------------------------------- | | `children` | `React.ReactNode` | - | Content to display in the prefix (icons, text, etc.). | | `className` | `string` | - | CSS classes for styling. | #### InputGroup.Suffix Props | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ---------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Content to display in the suffix (icons, buttons, badges, etc.). | | `className` | `string` | - | CSS classes for styling. | ### Usage Example ```tsx import {InputGroup, TextField, Label, Button} from '@heroui/react'; import {Icon} from '@iconify/react'; function Example() { return ( <TextField> <Label>Email</Label> <InputGroup> <InputGroup.Prefix> <Icon icon="gravity-ui:envelope" /> </InputGroup.Prefix> <InputGroup.Input placeholder="name@email.com" /> <InputGroup.Suffix> <Button isIconOnly size="sm" variant="ghost"> <Icon icon="gravity-ui:check" /> </Button> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### TextArea Usage Example ```tsx import {Envelope} from "@gravity-ui/icons"; import {Description, FieldError, InputGroup, Label, TextField} from "@heroui/react"; import {useState} from "react"; function TextAreaExample() { const [feedback, setFeedback] = useState(""); return ( <TextField fullWidth isInvalid={feedback.length > 500} name="feedback" onChange={setFeedback}> <Label>Your Feedback</Label> <InputGroup fullWidth> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.TextArea className="resize-none" placeholder="Share your thoughts, suggestions, or issues..." rows={5} value={feedback} /> </InputGroup> <Description className="flex w-full items-center justify-between px-1"> <span>Maximum 500 characters.</span> <span className="ml-auto">{feedback.length}/500</span> </Description> <FieldError>Feedback must be less than 500 characters</FieldError> </TextField> ); } ``` </page> <page url="/docs/react/components/input-otp"> # InputOTP **Category**: react **URL**: https://v3.heroui.com/docs/react/components/input-otp **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/input-otp.mdx > A one-time password input component for verification codes and secure authentication ## Import ```tsx import { InputOTP } from '@heroui/react'; ``` ### Usage ```tsx import {InputOTP, Label, Link} from "@heroui/react"; export function Basic() { return ( <div className="flex w-[280px] flex-col gap-2"> <div className="flex flex-col gap-1"> <Label>Verify account</Label> <p className="text-sm text-muted">We've sent a code to a****@gmail.com</p> </div> <InputOTP maxLength={6}> <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> <InputOTP.Slot index={2} /> </InputOTP.Group> <InputOTP.Separator /> <InputOTP.Group> <InputOTP.Slot index={3} /> <InputOTP.Slot index={4} /> <InputOTP.Slot index={5} /> </InputOTP.Group> </InputOTP> <div className="flex items-center gap-[5px] px-1 pt-1"> <p className="text-sm text-muted">Didn't receive a code?</p> <Link className="text-foreground underline" href="#"> Resend </Link> </div> </div> ); } ``` ### Anatomy Import the InputOTP component and access all parts using dot notation. ```tsx import { InputOTP } from '@heroui/react'; export default () => ( <InputOTP maxLength={6}> <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> {/* ...rest of the slots */} </InputOTP.Group> <InputOTP.Separator /> <InputOTP.Group> <InputOTP.Slot index={3} /> {/* ...rest of the slots */} </InputOTP.Group> </InputOTP> ) ``` > **InputOTP** is built on top of [input-otp](https://github.com/guilhermerodz/input-otp) by [@guilherme\_rodz](https://twitter.com/guilherme_rodz), providing a flexible and accessible foundation for OTP input components. ### Four Digits ```tsx import {InputOTP, Label} from "@heroui/react"; export function FourDigits() { return ( <div className="flex w-[280px] flex-col gap-2"> <Label>Enter PIN</Label> <InputOTP maxLength={4}> <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> <InputOTP.Slot index={2} /> <InputOTP.Slot index={3} /> </InputOTP.Group> </InputOTP> </div> ); } ``` ### Disabled State ```tsx import {Description, InputOTP, Label} from "@heroui/react"; export function Disabled() { return ( <div className="flex w-[280px] flex-col gap-2"> <Label isDisabled>Verify account</Label> <Description>Code verification is currently disabled</Description> <InputOTP isDisabled maxLength={6}> <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> <InputOTP.Slot index={2} /> </InputOTP.Group> <InputOTP.Separator /> <InputOTP.Group> <InputOTP.Slot index={3} /> <InputOTP.Slot index={4} /> <InputOTP.Slot index={5} /> </InputOTP.Group> </InputOTP> </div> ); } ``` ### With Pattern Use the `pattern` prop to restrict input to specific characters. HeroUI exports common patterns like `REGEXP_ONLY_CHARS` and `REGEXP_ONLY_DIGITS`. ```tsx import {Description, InputOTP, Label, REGEXP_ONLY_CHARS} from "@heroui/react"; export function WithPattern() { return ( <div className="flex w-[280px] flex-col gap-2"> <Label>Enter code (letters only)</Label> <Description>Only alphabetic characters are allowed</Description> <InputOTP maxLength={6} pattern={REGEXP_ONLY_CHARS}> <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> <InputOTP.Slot index={2} /> </InputOTP.Group> <InputOTP.Separator /> <InputOTP.Group> <InputOTP.Slot index={3} /> <InputOTP.Slot index={4} /> <InputOTP.Slot index={5} /> </InputOTP.Group> </InputOTP> </div> ); } ``` ### Controlled Control the value to synchronize with state, clear the input, or implement custom validation. ```tsx "use client"; import {Description, InputOTP, Label} from "@heroui/react"; import React from "react"; export function Controlled() { const [value, setValue] = React.useState(""); return ( <div className="flex w-[280px] flex-col gap-2"> <Label>Verify account</Label> <InputOTP maxLength={6} value={value} onChange={setValue}> <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> <InputOTP.Slot index={2} /> </InputOTP.Group> <InputOTP.Separator /> <InputOTP.Group> <InputOTP.Slot index={3} /> <InputOTP.Slot index={4} /> <InputOTP.Slot index={5} /> </InputOTP.Group> </InputOTP> <Description> {value.length > 0 ? ( <> Value: {value} ({value.length}/6) •{" "} <button className="font-medium text-foreground underline" onClick={() => setValue("")}> Clear </button> </> ) : ( "Enter a 6-digit code" )} </Description> </div> ); } ``` ### With Validation Use `isInvalid` together with validation messages to surface errors. ```tsx "use client"; import {Button, Description, Form, InputOTP, Label} from "@heroui/react"; import React from "react"; export function WithValidation() { const [value, setValue] = React.useState(""); const [isInvalid, setIsInvalid] = React.useState(false); const onSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const code = formData.get("code"); if (code !== "123456") { setIsInvalid(true); return; } setIsInvalid(false); setValue(""); alert("Code verified successfully!"); }; const handleChange = (val: string) => { setValue(val); setIsInvalid(false); }; return ( <div className="flex w-[280px] flex-col gap-2"> <Form className="flex flex-col gap-2" onSubmit={onSubmit}> <Label>Verify account</Label> <Description>Hint: The code is 123456</Description> <InputOTP aria-describedby={isInvalid ? "code-error" : undefined} isInvalid={isInvalid} maxLength={6} name="code" value={value} onChange={handleChange} > <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> <InputOTP.Slot index={2} /> </InputOTP.Group> <InputOTP.Separator /> <InputOTP.Group> <InputOTP.Slot index={3} /> <InputOTP.Slot index={4} /> <InputOTP.Slot index={5} /> </InputOTP.Group> </InputOTP> <span className="field-error" data-visible={isInvalid} id="code-error"> Invalid code. Please try again. </span> <Button isDisabled={value.length !== 6} type="submit"> Submit </Button> </Form> </div> ); } ``` ### On Complete Use the `onComplete` callback to trigger actions when all slots are filled. ```tsx "use client"; import {Button, Form, InputOTP, Label, Spinner} from "@heroui/react"; import React from "react"; export function OnComplete() { const [value, setValue] = React.useState(""); const [isComplete, setIsComplete] = React.useState(false); const [isSubmitting, setIsSubmitting] = React.useState(false); const handleComplete = (code: string) => { setIsComplete(true); console.log("Code complete:", code); }; const handleSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); setIsSubmitting(true); // Simulate API call setTimeout(() => { setIsSubmitting(false); setValue(""); setIsComplete(false); }, 2000); }; return ( <Form className="flex w-[280px] flex-col gap-2" onSubmit={handleSubmit}> <Label>Verify account</Label> <InputOTP maxLength={6} value={value} onComplete={handleComplete} onChange={(val) => { setValue(val); setIsComplete(false); }} > <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> <InputOTP.Slot index={2} /> </InputOTP.Group> <InputOTP.Separator /> <InputOTP.Group> <InputOTP.Slot index={3} /> <InputOTP.Slot index={4} /> <InputOTP.Slot index={5} /> </InputOTP.Group> </InputOTP> <Button className="mt-2 w-full" isDisabled={!isComplete} isPending={isSubmitting} type="submit" variant="primary" > {isSubmitting ? ( <> <Spinner color="current" size="sm" /> Verifying... </> ) : ( "Verify Code" )} </Button> </Form> ); } ``` ### Form Example A complete two-factor authentication form with validation and submission. ```tsx "use client"; import {Button, Description, Form, InputOTP, Label, Link, Spinner} from "@heroui/react"; import React from "react"; export function FormExample() { const [value, setValue] = React.useState(""); const [error, setError] = React.useState(""); const [isSubmitting, setIsSubmitting] = React.useState(false); const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); setError(""); if (value.length !== 6) { setError("Please enter all 6 digits"); return; } setIsSubmitting(true); // Simulate API call setTimeout(() => { if (value === "123456") { console.log("Code verified successfully!"); setValue(""); } else { setError("Invalid code. Please try again."); } setIsSubmitting(false); }, 1500); }; return ( <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}> <div className="flex flex-col gap-2"> <Label>Two-factor authentication</Label> <Description>Enter the 6-digit code from your authenticator app</Description> <InputOTP isInvalid={!!error} maxLength={6} value={value} onChange={(val) => { setValue(val); setError(""); }} > <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> <InputOTP.Slot index={2} /> </InputOTP.Group> <InputOTP.Separator /> <InputOTP.Group> <InputOTP.Slot index={3} /> <InputOTP.Slot index={4} /> <InputOTP.Slot index={5} /> </InputOTP.Group> </InputOTP> <span className="field-error" data-visible={!!error} id="code-error"> {error} </span> </div> <Button className="w-full" isDisabled={value.length !== 6} isPending={isSubmitting} type="submit" variant="primary" > {isSubmitting ? ( <> <Spinner color="current" size="sm" /> Verifying... </> ) : ( "Verify" )} </Button> <div className="flex items-center justify-center gap-1"> <p className="text-sm text-muted">Having trouble?</p> <Link className="text-sm text-foreground underline" href="#"> Use backup code </Link> </div> </Form> ); } ``` ### Variants The InputOTP component supports two visual variants: * **`primary`** (default) - Standard styling with shadow, suitable for most use cases * **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components ```tsx import {InputOTP, Label} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-6"> <div className="flex flex-col gap-2"> <Label>Primary variant</Label> <InputOTP maxLength={6} variant="primary"> <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> <InputOTP.Slot index={2} /> </InputOTP.Group> <InputOTP.Separator /> <InputOTP.Group> <InputOTP.Slot index={3} /> <InputOTP.Slot index={4} /> <InputOTP.Slot index={5} /> </InputOTP.Group> </InputOTP> </div> <div className="flex flex-col gap-2"> <Label>Secondary variant</Label> <InputOTP maxLength={6} variant="secondary"> <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> <InputOTP.Slot index={2} /> </InputOTP.Group> <InputOTP.Separator /> <InputOTP.Group> <InputOTP.Slot index={3} /> <InputOTP.Slot index={4} /> <InputOTP.Slot index={5} /> </InputOTP.Group> </InputOTP> </div> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx import {InputOTP, Label, Link, Surface} from "@heroui/react"; export function OnSurface() { return ( <Surface className="flex w-full flex-col gap-2 rounded-3xl p-6"> <div className="flex flex-col gap-1"> <Label>Verify account</Label> <p className="text-sm text-muted">We've sent a code to a****@gmail.com</p> </div> <InputOTP maxLength={6} variant="secondary"> <InputOTP.Group> <InputOTP.Slot index={0} /> <InputOTP.Slot index={1} /> <InputOTP.Slot index={2} /> </InputOTP.Group> <InputOTP.Separator /> <InputOTP.Group> <InputOTP.Slot index={3} /> <InputOTP.Slot index={4} /> <InputOTP.Slot index={5} /> </InputOTP.Group> </InputOTP> <div className="flex items-center gap-[5px] px-1 pt-1"> <p className="text-sm text-muted">Didn't receive a code?</p> <Link className="text-foreground underline" href="#"> Resend </Link> </div> </Surface> ); } ``` ## Related Components * **Input**: Single-line text input built on React Aria * **Form**: Form validation and submission handling * **Surface**: Base container surface ## Styling ### Passing Tailwind CSS classes ```tsx import {InputOTP, Label} from '@heroui/react'; function CustomInputOTP() { return ( <div className="flex flex-col gap-2"> <Label className="text-sm font-semibold">Enter verification code</Label> <InputOTP className="gap-3" containerClassName="gap-4" maxLength={6} > <InputOTP.Group className="gap-3"> <InputOTP.Slot className="size-12 rounded-lg border-2 text-lg font-bold" index={0} /> <InputOTP.Slot className="size-12 rounded-lg border-2 text-lg font-bold" index={1} /> <InputOTP.Slot className="size-12 rounded-lg border-2 text-lg font-bold" index={2} /> </InputOTP.Group> <InputOTP.Separator className="bg-border h-1 w-2 rounded-full" /> <InputOTP.Group className="gap-3"> <InputOTP.Slot className="size-12 rounded-lg border-2 text-lg font-bold" index={3} /> <InputOTP.Slot className="size-12 rounded-lg border-2 text-lg font-bold" index={4} /> <InputOTP.Slot className="size-12 rounded-lg border-2 text-lg font-bold" index={5} /> </InputOTP.Group> </InputOTP> </div> ); } ``` ### Customizing the component classes To customize the InputOTP component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .input-otp { @apply gap-3; } .input-otp__slot { @apply size-12 rounded-xl border-2 font-bold; } .input-otp__slot[data-active="true"] { @apply border-primary-500 ring-2 ring-primary-200; } .input-otp__separator { @apply w-2 h-1 bg-border-strong rounded-full; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The InputOTP component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/input-otp.css)): #### Base Classes * `.input-otp` - Base container * `.input-otp__container` - Inner container from input-otp library * `.input-otp__group` - Group of slots * `.input-otp__slot` - Individual input slot * `.input-otp__slot-value` - The character inside a slot * `.input-otp__caret` - Blinking caret indicator * `.input-otp__separator` - Visual separator between groups #### State Classes * `.input-otp__slot[data-active="true"]` - Currently active slot * `.input-otp__slot[data-filled="true"]` - Slot with a character * `.input-otp__slot[data-disabled="true"]` - Disabled slot * `.input-otp__slot[data-invalid="true"]` - Invalid slot * `.input-otp__container[data-disabled="true"]` - Disabled container ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Hover**: `:hover` or `[data-hovered="true"]` on slot * **Active**: `[data-active="true"]` on slot (currently focused) * **Filled**: `[data-filled="true"]` on slot (contains a character) * **Disabled**: `[data-disabled="true"]` on container and slots * **Invalid**: `[data-invalid="true"]` on slots ## API Reference ### InputOTP Props InputOTP is built on top of the [input-otp](https://github.com/guilhermerodz/input-otp) library with additional features. #### Base Props | Prop | Type | Default | Description | | -------------------- | -------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `maxLength` | `number` | - | **Required.** Number of input slots. | | `value` | `string` | - | Controlled value (uncontrolled if not provided). | | `onChange` | `(value: string) => void` | - | Handler called when the value changes. | | `onComplete` | `(value: string) => void` | - | Handler called when all slots are filled. | | `className` | `string` | - | Additional CSS classes for the container. | | `containerClassName` | `string` | - | CSS classes for the inner container. | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | | `children` | `React.ReactNode` | - | InputOTP.Group, InputOTP.Slot, and InputOTP.Separator components. | #### Validation Props | Prop | Type | Default | Description | | ------------------- | --------------- | ------- | ----------------------------------------- | | `isDisabled` | `boolean` | `false` | Whether the input is disabled. | | `isInvalid` | `boolean` | `false` | Whether the input is in an invalid state. | | `validationErrors` | `string[]` | - | Server-side or custom validation errors. | | `validationDetails` | `ValidityState` | - | HTML5 validation details. | #### Input Props | Prop | Type | Default | Description | | ------------------ | --------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------ | | `pattern` | `string` | - | Regex pattern for allowed characters (e.g., `REGEXP_ONLY_DIGITS`). | | `textAlign` | `'left' \| 'center' \| 'right'` | `'left'` | Text alignment within slots. | | `inputMode` | `'numeric' \| 'text' \| 'decimal' \| 'tel' \| 'search' \| 'email' \| 'url'` | `'numeric'` | Virtual keyboard type on mobile devices. | | `placeholder` | `string` | - | Placeholder text for empty slots. | | `pasteTransformer` | `(text: string) => string` | - | Transform pasted text (e.g., remove hyphens). | #### Form Props | Prop | Type | Default | Description | | ----------- | --------- | ------- | ----------------------------------------- | | `name` | `string` | - | Name attribute for form submission. | | `autoFocus` | `boolean` | - | Whether to focus the first slot on mount. | ### InputOTP.Group Props | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ------------------------------------- | | `className` | `string` | - | Additional CSS classes for the group. | | `children` | `React.ReactNode` | - | InputOTP.Slot components. | ### InputOTP.Slot Props | Prop | Type | Default | Description | | ----------- | -------- | ------- | ------------------------------------------- | | `index` | `number` | - | **Required.** Zero-based index of the slot. | | `className` | `string` | - | Additional CSS classes for the slot. | ### InputOTP.Separator Props | Prop | Type | Default | Description | | ----------- | -------- | ------- | ----------------------------------------- | | `className` | `string` | - | Additional CSS classes for the separator. | ### Exported Patterns HeroUI re-exports common regex patterns from input-otp for convenience: ```tsx import { REGEXP_ONLY_DIGITS, REGEXP_ONLY_CHARS, REGEXP_ONLY_DIGITS_AND_CHARS } from '@heroui/react'; // Use with pattern prop <InputOTP pattern={REGEXP_ONLY_DIGITS} maxLength={6}> {/* ... */} </InputOTP> ``` * **REGEXP\_ONLY\_DIGITS** - Only numeric characters (0-9) * **REGEXP\_ONLY\_CHARS** - Only alphabetic characters (a-z, A-Z) * **REGEXP\_ONLY\_DIGITS\_AND\_CHARS** - Alphanumeric characters (0-9, a-z, A-Z) </page> <page url="/docs/react/components/input"> # Input **Category**: react **URL**: https://v3.heroui.com/docs/react/components/input **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/input.mdx > Primitive single-line text input component that accepts standard HTML attributes ## Import ```tsx import { Input } from '@heroui/react'; ``` <Callout> For validation, labels, and error messages, see **[TextField](/docs/components/text-field)**. </Callout> ### Usage ```tsx import {Input} from "@heroui/react"; export function Basic() { return <Input aria-label="Name" className="w-64" placeholder="Enter your name" />; } ``` ### Input Types ```tsx import {Input, Label} from "@heroui/react"; export function Types() { return ( <div className="flex w-80 flex-col gap-4"> <div className="flex flex-col gap-1"> <Label htmlFor="input-type-email">Email</Label> <Input id="input-type-email" placeholder="jane@example.com" type="email" /> </div> <div className="flex flex-col gap-1"> <Label htmlFor="input-type-number">Age</Label> <Input id="input-type-number" min={0} placeholder="30" type="number" /> </div> <div className="flex flex-col gap-1"> <Label htmlFor="input-type-password">Password</Label> <Input id="input-type-password" placeholder="••••••••" type="password" /> </div> </div> ); } ``` ### Controlled ```tsx "use client"; import {Input} from "@heroui/react"; import React from "react"; export function Controlled() { const [value, setValue] = React.useState("heroui.com"); return ( <div className="flex w-80 flex-col gap-2"> <Input aria-label="Domain" placeholder="domain" value={value} onChange={(event) => setValue(event.target.value)} /> <span className="px-1 text-sm text-muted">https://{value || "your-domain"}</span> </div> ); } ``` ### Full Width ```tsx import {Input} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-3"> <Input fullWidth placeholder="Full width input" /> </div> ); } ``` ### Variants The Input component supports two visual variants: * **`primary`** (default) - Standard styling with shadow, suitable for most use cases * **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components ```tsx import {Input} from "@heroui/react"; export function Variants() { return ( <div className="flex w-[240px] flex-col gap-2"> <Input fullWidth placeholder="Primary input" variant="primary" /> <Input fullWidth placeholder="Secondary input" variant="secondary" /> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx import {Input, Surface} from "@heroui/react"; export function OnSurface() { return ( <Surface className="flex h-[180px] w-[280px] items-center justify-center rounded-3xl bg-surface p-4"> <Input className="w-full" placeholder="Your name" variant="secondary" /> </Surface> ); } ``` ## Related Components * **TextField**: Composition-friendly fields with labels and validation * **TextArea**: Multiline text input with focus management * **Label**: Accessible label for form controls ## Styling ### Passing Tailwind CSS classes ```tsx import {Input, Label} from '@heroui/react'; function CustomInput() { return ( <div className="flex flex-col gap-2"> <Label htmlFor="custom-input">Project name</Label> <Input id="custom-input" className="rounded-xl border border-border/70 bgsurface px-4 py-2 text-sm shadow-sm focus-visible:border-primary" placeholder="New web app" /> </div> ); } ``` ### Customizing the component classes The base class `.input` powers every instance. Override it once with `@layer components`. ```css @layer components { .input { @apply rounded-lg border border-border bgsurface px-4 py-2 text-sm shadow-sm transition-colors; &:hover, &[data-hovered="true"] { @apply bg-surface-secondary border-border/80; } &:focus-visible, &[data-focus-visible="true"] { @apply border-primary ring-2 ring-primary/20; } &[data-invalid="true"] { @apply border-danger bg-danger-50/10 text-danger; } } } ``` ### CSS Classes * `.input` – Native input element styling ### Interactive States * **Hover**: `:hover` or `[data-hovered="true"]` * **Focus Visible**: `:focus-visible` or `[data-focus-visible="true"]` * **Invalid**: `[data-invalid="true"]` (also syncs with `aria-invalid`) * **Disabled**: `:disabled` or `[aria-disabled="true"]` * **Read Only**: `[aria-readonly="true"]` ## API Reference ### Input Props Input accepts all standard HTML `<input>` attributes plus the following: | Prop | Type | Default | Description | | -------------- | ------------------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `className` | `string` | - | Tailwind classes merged with the component styles. | | `type` | `string` | `"text"` | Input type (text, email, password, number, etc.). | | `value` | `string` | - | Controlled value. | | `defaultValue` | `string` | - | Uncontrolled initial value. | | `onChange` | `(event: React.ChangeEvent<HTMLInputElement>) => void` | - | Change handler. | | `placeholder` | `string` | - | Placeholder text. | | `disabled` | `boolean` | `false` | Disables the input. | | `readOnly` | `boolean` | `false` | Makes the input read-only. | | `required` | `boolean` | `false` | Marks the input as required. | | `name` | `string` | - | Name for form submission. | | `autoComplete` | `string` | - | Autocomplete hint for the browser. | | `maxLength` | `number` | - | Maximum number of characters. | | `minLength` | `number` | - | Minimum number of characters. | | `pattern` | `string` | - | Regex pattern for validation. | | `min` | `number \| string` | - | Minimum value (for number/date inputs). | | `max` | `number \| string` | - | Maximum value (for number/date inputs). | | `step` | `number \| string` | - | Stepping interval (for number inputs). | | `fullWidth` | `boolean` | `false` | Whether the input should take full width of its container | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | > For validation props like `isInvalid`, `isRequired`, and error handling, use **[TextField](/docs/components/text-field)** with Input as a child component. </page> <page url="/docs/react/components/label"> # Label **Category**: react **URL**: https://v3.heroui.com/docs/react/components/label **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/label.mdx > Renders an accessible label associated with form controls ## Import ```tsx import { Label } from '@heroui/react'; ``` ## Usage ```tsx import {Input, Label} from "@heroui/react"; export function Basic() { return ( <div className="flex flex-col gap-1"> <Label htmlFor="name">Name</Label> <Input className="w-64" id="name" placeholder="Enter your name" type="text" /> </div> ); } ``` ## Related Components * **Input**: Single-line text input built on React Aria * **TextArea**: Multiline text input with focus management * **Fieldset**: Group related form controls with legends ## API ### Label Props | Prop | Type | Default | Description | | ------------ | ----------- | ------- | -------------------------------------------------- | | `htmlFor` | `string` | - | The id of the element the label is associated with | | `isRequired` | `boolean` | `false` | Whether to display a required indicator | | `isDisabled` | `boolean` | `false` | Whether the label is in a disabled state | | `isInvalid` | `boolean` | `false` | Whether the label is in an invalid state | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | The content of the label | ## Accessibility The Label component is built on the native HTML `<label>` element ([MDN Reference](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)) and follows WAI-ARIA best practices: * Associates with form controls using the `htmlFor` attribute * Provides semantic HTML `<label>` element * Supports keyboard navigation when associated with form controls * Communicates required and invalid states to screen readers * Clicking the label focuses/activates the associated form control ## Related Components * **Input**: Single-line text input built on React Aria * **TextArea**: Multiline text input with focus management * **Fieldset**: Group related form controls with legends ## Styling ### CSS Classes The Label component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/label.css)): #### Base Classes * `.label` - Base label styles with text styling #### State Modifier Classes * `.label--required` or `[data-required="true"] > .label` - Shows required asterisk indicator * `.label--disabled` or `[data-disabled="true"] .label` - Disabled state styling * `.label--invalid` or `[data-invalid="true"] .label` or `[aria-invalid="true"] .label` - Invalid state styling (danger/red text color) **Note**: The required asterisk is smartly applied using role and data-slot detection. It excludes: * Elements with `role="group"`, `role="radiogroup"`, or `role="checkboxgroup"` * Elements with `data-slot="radio"` or `data-slot="checkbox"` This prevents duplicate asterisks when using group components with required fields. ## Examples ### With Required Indicator ```tsx <Label htmlFor="email" isRequired> Email Address </Label> <Input id="email" type="email" /> ``` ### With Disabled State ```tsx <Label htmlFor="username" isDisabled> Username </Label> <Input id="username" isDisabled /> ``` ### With Invalid State ```tsx <Label htmlFor="password" isInvalid> Password </Label> <Input id="password" isInvalid /> ``` </page> <page url="/docs/react/components/number-field"> # NumberField **Category**: react **URL**: https://v3.heroui.com/docs/react/components/number-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/number-field.mdx > Number input fields with increment/decrement buttons, validation, and internationalized formatting ## Import ```tsx import { NumberField } from '@heroui/react'; ``` ### Usage ```tsx import {Label, NumberField} from "@heroui/react"; export function Basic() { return ( <NumberField className="w-full max-w-64" defaultValue={1024} minValue={0} name="width"> <Label>Width</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> ); } ``` ### Anatomy ```tsx import {NumberField, Label, Description, FieldError} from '@heroui/react'; export default () => ( <NumberField> <Label /> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input /> <NumberField.IncrementButton /> </NumberField.Group> <Description /> <FieldError /> </NumberField> ) ``` > **NumberField** allows users to enter numeric values with optional increment/decrement buttons. It supports internationalized formatting, validation, and keyboard navigation. ### With Description ```tsx import {Description, Label, NumberField} from "@heroui/react"; export function WithDescription() { return ( <div className="flex w-full max-w-64 flex-col gap-4"> <NumberField defaultValue={1024} minValue={0} name="width"> <Label>Width</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Enter the width in pixels</Description> </NumberField> <NumberField defaultValue={0.5} formatOptions={{style: "percent"}} maxValue={1} minValue={0} name="percentage" step={0.1} > <Label>Percentage</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Value must be between 0 and 100</Description> </NumberField> </div> ); } ``` ### Required Field ```tsx import {Description, Label, NumberField} from "@heroui/react"; export function Required() { return ( <div className="flex w-full max-w-64 flex-col gap-4"> <NumberField isRequired minValue={0} name="quantity"> <Label>Quantity</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> <NumberField isRequired defaultValue={1} maxValue={10} minValue={1} name="rating"> <Label>Rating</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Rate from 1 to 10</Description> </NumberField> </div> ); } ``` ### Validation Use `isInvalid` together with `FieldError` to surface validation messages. ```tsx import {FieldError, Label, NumberField} from "@heroui/react"; export function Validation() { return ( <div className="flex w-full max-w-64 flex-col gap-4"> <NumberField isInvalid isRequired minValue={0} name="quantity" value={-5}> <Label>Quantity</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <FieldError>Quantity must be greater than or equal to 0</FieldError> </NumberField> <NumberField isInvalid formatOptions={{style: "percent"}} maxValue={1} minValue={0} name="percentage" step={0.1} value={1.5} > <Label>Percentage</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <FieldError>Percentage must be between 0 and 100</FieldError> </NumberField> </div> ); } ``` ### Controlled Control the value to synchronize with other components or perform custom formatting. ```tsx "use client"; import {Button, Description, Label, NumberField} from "@heroui/react"; import React from "react"; export function Controlled() { const [value, setValue] = React.useState(1024); return ( <div className="flex w-full max-w-64 flex-col gap-4"> <NumberField minValue={0} name="width" value={value} onChange={setValue}> <Label>Width</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Current value: {value}</Description> </NumberField> <div className="flex gap-2"> <Button variant="tertiary" onPress={() => setValue(0)}> Reset to 0 </Button> <Button variant="tertiary" onPress={() => setValue(2048)}> Set to 2048 </Button> </div> </div> ); } ``` ### With Validation Implement custom validation logic with controlled values. ```tsx "use client"; import {Description, FieldError, Label, NumberField} from "@heroui/react"; import React from "react"; export function WithValidation() { const [value, setValue] = React.useState<number | undefined>(undefined); const isInvalid = value !== undefined && (value < 0 || value > 100); return ( <div className="flex w-full max-w-64 flex-col gap-4"> <NumberField isRequired formatOptions={{style: "percent"}} isInvalid={isInvalid} maxValue={1} minValue={0} name="percentage" step={0.1} value={value} onChange={setValue} > <Label>Percentage</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> {isInvalid ? ( <FieldError>Percentage must be between 0 and 100</FieldError> ) : ( <Description>Enter a value between 0 and 100</Description> )} </NumberField> </div> ); } ``` ### Step Values Configure increment/decrement step values for precise control. ```tsx import {Description, Label, NumberField} from "@heroui/react"; export function WithStep() { return ( <div className="flex w-full max-w-64 flex-col gap-4"> <NumberField defaultValue={0} maxValue={100} minValue={0} name="step1" step={1}> <Label>Step: 1</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Increments by 1</Description> </NumberField> <NumberField defaultValue={0} maxValue={100} minValue={0} name="step5" step={5}> <Label>Step: 5</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Increments by 5</Description> </NumberField> <NumberField defaultValue={0} maxValue={100} minValue={0} name="step10" step={10}> <Label>Step: 10</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Increments by 10</Description> </NumberField> </div> ); } ``` ### Format Options Format numbers as currency, percentages, decimals, or units with internationalization support. ```tsx import {Description, Label, NumberField} from "@heroui/react"; export function WithFormatOptions() { return ( <div className="flex w-full max-w-64 flex-col gap-4"> <NumberField defaultValue={99} minValue={0} name="currency-eur" formatOptions={{ currency: "EUR", currencySign: "accounting", style: "currency", }} > <Label>Currency (EUR - Accounting)</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Accounting format with EUR currency</Description> </NumberField> <NumberField defaultValue={99.99} minValue={0} name="currency-usd" formatOptions={{ currency: "USD", style: "currency", }} > <Label>Currency (USD)</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Standard USD currency format</Description> </NumberField> <NumberField defaultValue={0.5} formatOptions={{style: "percent"}} maxValue={1} minValue={0} name="percentage" step={0.01} > <Label>Percentage</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Percentage format (0-1, where 0.5 = 50%)</Description> </NumberField> <NumberField defaultValue={1234.56} minValue={0} name="decimal" formatOptions={{ maximumFractionDigits: 2, minimumFractionDigits: 2, style: "decimal", }} > <Label>Decimal (2 decimal places)</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Decimal format with 2 decimal places</Description> </NumberField> <NumberField defaultValue={1000} minValue={0} name="unit" formatOptions={{ style: "unit", unit: "kilogram", unitDisplay: "short", }} > <Label>Unit (Kilograms)</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Unit format with kilograms</Description> </NumberField> </div> ); } ``` ### Custom Icons Customize the increment and decrement button icons. ```tsx import {Description, Label, NumberField} from "@heroui/react"; export function CustomIcons() { return ( <div className="flex w-full max-w-64 flex-col gap-4"> <NumberField defaultValue={1024} minValue={0} name="width"> <Label>Width (Custom Icons)</Label> <NumberField.Group> <NumberField.DecrementButton> <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg"> <path clipRule="evenodd" d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m-2-6.5a.75.75 0 0 0 0 1.5h4a.75.75 0 0 0 0-1.5z" fill="currentColor" fillRule="evenodd" /> </svg> </NumberField.DecrementButton> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton> <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg"> <path clipRule="evenodd" d="M6.75 11a4.25 4.25 0 1 0 0-8.5a4.25 4.25 0 0 0 0 8.5m0 1.5a5.73 5.73 0 0 0 3.501-1.188l2.719 2.718a.75.75 0 1 0 1.06-1.06l-2.718-2.719A5.75 5.75 0 1 0 6.75 12.5m.75-7.75a.75.75 0 0 0-1.5 0V6H4.75a.75.75 0 0 0 0 1.5H6v1.25a.75.75 0 0 0 1.5 0V7.5h1.25a.75.75 0 0 0 0-1.5H7.5z" fill="currentColor" fillRule="evenodd" /> </svg> </NumberField.IncrementButton> </NumberField.Group> <Description>Custom icon children</Description> </NumberField> </div> ); } ``` ### With Chevrons Use chevron icons in a vertical layout for a different visual style. ```tsx import {Label, NumberField} from "@heroui/react"; export function WithChevrons() { return ( <NumberField className="w-full max-w-64" defaultValue={99} minValue={0} name="amount" formatOptions={{ currency: "EUR", currencySign: "accounting", style: "currency", }} > <Label>Number field with chevrons</Label> <NumberField.Group> <NumberField.Input /> <div className="flex h-[calc(100%+2px)] flex-col border-l border-field-placeholder/15"> <NumberField.IncrementButton className="-ml-px flex h-1/2 w-6 flex-1 rounded-none border-r-0 border-l-0 pt-0.5 text-sm"> <svg aria-hidden="true" height="11" viewBox="0 0 16 16" width="11" xmlns="http://www.w3.org/2000/svg" > <path clipRule="evenodd" d="M13.03 10.53a.75.75 0 0 1-1.06 0L8 6.56l-3.97 3.97a.75.75 0 1 1-1.06-1.06l4.5-4.5a.75.75 0 0 1 1.06 0l4.5 4.5a.75.75 0 0 1 0 1.06" fill="currentColor" fillRule="evenodd" /> </svg> </NumberField.IncrementButton> <NumberField.DecrementButton className="-ml-px flex h-1/2 w-6 flex-1 rounded-none border-r-0 border-l-0 pb-0.5 text-sm"> <svg aria-hidden="true" height="11" viewBox="0 0 16 16" width="11" xmlns="http://www.w3.org/2000/svg" > <path clipRule="evenodd" d="M2.97 5.47a.75.75 0 0 1 1.06 0L8 9.44l3.97-3.97a.75.75 0 1 1 1.06 1.06l-4.5 4.5a.75.75 0 0 1-1.06 0l-4.5-4.5a.75.75 0 0 1 0-1.06" fill="currentColor" fillRule="evenodd" /> </svg> </NumberField.DecrementButton> </div> </NumberField.Group> </NumberField> ); } ``` ### Disabled State ```tsx import {Description, Label, NumberField} from "@heroui/react"; export function Disabled() { return ( <div className="flex w-full max-w-64 flex-col gap-4"> <NumberField isDisabled defaultValue={1024} minValue={0} name="width"> <Label>Width</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Enter the width in pixels</Description> </NumberField> <NumberField isDisabled defaultValue={0.5} formatOptions={{style: "percent"}} maxValue={1} minValue={0} name="percentage" step={0.1} > <Label>Percentage</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Value must be between 0 and 100</Description> </NumberField> </div> ); } ``` ### Full Width ```tsx import {Label, NumberField} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <NumberField fullWidth defaultValue={1024} minValue={0} name="width"> <Label>Width</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> </div> ); } ``` ### Variants The NumberField component supports two visual variants: * **`primary`** (default) - Standard styling with shadow, suitable for most use cases * **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components ```tsx import {Label, NumberField} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-4"> <NumberField defaultValue={100} minValue={0} name="primary-width" variant="primary"> <Label>Primary variant</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> <NumberField defaultValue={100} minValue={0} name="secondary-width" variant="secondary"> <Label>Secondary variant</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx import {Description, Label, NumberField, Surface} from "@heroui/react"; export function OnSurface() { return ( <Surface className="flex w-full max-w-[280px] flex-col gap-4 rounded-3xl p-6"> <NumberField defaultValue={1024} minValue={0} name="width" variant="secondary"> <Label>Width</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-full" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Enter the width in pixels</Description> </NumberField> <NumberField defaultValue={0.5} formatOptions={{style: "percent"}} maxValue={1} minValue={0} name="percentage" step={0.1} variant="secondary" > <Label>Percentage</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-full" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Value must be between 0 and 100</Description> </NumberField> </Surface> ); } ``` ### Form Example Complete form integration with validation and submission handling. ```tsx "use client"; import {Button, Description, FieldError, Form, Label, NumberField, Spinner} from "@heroui/react"; import React from "react"; export function FormExample() { const [value, setValue] = React.useState<number | undefined>(undefined); const [isSubmitting, setIsSubmitting] = React.useState(false); const STOCK_AVAILABLE = 3; const isOutOfStock = value !== undefined && value > STOCK_AVAILABLE; const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); if (value === undefined || value === null || value < 1 || value > STOCK_AVAILABLE) { return; } setIsSubmitting(true); // Simulate API call setTimeout(() => { console.log("Order submitted:", {quantity: value}); setValue(undefined); setIsSubmitting(false); }, 1500); }; return ( <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}> <NumberField isRequired isInvalid={isOutOfStock} maxValue={5} minValue={1} name="quantity" value={value} onChange={setValue} > <Label>Order quantity</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> {isOutOfStock ? ( <FieldError>Only {STOCK_AVAILABLE} items left in stock</FieldError> ) : ( <Description>Only {STOCK_AVAILABLE} items available</Description> )} </NumberField> <Button className="w-full" isDisabled={value === undefined || value < 1 || value > STOCK_AVAILABLE} isPending={isSubmitting} type="submit" variant="primary" > {isSubmitting ? ( <> <Spinner color="current" size="sm" /> Processing... </> ) : ( "Place Order" )} </Button> </Form> ); } ``` ## Related Components * **Label**: Accessible label for form controls * **Description**: Helper text for form fields * **FieldError**: Inline validation messages for form fields ### Custom Render Function ```tsx "use client"; import {Label, NumberField} from "@heroui/react"; export function CustomRenderFunction() { return ( <NumberField className="w-full max-w-64" defaultValue={1024} minValue={0} name="width" render={(props) => <div {...props} data-custom="foo" />} > <Label>Width</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import {NumberField, Label} from '@heroui/react'; function CustomNumberField() { return ( <NumberField className="gap-2"> <Label className="text-sm font-semibold">Quantity</Label> <NumberField.Group className="rounded-xl border-2"> <NumberField.DecrementButton className="bg-gray-100" /> <NumberField.Input className="text-center font-bold" /> <NumberField.IncrementButton className="bg-gray-100" /> </NumberField.Group> </NumberField> ); } ``` ### Customizing the component classes NumberField uses CSS classes that can be customized. Override the component classes to match your design system. ```css @layer components { .number-field { @apply flex flex-col gap-1; } /* When invalid, the description is hidden automatically */ .number-field[data-invalid="true"] [data-slot="description"], .number-field[aria-invalid="true"] [data-slot="description"] { @apply hidden; } .number-field__group { @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border; } .number-field__input { @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 tabular-nums; } .number-field__increment-button, .number-field__decrement-button { @apply flex h-full w-10 items-center justify-center rounded-none bg-transparent; } } ``` ### CSS Classes * `.number-field` – Root container with minimal styling (`flex flex-col gap-1`) * `.number-field__group` – Container for input and buttons with border and background styling * `.number-field__input` – The numeric input field * `.number-field__increment-button` – Button to increment the value * `.number-field__decrement-button` – Button to decrement the value * `.number-field--primary` – Primary variant with shadow (default) * `.number-field--secondary` – Secondary variant without shadow, suitable for use in surfaces > **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. ### Interactive States NumberField automatically manages these data attributes based on its state: * **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid * **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true * **Focus Within**: `[data-focus-within="true"]` - Applied when the input or buttons are focused * **Focus Visible**: `[data-focus-visible="true"]` - Applied when focus is visible (keyboard navigation) * **Hovered**: `[data-hovered="true"]` - Applied when hovering over buttons Additional attributes are available through render props (see NumberFieldRenderProps below). ## API Reference ### NumberField Props NumberField inherits all props from React Aria's [NumberField](https://react-spectrum.adobe.com/react-aria/NumberField.html) component. #### Base Props | Prop | Type | Default | Description | | ----------- | -------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `children` | `React.ReactNode \| (values: NumberFieldRenderProps) => React.ReactNode` | - | Child components (Label, Group, Input, etc.) or render function. | | `className` | `string \| (values: NumberFieldRenderProps) => string` | - | CSS classes for styling, supports render props. | | `style` | `React.CSSProperties \| (values: NumberFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. | | `fullWidth` | `boolean` | `false` | Whether the number field should take full width of its container | | `id` | `string` | - | The element's unique identifier. | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, NumberFieldRenderProps>` | - | Overrides the default DOM element with a custom render function. | #### Value Props | Prop | Type | Default | Description | | -------------- | -------------------------------------- | ------- | -------------------------------------- | | `value` | `number` | - | Current value (controlled). | | `defaultValue` | `number` | - | Default value (uncontrolled). | | `onChange` | `(value: number \| undefined) => void` | - | Handler called when the value changes. | #### Formatting Props | Prop | Type | Default | Description | | --------------- | -------------------------- | ------- | ------------------------------------------------------------------ | | `formatOptions` | `Intl.NumberFormatOptions` | - | Options for formatting numbers (currency, percent, decimal, unit). | | `locale` | `string` | - | Locale for number formatting. | #### Validation Props | Prop | Type | Default | Description | | -------------------- | ----------------------------------------------------------------- | ---------- | -------------------------------------------------------------- | | `isRequired` | `boolean` | `false` | Whether user input is required before form submission. | | `isInvalid` | `boolean` | - | Whether the value is invalid. | | `validate` | `(value: number) => ValidationError \| true \| null \| undefined` | - | Custom validation function. | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. | | `validationErrors` | `string[]` | - | Server-side validation errors. | #### Range Props | Prop | Type | Default | Description | | ---------- | -------- | ------- | ---------------------------------------------- | | `minValue` | `number` | - | Minimum allowed value. | | `maxValue` | `number` | - | Maximum allowed value. | | `step` | `number` | `1` | Step value for increment/decrement operations. | #### State Props | 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. | | `autoFocus` | `boolean` | - | Whether the element should receive focus on render. | #### Accessibility Props | Prop | Type | Default | Description | | ------------------ | -------- | ------- | ----------------------------------------------------- | | `aria-label` | `string` | - | Accessibility label when no visible label is present. | | `aria-labelledby` | `string` | - | ID of elements that label this field. | | `aria-describedby` | `string` | - | ID of elements that describe this field. | | `aria-details` | `string` | - | ID of elements with additional details. | ### Composition Components NumberField works with these separate components that should be imported and used directly: * **NumberField.Group** - Container for input and buttons * **NumberField.Input** - The numeric input field * **NumberField.IncrementButton** - Button to increment the value * **NumberField.DecrementButton** - Button to decrement the value * **Label** - Field label component from `@heroui/react` * **Description** - Helper text component from `@heroui/react` * **FieldError** - Validation error message from `@heroui/react` Each of these components has its own props API. Use them directly within NumberField for composition: ```tsx <NumberField isRequired isInvalid={hasError} minValue={0} maxValue={100}> <Label>Quantity</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input /> <NumberField.IncrementButton /> </NumberField.Group> <Description>Enter a value between 0 and 100</Description> <FieldError>Value must be between 0 and 100</FieldError> </NumberField> ``` #### NumberField.Group Props NumberField.Group inherits props from React Aria's [Group](https://react-spectrum.adobe.com/react-aria/Group.html) component. | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------------ | ------- | ----------------------------------------------------- | | `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | Child components (Input, Buttons) or render function. | | `className` | `string \| (values: GroupRenderProps) => string` | - | CSS classes for styling. | #### NumberField.Input Props NumberField.Input inherits props from React Aria's [Input](https://react-spectrum.adobe.com/react-aria/Input.html) component. | Prop | Type | Default | Description | | ----------- | -------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `className` | `string` | - | CSS classes for styling. | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | #### NumberField.IncrementButton Props NumberField.IncrementButton inherits props from React Aria's [Button](https://react-spectrum.adobe.com/react-aria/Button.html) component. | Prop | Type | Default | Description | | ----------- | ----------------- | -------------- | ------------------------------------------------------ | | `children` | `React.ReactNode` | `<IconPlus />` | Icon or content for the button. Defaults to plus icon. | | `className` | `string` | - | CSS classes for styling. | | `slot` | `"increment"` | `"increment"` | Must be set to "increment" (automatically set). | #### NumberField.DecrementButton Props NumberField.DecrementButton inherits props from React Aria's [Button](https://react-spectrum.adobe.com/react-aria/Button.html) component. | Prop | Type | Default | Description | | ----------- | ----------------- | --------------- | ------------------------------------------------------- | | `children` | `React.ReactNode` | `<IconMinus />` | Icon or content for the button. Defaults to minus icon. | | `className` | `string` | - | CSS classes for styling. | | `slot` | `"decrement"` | `"decrement"` | Must be set to "decrement" (automatically set). | ### NumberFieldRenderProps When using render props with `className`, `style`, or `children`, these values are available: | Prop | Type | Description | | ---------------- | --------------------- | -------------------------------------------------------------------------- | | `isDisabled` | `boolean` | Whether the field is disabled. | | `isInvalid` | `boolean` | Whether the field is currently invalid. | | `isReadOnly` | `boolean` | Whether the field is read-only. | | `isRequired` | `boolean` | Whether the field is required. | | `isFocused` | `boolean` | Whether the field is currently focused (DEPRECATED - use `isFocusWithin`). | | `isFocusWithin` | `boolean` | Whether any child element is focused. | | `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). | | `value` | `number \| undefined` | Current value. | | `minValue` | `number \| undefined` | Minimum allowed value. | | `maxValue` | `number \| undefined` | Maximum allowed value. | | `step` | `number` | Step value for increment/decrement. | </page> <page url="/docs/react/components/radio-group"> # RadioGroup **Category**: react **URL**: https://v3.heroui.com/docs/react/components/radio-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/radio-group.mdx > Radio group for selecting a single option from a list ## Import ```tsx import { RadioGroup, Radio } from '@heroui/react'; ``` ### Usage ```tsx import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function Basic() { return ( <RadioGroup defaultValue="premium" name="plan"> <Label>Plan selection</Label> <Description>Choose the plan that suits you best</Description> <Radio value="basic"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Basic Plan</Label> <Description>Includes 100 messages per month</Description> </Radio.Content> </Radio> <Radio value="premium"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Premium Plan</Label> <Description>Includes 200 messages per month</Description> </Radio.Content> </Radio> <Radio value="business"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Business Plan</Label> <Description>Unlimited messages</Description> </Radio.Content> </Radio> </RadioGroup> ); } ``` ### Anatomy Import the RadioGroup component and access all parts using dot notation. ```tsx import {RadioGroup, Radio, Label, Description, FieldError} from '@heroui/react'; export default () => ( <RadioGroup> <Label /> <Description /> <Radio value="option1"> <Radio.Control> <Radio.Indicator> <span>✓</span> {/* Custom indicator (optional) */} </Radio.Indicator> </Radio.Control> <Radio.Content> <Label /> <Description /> </Radio.Content> </Radio> <FieldError /> </RadioGroup> ) ``` ### Custom Indicator ```tsx "use client"; import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function CustomIndicator() { return ( <RadioGroup defaultValue="premium" name="plan-custom-indicator"> <Label>Plan selection</Label> <Description>Choose the plan that suits you best</Description> <Radio value="basic"> <Radio.Control> <Radio.Indicator> {({isSelected}) => isSelected ? <span className="text-xs leading-none text-background">✓</span> : null } </Radio.Indicator> </Radio.Control> <Radio.Content> <Label>Basic Plan</Label> <Description>Includes 100 messages per month</Description> </Radio.Content> </Radio> <Radio value="premium"> <Radio.Control> <Radio.Indicator> {({isSelected}) => isSelected ? <span className="text-xs leading-none text-background">✓</span> : null } </Radio.Indicator> </Radio.Control> <Radio.Content> <Label>Premium Plan</Label> <Description>Includes 200 messages per month</Description> </Radio.Content> </Radio> <Radio value="business"> <Radio.Control> <Radio.Indicator> {({isSelected}) => isSelected ? <span className="text-xs leading-none text-background">✓</span> : null } </Radio.Indicator> </Radio.Control> <Radio.Content> <Label>Business Plan</Label> <Description>Unlimited messages</Description> </Radio.Content> </Radio> </RadioGroup> ); } ``` ### Horizontal Orientation ```tsx import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function Horizontal() { return ( <div className="flex flex-col gap-4"> <Label>Subscription plan</Label> <RadioGroup defaultValue="pro" name="plan-orientation" orientation="horizontal"> <Radio value="starter"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Starter</Label> <Description>For side projects</Description> </Radio.Content> </Radio> <Radio value="pro"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Pro</Label> <Description>Advanced reporting</Description> </Radio.Content> </Radio> <Radio value="teams"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Teams</Label> <Description>Up to 10 teammates</Description> </Radio.Content> </Radio> </RadioGroup> </div> ); } ``` ### Controlled ```tsx "use client"; import {Description, Label, Radio, RadioGroup} from "@heroui/react"; import React from "react"; export function Controlled() { const [value, setValue] = React.useState("pro"); return ( <div className="flex flex-col gap-4"> <RadioGroup name="plan-controlled" value={value} onChange={setValue}> <Label>Subscription plan</Label> <Radio value="starter"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Starter</Label> <Description>For side projects and small teams</Description> </Radio.Content> </Radio> <Radio value="pro"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Pro</Label> <Description>Advanced reporting and analytics</Description> </Radio.Content> </Radio> <Radio value="teams"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Teams</Label> <Description>Share access with up to 10 teammates</Description> </Radio.Content> </Radio> </RadioGroup> <p className="text-sm text-muted"> Selected plan: <span className="font-medium">{value}</span> </p> </div> ); } ``` ### Uncontrolled Combine `defaultValue` with `onChange` when you only need to react to updates. ```tsx "use client"; import {Description, Label, Radio, RadioGroup} from "@heroui/react"; import React from "react"; export function Uncontrolled() { const [selection, setSelection] = React.useState("pro"); return ( <div className="flex flex-col gap-4"> <RadioGroup defaultValue="pro" name="plan-uncontrolled" onChange={(nextValue) => setSelection(nextValue)} > <Label>Subscription plan</Label> <Radio value="starter"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Starter</Label> <Description>For side projects and small teams</Description> </Radio.Content> </Radio> <Radio value="pro"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Pro</Label> <Description>Advanced reporting and analytics</Description> </Radio.Content> </Radio> <Radio value="teams"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Teams</Label> <Description>Share access with up to 10 teammates</Description> </Radio.Content> </Radio> </RadioGroup> <p className="text-sm text-muted"> Last chosen plan: <span className="font-medium">{selection}</span> </p> </div> ); } ``` ### Validation ```tsx "use client"; import {Button, Description, FieldError, Form, Label, Radio, RadioGroup} from "@heroui/react"; import React from "react"; export function Validation() { const [message, setMessage] = React.useState<string | null>(null); return ( <Form className="flex flex-col gap-4" onSubmit={(e) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const value = formData.get("plan-validation"); setMessage(`Your chosen plan is: ${value}`); }} > <RadioGroup isRequired name="plan-validation"> <Label>Subscription plan</Label> <Radio value="starter"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Starter</Label> <Description>For side projects and small teams</Description> </Radio.Content> </Radio> <Radio value="pro"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Pro</Label> <Description>Advanced reporting and analytics</Description> </Radio.Content> </Radio> <Radio value="teams"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Teams</Label> <Description>Share access with up to 10 teammates</Description> </Radio.Content> </Radio> <FieldError>Choose a subscription before continuing.</FieldError> </RadioGroup> <Button className="mt-2 w-fit" type="submit"> Submit </Button> {!!message && <p className="text-sm text-muted">{message}</p>} </Form> ); } ``` ### Disabled ```tsx import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function Disabled() { return ( <RadioGroup isDisabled defaultValue="pro" name="plan-disabled"> <Label>Subscription plan</Label> <Description>Plan changes are temporarily paused while we roll out updates.</Description> <Radio value="starter"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Starter</Label> <Description>For side projects and small teams</Description> </Radio.Content> </Radio> <Radio value="pro"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Pro</Label> <Description>Advanced reporting and analytics</Description> </Radio.Content> </Radio> <Radio value="teams"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Teams</Label> <Description>Share access with up to 10 teammates</Description> </Radio.Content> </Radio> </RadioGroup> ); } ``` ### Variants The RadioGroup component supports two visual variants: * **`primary`** (default) - Standard styling with default background, suitable for most use cases * **`secondary`** - Lower emphasis variant, suitable for use in Surface components ```tsx import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-8"> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Primary variant</p> <RadioGroup defaultValue="option1" name="primary-plan" variant="primary"> <Radio value="option1"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Option 1</Label> <Description>Standard styling with default background</Description> </Radio.Content> </Radio> <Radio value="option2"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Option 2</Label> <Description>Another option with primary styling</Description> </Radio.Content> </Radio> </RadioGroup> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Secondary variant</p> <RadioGroup defaultValue="option1" name="secondary-plan" variant="secondary"> <Radio value="option1"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Option 1</Label> <Description>Lower emphasis variant for use in surfaces</Description> </Radio.Content> </Radio> <Radio value="option2"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Option 2</Label> <Description>Another option with secondary styling</Description> </Radio.Content> </Radio> </RadioGroup> </div> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx import {Description, Label, Radio, RadioGroup, Surface} from "@heroui/react"; export function OnSurface() { return ( <Surface className="w-full rounded-3xl p-6"> <RadioGroup defaultValue="premium" name="plan" variant="secondary"> <Label>Plan selection</Label> <Description>Choose the plan that suits you best</Description> <Radio value="basic"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Basic Plan</Label> <Description>Includes 100 messages per month</Description> </Radio.Content> </Radio> <Radio value="premium"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Premium Plan</Label> <Description>Includes 200 messages per month</Description> </Radio.Content> </Radio> <Radio value="business"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Business Plan</Label> <Description>Unlimited messages</Description> </Radio.Content> </Radio> </RadioGroup> </Surface> ); } ``` ### Delivery & Payment ## Related Components * **Fieldset**: Group related form controls with legends * **Surface**: Base container surface * **Description**: Helper text for form fields ### Custom Render Function ```tsx "use client"; import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function CustomRenderFunction() { return ( <RadioGroup defaultValue="premium" name="plan" render={(props) => <div {...props} data-custom="foo" />} > <Label>Plan selection</Label> <Description>Choose the plan that suits you best</Description> <Radio value="basic"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Basic Plan</Label> <Description>Includes 100 messages per month</Description> </Radio.Content> </Radio> <Radio value="premium"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Premium Plan</Label> <Description>Includes 200 messages per month</Description> </Radio.Content> </Radio> <Radio value="business"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Radio.Content> <Label>Business Plan</Label> <Description>Unlimited messages</Description> </Radio.Content> </Radio> </RadioGroup> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import { RadioGroup, Radio } from '@heroui/react'; export default () => ( <RadioGroup defaultValue="premium" name="plan"> <Radio className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-blue-300 data-[selected=true]:border-blue-500 data-[selected=true]:bg-blue-500/10" value="basic" > <Radio.Indicator className="border-border border-2 group-hover:border-blue-400 group-data-[selected=true]:border-blue-500 group-data-[selected=true]:bg-blue-500" /> Basic Plan </Radio> <Radio className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-purple-300 data-[selected=true]:border-purple-500 data-[selected=true]:bg-purple-500/10" value="premium" > <Radio.Indicator className="border-border border-2 group-hover:border-purple-400 group-data-[selected=true]:border-purple-500 group-data-[selected=true]:bg-purple-500" /> Premium Plan </Radio> <Radio className="border-border group cursor-pointer rounded-xl border-2 p-4 hover:border-emerald-300 data-[selected=true]:border-emerald-500 data-[selected=true]:bg-emerald-500/10" value="business" > <Radio.Indicator className="border-border border-2 group-hover:border-emerald-400 group-data-[selected=true]:border-emerald-500 group-data-[selected=true]:bg-emerald-500" /> Business Plan </Radio> </RadioGroup> ); ``` ### Customizing the component classes To customize the RadioGroup component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .radio-group { @apply gap-2; } .radio { @apply gap-4 rounded-lg border border-border p-3 hover:bg-surface-hovered; } .radio__control { @apply border-2 border-primary; } .radio__indicator { @apply bg-primary; } .radio__content { @apply gap-1; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The RadioGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/radio-group.css)): #### Base Classes * `.radio-group` - Base radio group container * `.radio` - Individual radio item * `.radio__control` - Radio control (circular button) * `.radio__indicator` - Radio indicator (inner dot) * `.radio__content` - Radio content wrapper #### Modifier Classes * `.radio--disabled` - Disabled radio state ### Interactive States The radio supports both CSS pseudo-classes and data attributes for flexibility: * **Selected**: `[aria-checked="true"]` or `[data-selected="true"]` (indicator appears) * **Hover**: `:hover` or `[data-hovered="true"]` (border color changes) * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` (shows focus ring) * **Pressed**: `:active` or `[data-pressed="true"]` (scale transform) * **Disabled**: `:disabled` or `[aria-disabled="true"]` (reduced opacity, no pointer events) * **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` (error border color) ## API Reference ### RadioGroup Props | Prop | Type | Default | Description | | -------------- | ----------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `value` | `string` | - | The current value (controlled) | | `defaultValue` | `string` | - | The default value (uncontrolled) | | `onChange` | `(value: string) => void` | - | Handler called when the value changes | | `isDisabled` | `boolean` | `false` | Whether the radio group is disabled | | `isRequired` | `boolean` | `false` | Whether the radio group is required | | `isReadOnly` | `boolean` | `false` | Whether the radio group is read only | | `isInvalid` | `boolean` | `false` | Whether the radio group is in an invalid state | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | | `name` | `string` | - | The name of the radio group, used when submitting an HTML form | | `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | The orientation of the radio group | | `children` | `React.ReactNode \| (values: RadioGroupRenderProps) => React.ReactNode` | - | Radio group content or render prop | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, RadioGroupRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Radio Props | Prop | Type | Default | Description | | ------------ | ------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------- | | `value` | `string` | - | The value of the radio button | | `isDisabled` | `boolean` | `false` | Whether the radio button is disabled | | `name` | `string` | - | The name of the radio button, used when submitting an HTML form | | `children` | `React.ReactNode \| (values: RadioRenderProps) => React.ReactNode` | - | Radio content or render prop | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, RadioRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Radio.Control Props Extends `React.HTMLAttributes<HTMLSpanElement>`. | Prop | Type | Default | Description | | ---------- | ----------------- | ------- | ---------------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | The content to render inside the control wrapper (typically Radio.Indicator) | ### Radio.Indicator Props Extends `React.HTMLAttributes<HTMLSpanElement>`. | Prop | Type | Default | Description | | ---------- | ------------------------------------------------------------------ | ------- | ---------------------------------------------------------------------- | | `children` | `React.ReactNode \| (values: RadioRenderProps) => React.ReactNode` | - | Optional content or render prop that receives the current radio state. | ### Radio.Content Props Extends `React.HTMLAttributes<HTMLDivElement>`. | Prop | Type | Default | Description | | ---------- | ----------------- | ------- | ---------------------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | The content to render inside the content wrapper (typically Label and Description) | ### RadioRenderProps When using the render prop pattern, these values are provided: | Prop | Type | Description | | ---------------- | --------- | ---------------------------------------- | | `isSelected` | `boolean` | Whether the radio is currently selected | | `isHovered` | `boolean` | Whether the radio is hovered | | `isPressed` | `boolean` | Whether the radio is currently pressed | | `isFocused` | `boolean` | Whether the radio is focused | | `isFocusVisible` | `boolean` | Whether the radio is keyboard focused | | `isDisabled` | `boolean` | Whether the radio is disabled | | `isReadOnly` | `boolean` | Whether the radio is read only | | `isInvalid` | `boolean` | Whether the radio is in an invalid state | </page> <page url="/docs/react/components/search-field"> # SearchField **Category**: react **URL**: https://v3.heroui.com/docs/react/components/search-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/search-field.mdx > Search input field with clear button and search icon ## Import ```tsx import { SearchField } from '@heroui/react'; ``` ### Usage ```tsx import {Label, SearchField} from "@heroui/react"; export function Basic() { return ( <SearchField name="search"> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> ); } ``` ### Anatomy ```tsx import {SearchField, Label, Description, FieldError} from '@heroui/react'; export default () => ( <SearchField> <Label /> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input /> <SearchField.ClearButton /> </SearchField.Group> <Description /> <FieldError /> </SearchField> ) ``` > **SearchField** allows users to enter and clear a search query. It includes a search icon and an optional clear button for easy reset. ### With Description ```tsx import {Description, Label, SearchField} from "@heroui/react"; export function WithDescription() { return ( <div className="flex flex-col gap-4"> <SearchField name="search"> <Label>Search products</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search products..." /> <SearchField.ClearButton /> </SearchField.Group> <Description>Enter keywords to search for products</Description> </SearchField> <SearchField name="search-users"> <Label>Search users</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search users..." /> <SearchField.ClearButton /> </SearchField.Group> <Description>Search by name, email, or username</Description> </SearchField> </div> ); } ``` ### Required Field ```tsx import {Description, Label, SearchField} from "@heroui/react"; export function Required() { return ( <div className="flex flex-col gap-4"> <SearchField isRequired name="search"> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <SearchField isRequired name="search-query"> <Label>Search query</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Enter search query..." /> <SearchField.ClearButton /> </SearchField.Group> <Description>Minimum 3 characters required</Description> </SearchField> </div> ); } ``` ### Validation Use `isInvalid` together with `FieldError` to surface validation messages. ```tsx import {FieldError, Label, SearchField} from "@heroui/react"; export function Validation() { return ( <div className="flex flex-col gap-4"> <SearchField isInvalid isRequired name="search" value="ab"> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> <FieldError>Search query must be at least 3 characters</FieldError> </SearchField> <SearchField isInvalid name="search-invalid"> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search..." value="invalid@query" /> <SearchField.ClearButton /> </SearchField.Group> <FieldError>Invalid characters in search query</FieldError> </SearchField> </div> ); } ``` ### Disabled State ```tsx import {Description, Label, SearchField} from "@heroui/react"; export function Disabled() { return ( <div className="flex flex-col gap-4"> <SearchField isDisabled name="search" value="Disabled search"> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> <Description>This search field is disabled</Description> </SearchField> <SearchField isDisabled name="search-empty"> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> <Description>This search field is disabled</Description> </SearchField> </div> ); } ``` ### Controlled Control the value to synchronize with other components or perform custom formatting. ```tsx "use client"; import {Button, Description, Label, SearchField} from "@heroui/react"; import React from "react"; export function Controlled() { const [value, setValue] = React.useState(""); return ( <div className="flex flex-col gap-4"> <SearchField name="search" value={value} onChange={setValue}> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> <Description>Current value: {value || "(empty)"}</Description> </SearchField> <div className="flex gap-2"> <Button variant="tertiary" onPress={() => setValue("")}> Clear </Button> <Button variant="tertiary" onPress={() => setValue("example query")}> Set example </Button> </div> </div> ); } ``` ### With Validation Implement custom validation logic with controlled values. ```tsx "use client"; import {Description, FieldError, Label, SearchField} from "@heroui/react"; import React from "react"; export function WithValidation() { const [value, setValue] = React.useState(""); const isInvalid = value.length > 0 && value.length < 3; return ( <div className="flex flex-col gap-4"> <SearchField isRequired isInvalid={isInvalid} name="search" value={value} onChange={setValue}> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> {isInvalid ? ( <FieldError>Search query must be at least 3 characters</FieldError> ) : ( <Description>Enter at least 3 characters to search</Description> )} </SearchField> </div> ); } ``` ### Custom Icons Customize the search icon and clear button icons. ```tsx import {Description, Label, SearchField} from "@heroui/react"; export function CustomIcons() { return ( <div className="flex flex-col gap-4"> <SearchField name="search-custom"> <Label>Search (Custom Icons)</Label> <SearchField.Group> <SearchField.SearchIcon> <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg"> <path clipRule="evenodd" d="M12.5 4c0 .174-.071.513-.885.888S9.538 5.5 8 5.5s-2.799-.237-3.615-.612C3.57 4.513 3.5 4.174 3.5 4s.071-.513.885-.888S6.462 2.5 8 2.5s2.799.237 3.615.612c.814.375.885.714.885.888m-1.448 2.66C10.158 6.888 9.115 7 8 7s-2.158-.113-3.052-.34l1.98 2.905c.21.308.322.672.322 1.044v3.37q.088.02.25.021c.422 0 .749-.14.95-.316c.185-.162.3-.38.3-.684v-2.39c0-.373.112-.737.322-1.045zM8 1c3.314 0 6 1 6 3a3.24 3.24 0 0 1-.563 1.826l-3.125 4.584a.35.35 0 0 0-.062.2V13c0 1.5-1.25 2.5-2.75 2.5s-1.75-1-1.75-1v-3.89a.35.35 0 0 0-.061-.2L2.563 5.826A3.24 3.24 0 0 1 2 4c0-2 2.686-3 6-3m-.88 12.936q-.015-.008-.013-.01z" fill="currentColor" fillRule="evenodd" /> </svg> </SearchField.SearchIcon> <SearchField.Input className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton> <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg"> <path clipRule="evenodd" d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14M6.53 5.47a.75.75 0 0 0-1.06 1.06L6.94 8L5.47 9.47a.75.75 0 1 0 1.06 1.06L8 9.06l1.47 1.47a.75.75 0 1 0 1.06-1.06L9.06 8l1.47-1.47a.75.75 0 1 0-1.06-1.06L8 6.94z" fill="currentColor" fillRule="evenodd" /> </svg> </SearchField.ClearButton> </SearchField.Group> <Description>Custom icon children</Description> </SearchField> </div> ); } ``` ### Full Width ```tsx import {Label, SearchField} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <SearchField fullWidth name="search"> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> </div> ); } ``` ### Variants The SearchField component supports two visual variants: * **`primary`** (default) - Standard styling with shadow, suitable for most use cases * **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components ```tsx import {Label, SearchField} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-4"> <SearchField name="primary-search" variant="primary"> <Label>Primary variant</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <SearchField name="secondary-search" variant="secondary"> <Label>Secondary variant</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx import {Description, Label, SearchField, Surface} from "@heroui/react"; export function OnSurface() { return ( <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6"> <SearchField name="search" variant="secondary"> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-full" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> <Description>Enter keywords to search</Description> </SearchField> <SearchField name="search-2" variant="secondary"> <Label>Advanced search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-full" placeholder="Advanced search..." /> <SearchField.ClearButton /> </SearchField.Group> <Description>Use filters to refine your search</Description> </SearchField> </Surface> ); } ``` ### Form Example Complete form integration with validation and submission handling. ```tsx "use client"; import {Button, Description, FieldError, Form, Label, SearchField, Spinner} from "@heroui/react"; import React from "react"; export function FormExample() { const [value, setValue] = React.useState(""); const [isSubmitting, setIsSubmitting] = React.useState(false); const MIN_LENGTH = 3; const isInvalid = value.length > 0 && value.length < MIN_LENGTH; const handleSubmit = (e: React.FormEvent) => { e.preventDefault(); if (value.length < MIN_LENGTH) { return; } setIsSubmitting(true); // Simulate API call setTimeout(() => { console.log("Search submitted:", {query: value}); setValue(""); setIsSubmitting(false); }, 1500); }; return ( <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}> <SearchField isRequired isInvalid={isInvalid} name="search" value={value} onChange={setValue}> <Label>Search products</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-full" placeholder="Search products..." /> <SearchField.ClearButton /> </SearchField.Group> {isInvalid ? ( <FieldError>Search query must be at least {MIN_LENGTH} characters</FieldError> ) : ( <Description>Enter at least {MIN_LENGTH} characters to search</Description> )} </SearchField> <Button className="w-full" isDisabled={value.length < MIN_LENGTH} isPending={isSubmitting} type="submit" variant="primary" > {isSubmitting ? ( <> <Spinner color="current" size="sm" /> Searching... </> ) : ( "Search" )} </Button> </Form> ); } ``` ### With Keyboard Shortcut Add keyboard shortcuts to quickly focus the search field. ```tsx "use client"; import {Description, Kbd, Label, SearchField} from "@heroui/react"; import React from "react"; export function WithKeyboardShortcut() { const inputRef = React.useRef<HTMLInputElement>(null); const [value, setValue] = React.useState(""); React.useEffect(() => { const handleKeyDown = (e: KeyboardEvent) => { // Check for Shift+S if (e.shiftKey && e.key === "S" && !e.metaKey && !e.ctrlKey && !e.altKey) { e.preventDefault(); inputRef.current?.focus(); } // Check for ESC key to blur the input if (e.key === "Escape" && document.activeElement === inputRef.current) { inputRef.current?.blur(); } }; // Add global event listener window.addEventListener("keydown", handleKeyDown); // Cleanup on unmount return () => { window.removeEventListener("keydown", handleKeyDown); }; }, []); return ( <div className="flex flex-col gap-4"> <div> <SearchField name="search" value={value} onChange={setValue}> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input ref={inputRef} className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> <Description>Use keyboard shortcut to quickly focus this field</Description> </SearchField> </div> <div className="text-default-500 flex items-center gap-2 text-sm"> <span>Press</span> <Kbd> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>S</Kbd.Content> </Kbd> <span>to focus the search field</span> </div> </div> ); } ``` ## Related Components * **Label**: Accessible label for form controls * **Description**: Helper text for form fields * **FieldError**: Inline validation messages for form fields ### Custom Render Function ```tsx "use client"; import {Label, SearchField} from "@heroui/react"; export function CustomRenderFunction() { return ( <SearchField name="search" render={(props) => <div {...props} data-custom="foo" />}> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import {SearchField, Label} from '@heroui/react'; function CustomSearchField() { return ( <SearchField className="gap-2"> <Label className="text-sm font-semibold">Search</Label> <SearchField.Group className="rounded-xl border-2"> <SearchField.SearchIcon className="text-blue-500" /> <SearchField.Input className="text-center font-bold" /> <SearchField.ClearButton className="text-red-500" /> </SearchField.Group> </SearchField> ); } ``` ### Customizing the component classes SearchField uses CSS classes that can be customized. Override the component classes to match your design system. ```css @layer components { .search-field { @apply flex flex-col gap-1; } /* When invalid, the description is hidden automatically */ .search-field[data-invalid], .search-field[aria-invalid] { [data-slot="description"] { @apply hidden; } } .search-field__group { @apply bg-field text-field-foreground shadow-field rounded-field inline-flex h-9 items-center overflow-hidden border; } .search-field__input { @apply flex-1 rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none; } .search-field__search-icon { @apply text-field-placeholder pointer-events-none shrink-0 ml-3 mr-0 size-4; } .search-field__clear-button { @apply mr-1 shrink-0; } } ``` ### CSS Classes * `.search-field` – Root container with minimal styling (`flex flex-col gap-1`) * `.search-field__group` – Container for search icon, input, and clear button with border and background styling * `.search-field__input` – The search input field * `.search-field__search-icon` – The search icon displayed on the left * `.search-field__clear-button` – Button to clear the search field * `.search-field--primary` – Primary variant with shadow (default) * `.search-field--secondary` – Secondary variant without shadow, suitable for use in surfaces > **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. ### Interactive States SearchField automatically manages these data attributes based on its state: * **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid * **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true * **Focus Within**: `[data-focus-within="true"]` - Applied when the input is focused * **Focus Visible**: `[data-focus-visible="true"]` - Applied when focus is visible (keyboard navigation) * **Hovered**: `[data-hovered="true"]` - Applied when hovering over the group * **Empty**: `[data-empty="true"]` - Applied when the field is empty (hides clear button) Additional attributes are available through render props (see SearchFieldRenderProps below). ## API Reference ### SearchField Props SearchField inherits all props from React Aria's [SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html) component. #### Base Props | Prop | Type | Default | Description | | ----------- | -------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `children` | `React.ReactNode \| (values: SearchFieldRenderProps) => React.ReactNode` | - | Child components (Label, Group, Input, etc.) or render function. | | `className` | `string \| (values: SearchFieldRenderProps) => string` | - | CSS classes for styling, supports render props. | | `style` | `React.CSSProperties \| (values: SearchFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. | | `fullWidth` | `boolean` | `false` | Whether the search field should take full width of its container | | `id` | `string` | - | The element's unique identifier. | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SearchFieldRenderProps>` | - | Overrides the default DOM element with a custom render function. | #### Value Props | Prop | Type | Default | Description | | -------------- | ------------------------- | ------- | -------------------------------------- | | `value` | `string` | - | Current value (controlled). | | `defaultValue` | `string` | - | Default value (uncontrolled). | | `onChange` | `(value: string) => void` | - | Handler called when the value changes. | #### Validation Props | Prop | Type | Default | Description | | -------------------- | ----------------------------------------------------------------- | ---------- | -------------------------------------------------------------- | | `isRequired` | `boolean` | `false` | Whether user input is required before form submission. | | `isInvalid` | `boolean` | - | Whether the value is invalid. | | `validate` | `(value: string) => ValidationError \| true \| null \| undefined` | - | Custom validation function. | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. | | `validationErrors` | `string[]` | - | Server-side validation errors. | #### State Props | 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. | | `autoFocus` | `boolean` | - | Whether the element should receive focus on render. | #### Event Props | Prop | Type | Default | Description | | ---------- | ------------------------- | ------- | ------------------------------------------------------------ | | `onSubmit` | `(value: string) => void` | - | Handler called when the user submits the search (Enter key). | | `onClear` | `() => void` | - | Handler called when the clear button is pressed. | #### Accessibility Props | 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 SearchField works with these separate components that should be imported and used directly: * **SearchField.Group** - Container for search icon, input, and clear button * **SearchField.Input** - The search input field * **SearchField.SearchIcon** - The search icon displayed on the left * **SearchField.ClearButton** - Button to clear the search field * **Label** - Field label component from `@heroui/react` * **Description** - Helper text component from `@heroui/react` * **FieldError** - Validation error message from `@heroui/react` Each of these components has its own props API. Use them directly within SearchField for composition: ```tsx <SearchField isRequired isInvalid={hasError} value={value} onChange={setValue}> <Label>Search</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> <Description>Enter keywords to search</Description> <FieldError>Search query is required</FieldError> </SearchField> ``` #### SearchField.Group Props SearchField.Group inherits props from React Aria's [Group](https://react-spectrum.adobe.com/react-aria/Group.html) component. | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------------ | ------- | --------------------------------------------------------------------- | | `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | Child components (SearchIcon, Input, ClearButton) or render function. | | `className` | `string \| (values: GroupRenderProps) => string` | - | CSS classes for styling. | #### SearchField.Input Props SearchField.Input inherits props from React Aria's [Input](https://react-spectrum.adobe.com/react-aria/Input.html) component. | Prop | Type | Default | Description | | ------------- | -------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `className` | `string` | - | CSS classes for styling. | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the input. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | | `placeholder` | `string` | - | Placeholder text displayed when the input is empty. | | `type` | `string` | `"search"` | Input type (automatically set to "search"). | #### SearchField.SearchIcon Props SearchField.SearchIcon is a custom component that renders the search icon. | Prop | Type | Default | Description | | ----------- | ----------------- | ---------------- | --------------------------------------------- | | `children` | `React.ReactNode` | `<IconSearch />` | Custom icon element. Defaults to search icon. | | `className` | `string` | - | CSS classes for styling. | #### SearchField.ClearButton Props SearchField.ClearButton inherits props from React Aria's [Button](https://react-spectrum.adobe.com/react-aria/Button.html) component. | Prop | Type | Default | Description | | ----------- | ----------------- | ---------------------- | ------------------------------------------------------- | | `children` | `React.ReactNode` | `<CloseButton icon />` | Icon or content for the button. Defaults to close icon. | | `className` | `string` | - | CSS classes for styling. | | `slot` | `"clear"` | `"clear"` | Must be set to "clear" (automatically set). | ### SearchFieldRenderProps When using render props with `className`, `style`, or `children`, these values are available: | Prop | Type | Description | | ---------------- | --------- | -------------------------------------------------------------------------- | | `isDisabled` | `boolean` | Whether the field is disabled. | | `isInvalid` | `boolean` | Whether the field is currently invalid. | | `isReadOnly` | `boolean` | Whether the field is read-only. | | `isRequired` | `boolean` | Whether the field is required. | | `isFocused` | `boolean` | Whether the field is currently focused (DEPRECATED - use `isFocusWithin`). | | `isFocusWithin` | `boolean` | Whether any child element is focused. | | `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). | | `value` | `string` | Current value. | | `isEmpty` | `boolean` | Whether the field is empty. | </page> <page url="/docs/react/components/text-area"> # TextArea **Category**: react **URL**: https://v3.heroui.com/docs/react/components/text-area **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/text-area.mdx > Primitive multiline text input component that accepts standard HTML attributes ## Import ```tsx import { TextArea } from '@heroui/react'; ``` <Callout> For validation, labels, and error messages, see **[TextField](/docs/components/text-field)**. </Callout> ### Usage ```tsx import {TextArea} from "@heroui/react"; export function Basic() { return ( <TextArea aria-label="Quick project update" className="h-32 w-96" placeholder="Share a quick project update..." /> ); } ``` ### Controlled ```tsx "use client"; import {Description, TextArea} from "@heroui/react"; import React from "react"; export function Controlled() { const [value, setValue] = React.useState(""); return ( <div className="flex w-96 flex-col gap-2"> <TextArea aria-describedby="textarea-controlled-description" aria-label="Announcement" placeholder="Compose an announcement..." value={value} onChange={(event) => setValue(event.target.value)} /> <Description id="textarea-controlled-description"> Characters: {value.length} / 280 </Description> </div> ); } ``` ### Rows and Resizing ```tsx import {Label, TextArea} from "@heroui/react"; export function Rows() { return ( <div className="flex w-96 flex-col gap-4"> <div className="flex flex-col gap-2"> <Label htmlFor="textarea-rows-3">Short feedback</Label> <TextArea aria-label="Short feedback" id="textarea-rows-3" placeholder="This week's highlights..." rows={3} /> </div> <div className="flex flex-col gap-2"> <Label htmlFor="textarea-rows-6">Detailed notes</Label> <TextArea aria-label="Detailed notes" id="textarea-rows-6" placeholder="Write out the full meeting notes..." rows={6} style={{resize: "vertical"}} /> </div> </div> ); } ``` ### Full Width ```tsx import {TextArea} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-3"> <TextArea fullWidth placeholder="Full width textarea" /> </div> ); } ``` ### Variants The TextArea component supports two visual variants: * **`primary`** (default) - Standard styling with shadow, suitable for most use cases * **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components ```tsx import {TextArea} from "@heroui/react"; export function Variants() { return ( <div className="flex w-[280px] flex-col gap-2"> <TextArea fullWidth placeholder="Primary textarea" variant="primary" /> <TextArea fullWidth placeholder="Secondary textarea" variant="secondary" /> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx import {Surface, TextArea} from "@heroui/react"; export function OnSurface() { return ( <Surface className="w-full rounded-3xl p-6"> <TextArea className="w-full min-w-[280px]" placeholder="Describe your product" variant="secondary" /> </Surface> ); } ``` ## Related Components * **TextField**: Composition-friendly fields with labels and validation * **Input**: Single-line text input built on React Aria * **Label**: Accessible label for form controls ## Styling ### Passing Tailwind CSS classes ```tsx import {Label, TextArea} from '@heroui/react'; function CustomTextArea() { return ( <div className="flex flex-col gap-2"> <Label htmlFor="custom-textarea">Message</Label> <TextArea id="custom-textarea" className="rounded-xl border border-border/70 bgsurface px-4 py-3 text-sm leading-6 shadow-sm" placeholder="Let us know how we can help..." rows={5} style={{resize: "vertical"}} /> </div> ); } ``` ### Customizing the component classes Override the shared `.textarea` class once with Tailwind's `@layer components`. ```css @layer components { .textarea { @apply rounded-xl border border-border bgsurface px-4 py-3 text-sm leading-6 shadow-sm; &:hover, &[data-hovered="true"] { @apply bg-surface-secondary border-border/80; } &:focus-visible, &[data-focus-visible="true"] { @apply border-primary ring-2 ring-primary/20; } &[data-invalid="true"] { @apply border-danger bg-danger-50/10 text-danger; } } } ``` ### CSS Classes * `.textarea` – Underlying `<textarea>` element styling ### Interactive States * **Hover**: `:hover` or `[data-hovered="true"]` * **Focus Visible**: `:focus-visible` or `[data-focus-visible="true"]` * **Invalid**: `[data-invalid="true"]` * **Disabled**: `:disabled` or `[aria-disabled="true"]` ## API Reference ### TextArea Props TextArea accepts all standard HTML `<textarea>` attributes plus the following: | Prop | Type | Default | Description | | -------------- | --------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `className` | `string` | - | Tailwind classes merged with the base styles. | | `rows` | `number` | `3` | Number of visible text lines. | | `cols` | `number` | - | Visible width of the text control. | | `value` | `string` | - | Controlled value for the textarea. | | `defaultValue` | `string` | - | Initial uncontrolled value. | | `onChange` | `(event: React.ChangeEvent<HTMLTextAreaElement>) => void` | - | Change handler. | | `placeholder` | `string` | - | Placeholder text. | | `disabled` | `boolean` | `false` | Disables the textarea. | | `readOnly` | `boolean` | `false` | Makes the textarea read-only. | | `required` | `boolean` | `false` | Marks the textarea as required. | | `name` | `string` | - | Name for form submission. | | `autoComplete` | `string` | - | Autocomplete hint for the browser. | | `maxLength` | `number` | - | Maximum number of characters. | | `minLength` | `number` | - | Minimum number of characters. | | `wrap` | `'soft' \| 'hard'` | - | How text wraps when submitted. | | `fullWidth` | `boolean` | `false` | Whether the textarea should take full width of its container | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | > For validation props like `isInvalid`, `isRequired`, and error handling, use **[TextField](/docs/components/text-field)** with TextArea as a child component. </page> <page url="/docs/react/components/text-field"> # TextField **Category**: react **URL**: https://v3.heroui.com/docs/react/components/text-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(forms)/text-field.mdx > Composition-friendly text fields with labels, descriptions, and inline validation ## Import ```tsx import { TextField } from '@heroui/react'; ``` ### Usage ```tsx import {Input, Label, TextField} from "@heroui/react"; export function Basic() { return ( <TextField className="w-full max-w-64" name="email" type="email"> <Label>Email</Label> <Input placeholder="Enter your email" /> </TextField> ); } ``` ### Anatomy ```tsx import {TextField, Label, Input, Description, FieldError} from '@heroui/react'; export default () => ( <TextField> <Label /> <Input /> <Description /> <FieldError /> </TextField> ) ``` > **TextField** combines label, input, description, and error into a single accessible component. > For standalone inputs, use **[Input](/docs/components/input)** or **[TextArea](/docs/components/textarea)**. ### With Description ```tsx import {Description, Input, Label, TextField} from "@heroui/react"; export function WithDescription() { return ( <TextField className="w-full max-w-64" name="username"> <Label>Username</Label> <Input placeholder="Enter username" /> <Description>Choose a unique username for your account</Description> </TextField> ); } ``` ### Required Field ```tsx import {Description, Input, Label, TextField} from "@heroui/react"; export function Required() { return ( <TextField isRequired className="w-full max-w-64" name="fullName"> <Label>Full Name</Label> <Input placeholder="John Doe" /> <Description>This field is required</Description> </TextField> ); } ``` ### Validation Use `isInvalid` together with `FieldError` to surface validation messages. ```tsx "use client"; import {Description, FieldError, Input, Label, TextArea, TextField} from "@heroui/react"; import React from "react"; export function Validation() { const [username, setUsername] = React.useState(""); const [bio, setBio] = React.useState(""); const isUsernameInvalid = username.length > 0 && username.length < 3; const isBioInvalid = bio.length > 0 && bio.length < 20; return ( <div className="flex w-full max-w-64 flex-col gap-4"> <TextField isRequired isInvalid={isUsernameInvalid} name="username" onChange={setUsername}> <Label>Username</Label> <Input placeholder="jane_doe" value={username} /> {isUsernameInvalid ? ( <FieldError>Username must be at least 3 characters.</FieldError> ) : ( <Description>Choose a unique username for your profile.</Description> )} </TextField> <TextField isRequired isInvalid={isBioInvalid} name="bio" onChange={setBio}> <Label>Bio</Label> <TextArea placeholder="Tell us about yourself..." value={bio} /> {isBioInvalid ? ( <FieldError>Bio must contain at least 20 characters.</FieldError> ) : ( <Description>Minimum 20 characters ({bio.length}/20).</Description> )} </TextField> </div> ); } ``` ### Controlled Control the value to synchronize counters, previews, or formatting. ```tsx "use client"; import {Description, Input, Label, TextArea, TextField} from "@heroui/react"; import React from "react"; export function Controlled() { const [name, setName] = React.useState(""); const [bio, setBio] = React.useState(""); return ( <div className="flex w-full max-w-64 flex-col gap-4"> <TextField name="name" onChange={setName}> <Label>Display name</Label> <Input placeholder="Jane" value={name} /> <Description>Characters: {name.length}</Description> </TextField> <TextField name="bio" onChange={setBio}> <Label>Bio</Label> <TextArea placeholder="Tell us about yourself..." value={bio} /> <Description>Characters: {bio.length} / 200</Description> </TextField> </div> ); } ``` ### Error Message ```tsx import {FieldError, Input, Label, TextField} from "@heroui/react"; export function WithError() { return ( <TextField isInvalid className="w-full max-w-64" name="email" type="email"> <Label>Email</Label> <Input placeholder="user@example.com" /> <FieldError>Please enter a valid email address</FieldError> </TextField> ); } ``` ### Disabled State ```tsx import {Description, Input, Label, TextField} from "@heroui/react"; export function Disabled() { return ( <TextField isDisabled className="w-full max-w-64" name="accountId"> <Label>Account ID</Label> <Input placeholder="Auto-generated" value="USR-12345" /> <Description>This field cannot be edited</Description> </TextField> ); } ``` ### TextArea Use [TextArea](/docs/components/textarea) instead of [Input](/docs/components/input) for multiline content. ```tsx import {Description, Label, TextArea, TextField} from "@heroui/react"; export function TextAreaExample() { return ( <TextField className="w-full max-w-64" name="message"> <Label>Message</Label> <TextArea placeholder="Write your message here..." rows={4} /> <Description>Maximum 500 characters</Description> </TextField> ); } ``` ### Input Types ```tsx import {Input, Label, TextField} from "@heroui/react"; export function InputTypes() { return ( <div className="flex w-full max-w-64 flex-col gap-4"> <TextField name="password" type="password"> <Label>Password</Label> <Input placeholder="••••••••" /> </TextField> <TextField name="age" type="number"> <Label>Age</Label> <Input max="150" min="0" placeholder="21" /> </TextField> <TextField name="email" type="email"> <Label>Email</Label> <Input placeholder="user@example.com" /> </TextField> <TextField name="website" type="url"> <Label>Website</Label> <Input placeholder="https://example.com" /> </TextField> <TextField name="phone" type="tel"> <Label>Phone</Label> <Input placeholder="+1 (555) 000-0000" /> </TextField> </div> ); } ``` ### Full Width ```tsx import {FieldError, Input, Label, TextField} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <TextField fullWidth name="name"> <Label>Your name</Label> <Input placeholder="John" /> </TextField> <TextField fullWidth isInvalid isRequired name="password" type="password"> <Label>Password</Label> <Input /> <FieldError>Password must be longer than 8 characters</FieldError> </TextField> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` on Input or TextArea components to apply the lower emphasis variant suitable for surface backgrounds. ```tsx import {Description, Input, Label, Surface, TextArea, TextField} from "@heroui/react"; export function OnSurface() { return ( <Surface className="flex w-full min-w-[340px] flex-col gap-4 rounded-3xl p-6"> <TextField name="name" variant="secondary"> <Label>Your name</Label> <Input className="w-full" placeholder="John" /> <Description>We'll never share this with anyone else</Description> </TextField> <TextField name="email" type="email" variant="secondary"> <Label>Email</Label> <Input className="w-full" placeholder="john@example.com" /> </TextField> <TextField name="bio" variant="secondary"> <Label>Bio</Label> <TextArea className="w-full" placeholder="Tell us about yourself..." rows={4} /> <Description>Minimum 4 rows</Description> </TextField> </Surface> ); } ``` ## Related Components * **Input**: Single-line text input built on React Aria * **TextArea**: Multiline text input with focus management * **Fieldset**: Group related form controls with legends ### Custom Render Function ```tsx "use client"; import {Input, Label, TextField} from "@heroui/react"; export function CustomRenderFunction() { return ( <TextField className="w-full max-w-64" name="email" render={(props) => <div {...props} data-custom="foo" />} type="email" > <Label>Email</Label> <Input placeholder="Enter your email" /> </TextField> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import {TextField, Label, Input, Description} from '@heroui/react'; function CustomTextField() { return ( <TextField className="gap-2 rounded-xl border border-border/60 bgsurface p-4 shadow-sm"> <Label className="text-sm font-semibold text-default-700"> Project name </Label> <Input className="rounded-lg border border-border/60 bgsurface px-3 py-2" /> <Description className="text-xs text-default-500"> Keep it short and memorable. </Description> </TextField> ); } ``` ### Customizing the component classes TextField has minimal default styling. Override the `.textfield` class to customize the container styling. ```css @layer components { .textfield { @apply flex flex-col gap-1; } /* When invalid, the description is hidden automatically */ .textfield[data-invalid="true"] [data-slot="description"], .textfield[aria-invalid="true"] [data-slot="description"] { @apply hidden; } /* Description has default padding */ .textfield [data-slot="description"] { @apply px-1; } } ``` ### CSS Classes * `.textfield` – Root container with minimal styling (`flex flex-col gap-1`) > **Note:** Child components ([Label](/docs/components/label), [Input](/docs/components/input), [TextArea](/docs/components/textarea), [Description](/docs/components/description), [FieldError](/docs/components/field-error)) have their own CSS classes and styling. See their respective documentation for customization options. ### Interactive States TextField automatically manages these data attributes based on its state: * **Invalid**: `[data-invalid="true"]` or `[aria-invalid="true"]` - Automatically hides the description slot when invalid * **Disabled**: `[data-disabled="true"]` - Applied when `isDisabled` is true * **Focus Within**: `[data-focus-within="true"]` - Applied when any child input is focused * **Focus Visible**: `[data-focus-visible="true"]` - Applied when focus is visible (keyboard navigation) Additional attributes are available through render props (see TextFieldRenderProps below). ## API Reference ### TextField Props TextField inherits all props from React Aria's [TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) component. #### Base Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------- | | `children` | `React.ReactNode \| (values: TextFieldRenderProps) => React.ReactNode` | - | Child components (Label, Input, etc.) or render function. | | `className` | `string \| (values: TextFieldRenderProps) => string` | - | CSS classes for styling, supports render props. | | `style` | `React.CSSProperties \| (values: TextFieldRenderProps) => React.CSSProperties` | - | Inline styles, supports render props. | | `fullWidth` | `boolean` | `false` | Whether the text field should take full width of its container | | `id` | `string` | - | The element's unique identifier. | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TextFieldRenderProps>` | - | Overrides the default DOM element with a custom render function. | #### Validation Props | Prop | Type | Default | Description | | -------------------- | ----------------------------------------------------------------- | ---------- | -------------------------------------------------------------- | | `isRequired` | `boolean` | `false` | Whether user input is required before form submission. | | `isInvalid` | `boolean` | - | Whether the value is invalid. | | `validate` | `(value: string) => ValidationError \| true \| null \| undefined` | - | Custom validation function. | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA attributes. | | `validationErrors` | `string[]` | - | Server-side validation errors. | #### Value Props | Prop | Type | Default | Description | | -------------- | ------------------------- | ------- | -------------------------------------- | | `value` | `string` | - | Current value (controlled). | | `defaultValue` | `string` | - | Default value (uncontrolled). | | `onChange` | `(value: string) => void` | - | Handler called when the value changes. | #### 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. | | `autoFocus` | `boolean` | - | Whether the element should receive focus on render. | #### Accessibility Props | Prop | Type | Default | Description | | ------------------ | -------- | ------- | ----------------------------------------------------- | | `aria-label` | `string` | - | Accessibility label when no visible label is present. | | `aria-labelledby` | `string` | - | ID of elements that label this field. | | `aria-describedby` | `string` | - | ID of elements that describe this field. | | `aria-details` | `string` | - | ID of elements with additional details. | ### Composition Components TextField works with these separate components that should be imported and used directly: * **Label** - Field label component from `@heroui/react` * **Input** - Single-line text input from `@heroui/react` * **TextArea** - Multi-line text input from `@heroui/react` * **Description** - Helper text component from `@heroui/react` * **FieldError** - Validation error message from `@heroui/react` Each of these components has its own props API. Use them directly within TextField for composition: ```tsx <TextField isRequired isInvalid={hasError}> <Label>Email Address</Label> <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} /> <Description>We'll never share your email.</Description> <FieldError>Please enter a valid email address.</FieldError> </TextField> ``` ### TextFieldRenderProps When using render props with `className`, `style`, or `children`, these values are available: | Prop | Type | Description | | ---------------- | --------- | -------------------------------------------------------------------------- | | `isDisabled` | `boolean` | Whether the field is disabled. | | `isInvalid` | `boolean` | Whether the field is currently invalid. | | `isReadOnly` | `boolean` | Whether the field is read-only. | | `isRequired` | `boolean` | Whether the field is required. | | `isFocused` | `boolean` | Whether the field is currently focused (DEPRECATED - use `isFocusWithin`). | | `isFocusWithin` | `boolean` | Whether any child element is focused. | | `isFocusVisible` | `boolean` | Whether focus is visible (keyboard navigation). | </page> <page url="/docs/react/components/card"> # Card **Category**: react **URL**: https://v3.heroui.com/docs/react/components/card **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(layout)/card.mdx > Flexible container component for grouping related content and actions ## Import ```tsx import { Card } from "@heroui/react"; ``` ### Usage ```tsx import {CircleDollar} from "@gravity-ui/icons"; import {Card, Link} from "@heroui/react"; export function Default() { return ( <Card className="w-[400px]"> <CircleDollar aria-label="Dollar sign icon" className="text-primary size-6" role="img" /> <Card.Header> <Card.Title>Become an Acme Creator!</Card.Title> <Card.Description> Visit the Acme Creator Hub to sign up today and start earning credits from your fans and followers. </Card.Description> </Card.Header> <Card.Footer> <Link aria-label="Go to Acme Creator Hub (opens in new tab)" href="https://heroui.com" rel="noopener noreferrer" target="_blank" > Creator Hub <Link.Icon aria-hidden="true" /> </Link> </Card.Footer> </Card> ); } ``` ### Anatomy Import the Card component and access all parts using dot notation. ```tsx import { Card } from "@heroui/react"; export default () => ( <Card> <Card.Header> <Card.Title /> <Card.Description /> </Card.Header> <Card.Content /> <Card.Footer /> </Card> ); ``` ### Variants Cards come in semantic variants that describe their prominence level rather than specific visual styles. This allows themes to interpret them differently: ```tsx import {Card} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-4"> <Card className="w-[320px]" variant="transparent"> <Card.Header> <Card.Title>Transparent</Card.Title> <Card.Description>Minimal prominence with transparent background</Card.Description> </Card.Header> <Card.Content> <p>Use for less important content or nested cards</p> </Card.Content> </Card> <Card className="w-[320px]" variant="default"> <Card.Header> <Card.Title>Default</Card.Title> <Card.Description>Standard card appearance (bg-surface)</Card.Description> </Card.Header> <Card.Content> <p>The default card variant for most use cases</p> </Card.Content> </Card> <Card className="w-[320px]" variant="secondary"> <Card.Header> <Card.Title>Secondary</Card.Title> <Card.Description>Medium prominence (bg-surface-secondary)</Card.Description> </Card.Header> <Card.Content> <p>Use to draw moderate attention</p> </Card.Content> </Card> <Card className="w-[320px]" variant="tertiary"> <Card.Header> <Card.Title>Tertiary</Card.Title> <Card.Description>Higher prominence (bg-surface-tertiary)</Card.Description> </Card.Header> <Card.Content> <p>Use for primary or featured content</p> </Card.Content> </Card> </div> ); } ``` * **`transparent`** - Minimal prominence, transparent background (great for nested cards) * **`default`** - Standard card for most use cases (surface-secondary) * **`secondary`** - Medium prominence to draw moderate attention (surface-tertiary) * **`tertiary`** - Higher prominence for important content (surface-tertiary) ### Horizontal Layout ```tsx import {Button, Card, CloseButton} from "@heroui/react"; export function Horizontal() { return ( <Card className="w-full items-stretch md:flex-row"> <div className="relative h-[140px] w-full shrink-0 overflow-hidden rounded-2xl sm:h-[120px] sm:w-[120px]"> <img alt="Cherries" className="pointer-events-none absolute inset-0 h-full w-full scale-125 object-cover select-none" loading="lazy" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cherries.jpeg" /> </div> <div className="flex flex-1 flex-col gap-3"> <Card.Header className="gap-1"> <Card.Title className="pr-8">Become an ACME Creator!</Card.Title> <Card.Description> Lorem ipsum dolor sit amet consectetur. Sed arcu donec id aliquam dolor sed amet faucibus etiam. </Card.Description> <CloseButton aria-label="Close banner" className="absolute top-3 right-3" /> </Card.Header> <Card.Footer className="mt-auto flex w-full flex-col items-start gap-3 sm:flex-row sm:items-center sm:justify-between"> <div className="flex flex-col"> <span className="text-sm font-medium text-foreground">Only 10 spots</span> <span className="text-xs text-muted">Submission ends Oct 10.</span> </div> <Button className="w-full sm:w-auto">Apply Now</Button> </Card.Footer> </div> </Card> ); } ``` ### With Avatar ```tsx import {Avatar, Card} from "@heroui/react"; export function WithAvatar() { return ( <div className="flex flex-wrap gap-4"> <Card className="w-[200px] gap-2"> <img alt="Indie Hackers community" className="pointer-events-none aspect-square w-14 rounded-2xl object-cover select-none" loading="lazy" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg" /> <Card.Header> <Card.Title>Indie Hackers</Card.Title> <Card.Description>148 members</Card.Description> </Card.Header> <Card.Footer className="flex gap-2"> <Avatar aria-label="Martha's profile picture" className="size-5"> <Avatar.Image alt="Martha's avatar" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg" /> <Avatar.Fallback className="text-xs">IH</Avatar.Fallback> </Avatar> <span className="text-xs">By Martha</span> </Card.Footer> </Card> <Card className="w-[200px] gap-2"> <img alt="AI Builders community" className="pointer-events-none aspect-square w-14 rounded-2xl object-cover select-none" loading="lazy" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg" /> <Card.Header> <Card.Title>AI Builders</Card.Title> <Card.Description>362 members</Card.Description> </Card.Header> <Card.Footer className="flex gap-2"> <Avatar aria-label="John's profile picture" className="size-5"> <Avatar.Image alt="John's avatar - blue themed" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback className="text-xs">B</Avatar.Fallback> </Avatar> <span className="text-xs">By John</span> </Card.Footer> </Card> </div> ); } ``` ### With Images ```tsx import {CircleDollar} from "@gravity-ui/icons"; import {Avatar, Button, Card, CloseButton, Link} from "@heroui/react"; export function WithImages() { return ( <div className="flex w-full items-center justify-center"> <div className="grid w-full max-w-2xl grid-cols-12 gap-4 p-4"> {/* Row 1: Large Product Card - Available Soon */} <Card className="col-span-12 flex h-auto min-h-[152px] flex-col sm:flex-row"> <div className="relative h-[140px] w-full shrink-0 overflow-hidden rounded-2xl sm:h-[120px] sm:w-[120px]"> <img alt="Cherries" className="pointer-events-none absolute inset-0 h-full w-full scale-125 object-cover select-none" loading="lazy" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/cherries.jpeg" /> </div> <div className="flex flex-1 flex-col gap-3"> <Card.Header className="gap-1"> <Card.Title className="pr-8">Become an ACME Creator!</Card.Title> <Card.Description> Lorem ipsum dolor sit amet consectetur. Sed arcu donec id aliquam dolor sed amet faucibus etiam. </Card.Description> <CloseButton aria-label="Close banner" className="absolute top-3 right-3" /> </Card.Header> <Card.Footer className="mt-auto flex w-full flex-col items-start gap-3 sm:flex-row sm:items-center sm:justify-between"> <div className="flex flex-col"> <span className="text-sm font-medium text-foreground">Only 10 spots</span> <span className="text-xs text-muted">Submission ends Oct 10.</span> </div> <Button className="w-full sm:w-auto">Apply Now</Button> </Card.Footer> </div> </Card> {/* Row 2 */} <div className="col-span-12 grid grid-cols-12 gap-4"> {/* Left Column */} <div className="col-span-12 grid grid-cols-12 gap-4 lg:col-span-6"> {/* Top Card */} <Card className="col-span-12"> <div className="absolute top-3 right-3 z-10"> <CloseButton aria-label="Close notification" /> </div> <Card.Header className="gap-3"> <CircleDollar aria-label="Dollar sign icon" className="text-primary size-8 shrink-0" role="img" /> <div className="flex flex-col gap-1"> <span className="text-xs font-medium text-muted uppercase">PAYMENT</span> <Card.Title className="pr-8 text-sm sm:text-base"> You can now withdraw on crypto </Card.Title> <Card.Description className="text-xs sm:text-sm"> Add your wallet in settings to withdraw </Card.Description> </div> </Card.Header> <Card.Footer> <Link aria-label="Go to settings" href="#" rel="noopener noreferrer"> Go to settings <Link.Icon aria-hidden="true" /> </Link> </Card.Footer> </Card> {/* Bottom cards */} <div className="col-span-12 grid grid-cols-12 gap-4"> {/* Left Card */} <Card className="col-span-12 gap-2 sm:col-span-6"> <Card.Header> <Avatar className="size-[56px] rounded-xl"> <Avatar.Image alt="Demo 1" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo1.jpg" /> <Avatar.Fallback>JK</Avatar.Fallback> </Avatar> </Card.Header> <Card.Content className="mt-1"> <p className="text-sm leading-4 font-medium">Indie Hackers</p> <p className="text-xs text-muted">148 members</p> </Card.Content> <Card.Footer className="flex items-center gap-2"> <Avatar className="size-4"> <Avatar.Image alt="John" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg" /> <Avatar.Fallback>JK</Avatar.Fallback> </Avatar> <p className="text-xs text-muted">By John</p> </Card.Footer> </Card> {/* Right Card */} <Card className="col-span-12 gap-2 sm:col-span-6"> <Card.Header> <Avatar className="size-[56px] rounded-xl"> <Avatar.Image alt="Demo 2" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/demo2.jpg" /> <Avatar.Fallback>AB</Avatar.Fallback> </Avatar> </Card.Header> <Card.Content className="mt-1"> <p className="text-sm leading-4 font-medium">AI Builders</p> <p className="text-xs text-muted">362 members</p> </Card.Content> <Card.Footer className="flex items-center gap-2"> <Avatar className="size-4"> <Avatar.Image alt="John" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>M</Avatar.Fallback> </Avatar> <p className="text-xs text-muted">By Martha</p> </Card.Footer> </Card> </div> </div> {/* Right Column */} <Card className="col-span-12 min-h-[200px] overflow-hidden rounded-3xl lg:col-span-6"> {/* Background image */} <img alt="NEO Home Robot" aria-hidden="true" className="absolute inset-0 h-full w-full object-cover" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo2.jpeg" /> {/* Header */} <Card.Header className="z-10 text-white"> <Card.Title className="text-xs font-semibold tracking-wide text-black/70"> NEO </Card.Title> <Card.Description className="text-sm leading-5 font-medium text-black/50"> Home Robot </Card.Description> </Card.Header> {/* Footer */} <Card.Footer className="z-10 mt-auto flex items-center justify-between"> <div> <div className="text-sm font-medium text-black">Available soon</div> <div className="text-xs text-black/60">Get notified</div> </div> <Button className="bg-white text-black" size="sm" variant="tertiary"> Notify me </Button> </Card.Footer> </Card> </div> {/* Row 3 */} <div className="col-span-12 grid grid-cols-12 gap-4"> {/* Left Column: Card */} <Card className="relative col-span-12 h-[250px] sm:h-[300px] md:col-span-8 md:h-[350px]"> <img alt="NEO Home Robot" aria-hidden="true" className="absolute inset-0 h-full w-full object-cover" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo1.jpeg" /> <Card.Footer className="z-10 mt-auto flex items-end justify-between"> <div> <div className="text-base font-medium text-black sm:text-lg">NEO</div> <div className="text-xs font-medium text-black/50 sm:text-sm">$499/m</div> </div> <Button className="bg-white text-black" size="sm" variant="tertiary"> Get now </Button> </Card.Footer> </Card> {/* Right Column: Cards Stack */} <div className="col-span-12 flex flex-col gap-2 md:col-span-4 md:justify-between md:gap-0 md:py-2"> {/* 1 */} <Card className="flex flex-row gap-3 p-1" variant="transparent"> <img alt="Futuristic Robot" className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20" loading="lazy" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg" /> <div className="flex flex-1 flex-col justify-center gap-1"> <Card.Title className="text-sm">Bridging the Future</Card.Title> <Card.Description className="text-xs">Today, 6:30 PM</Card.Description> </div> </Card> {/* 2 */} <Card className="flex flex-row gap-3 p-1" variant="transparent"> <img alt="Avocado" className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20" loading="lazy" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg" /> <div className="flex flex-1 flex-col justify-center gap-1"> <Card.Title className="text-sm">Avocado Hackathon</Card.Title> <Card.Description className="text-xs">Wed, 4:30 PM</Card.Description> </div> </Card> {/* 3 */} <Card className="flex flex-row gap-3 p-1" variant="transparent"> <img alt="Sound Electro event" className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20" loading="lazy" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg" /> <div className="flex flex-1 flex-col justify-center gap-1"> <Card.Title className="text-sm">Sound Electro | Beyond art</Card.Title> <Card.Description className="text-xs">Fri, 8:00 PM</Card.Description> </div> </Card> </div> </div> </div> </div> ); } ``` ### With Form ```tsx "use client"; import {Button, Card, Form, Input, Label, Link, TextField} from "@heroui/react"; export function WithForm() { const onSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record<string, string> = {}; // Convert FormData to plain object formData.forEach((value, key) => { data[key] = value.toString(); }); alert("Form submitted successfully!"); }; return ( <Card className="w-full max-w-md"> <Card.Header> <Card.Title>Login</Card.Title> <Card.Description>Enter your credentials to access your account</Card.Description> </Card.Header> <Form onSubmit={onSubmit}> <Card.Content> <div className="flex flex-col gap-4"> <TextField name="email" type="email"> <Label>Email</Label> <Input placeholder="email@example.com" variant="secondary" /> </TextField> <TextField name="password" type="password"> <Label>Password</Label> <Input placeholder="••••••••" variant="secondary" /> </TextField> </div> </Card.Content> <Card.Footer className="mt-4 flex flex-col gap-2"> <Button className="w-full" type="submit"> Sign In </Button> <Link className="text-center text-sm" href="#"> Forgot password? </Link> </Card.Footer> </Form> </Card> ); } ``` ## Accessibility ```tsx import { Card } from '@heroui/react'; import { cardVariants } from '@heroui/styles'; // Semantic markup <Card role="article" aria-labelledby="card-title"> <Card.Header> <Card.Title id="card-title">Article Title</Card.Title> </Card.Header> </Card> // Interactive cards <a className={cardVariants().base()} href="/details" aria-label="View product details"> <Card.Title>Product Name</Card.Title> </a> ``` ## Related Components * **Surface**: Base container surface * **Avatar**: Display user profile images * **Form**: Form validation and submission handling ## Styling ### Component Customization ```tsx <Card className="border-2 border-blue-500 bg-gradient-to-r from-blue-50 to-purple-50"> <Card.Header> <Card.Title className="text-blue-900">Custom Styled Card</Card.Title> <Card.Description className="text-blue-700">Custom colors applied</Card.Description> </Card.Header> <Card.Content> <p className="text-blue-800">Content with custom styling</p> </Card.Content> </Card> ``` ### CSS Variable Overrides ```css /* Override specific variants */ .card--secondary { @apply bg-gradient-to-br from-blue-50 to-purple-50; } /* Custom element styles */ .card__title { @apply text-xl font-bold; } ``` ## CSS Classes Card uses [BEM](https://getbem.com/) naming for predictable styling, ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/card.css)): #### Base Classes * `.card` - Base container with padding and border * `.card__header` - Header section container * `.card__title` - Title with base font size and weight * `.card__description` - Muted description text * `.card__content` - Flexible content container * `.card__footer` - Footer with row layout #### Variant Classes * `.card--transparent` - Minimal prominence, transparent background (maps to `transparent` variant) * `.card--default` - Standard appearance with surface-secondary (default) * `.card--secondary` - Medium prominence with surface-tertiary (maps to `secondary` variant) * `.card--tertiary` - Higher prominence with surface-tertiary (maps to `tertiary` variant) ## API Reference ### Card | Prop | Type | Default | Description | | ----------- | --------------------------------------------------------- | ----------- | -------------------------------------------- | | `variant` | `"transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | Semantic variant indicating prominence level | | `className` | `string` | - | Additional CSS classes | | `children` | `React.ReactNode` | - | Card content | ### Card.Header | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `React.ReactNode` | - | Header content | ### Card.Title | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `React.ReactNode` | - | Title content (renders as `h3`) | ### Card.Description | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ------------------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `React.ReactNode` | - | Description content (renders as `p`) | ### Card.Content | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `React.ReactNode` | - | Main content | ### Card.Footer | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `React.ReactNode` | - | Footer content | </page> <page url="/docs/react/components/separator"> # Separator **Category**: react **URL**: https://v3.heroui.com/docs/react/components/separator **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(layout)/separator.mdx > Visually divide content sections ## Import ```tsx import { Separator } from '@heroui/react'; ``` ### Usage ```tsx import {Separator} from "@heroui/react"; export function Basic() { return ( <div className="max-w-md"> <div className="space-y-1"> <h4 className="text-medium font-medium">HeroUI v3 Components</h4> <p className="text-small text-default-400">Beautiful, fast and modern React UI library.</p> </div> <Separator className="my-4" /> <div className="text-small flex h-5 items-center space-x-4"> <div>Blog</div> <Separator orientation="vertical" /> <div>Docs</div> <Separator orientation="vertical" /> <div>Source</div> </div> </div> ); } ``` ### Vertical ```tsx import {Separator} from "@heroui/react"; export function Vertical() { return ( <div className="text-small flex h-5 items-center space-x-4"> <div>Blog</div> <Separator orientation="vertical" /> <div>Docs</div> <Separator orientation="vertical" /> <div>Source</div> </div> ); } ``` ### With Content ```tsx import {Separator} from "@heroui/react"; const items = [ { iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png", subtitle: "Receive account activity updates", title: "Set Up Notifications", }, { iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png", subtitle: "Connect your browser to your account", title: "Set up Browser Extension", }, { iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png", subtitle: "Create your first collectible", title: "Mint Collectible", }, ]; export function WithContent() { return ( <div className="max-w-md space-y-4"> {items.map((item, index) => ( <div key={index}> <div className="flex items-center gap-3"> <img alt={item.title} className="size-12" src={item.iconUrl} /> <div className="flex-1 space-y-0"> <h4 className="text-small font-medium">{item.title}</h4> <p className="text-sm text-muted">{item.subtitle}</p> </div> </div> {index < items.length - 1 && <Separator className="my-4" />} </div> ))} </div> ); } ``` ### Variants ```tsx import {Separator} from "@heroui/react"; export function Variants() { return ( <div className="flex max-w-md flex-col items-center gap-3"> <div>Default Variant</div> <Separator variant="default" /> <div>Secondary Variant</div> <Separator variant="secondary" /> <div>Tertiary Variant</div> <Separator variant="tertiary" /> </div> ); } ``` ### With Surface The Separator component adapts to different surface backgrounds for better visibility. ```tsx import {Separator, Surface} from "@heroui/react"; export function WithSurface() { return ( <div className="flex flex-col gap-8"> <div className="flex flex-col gap-2"> <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default"> <h3 className="text-base font-semibold text-foreground">Default Surface</h3> <Separator /> <p className="text-sm text-muted">Surface Content</p> </Surface> </div> <div className="flex flex-col gap-2"> <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="secondary"> <h3 className="text-base font-semibold text-foreground">Secondary Surface</h3> <Separator variant="secondary" /> <p className="text-sm text-muted">Surface Content</p> </Surface> </div> <div className="flex flex-col gap-2"> <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="tertiary"> <h3 className="text-base font-semibold text-foreground">Tertiary Surface</h3> <Separator variant="tertiary" /> <p className="text-sm text-muted">Surface Content</p> </Surface> </div> <div className="flex flex-col gap-2"> <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl border p-6" variant="transparent" > <h3 className="text-base font-semibold text-foreground">Transparent Surface</h3> <Separator /> <p className="text-sm text-muted">Surface Content</p> </Surface> </div> </div> ); } ``` ## Related Components * **Card**: Content container with header, body, and footer * **Chip**: Compact elements for tags and filters * **Avatar**: Display user profile images ### Custom Render Function ```tsx "use client"; import {Separator} from "@heroui/react"; export function CustomRenderFunction() { return ( <div className="max-w-md"> <div className="space-y-1"> <h4 className="text-medium font-medium">HeroUI v3 Components</h4> <p className="text-small text-default-400">Beautiful, fast and modern React UI library.</p> </div> <Separator className="my-4" render={(props) => <div {...props} data-custom="foo" />} /> <div className="text-small flex h-5 items-center space-x-4"> <div>Blog</div> <Separator orientation="vertical" render={(props) => <div {...props} data-custom="foo" />} /> <div>Docs</div> <Separator orientation="vertical" render={(props) => <div {...props} data-custom="foo" />} /> <div>Source</div> </div> </div> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import {Separator} from '@heroui/react'; function CustomSeparator() { return ( <Separator className="my-8 bg-linear-to-r from-transparent via-default-500 to-transparent" /> ); } ``` ### Customizing the component classes To customize the Separator component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .separator { @apply bg-accent h-[2px]; } .separator--vertical { @apply bg-accent w-[2px]; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Separator component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/separator.css)): #### Base & Orientation Classes * `.separator` - Base separator styles with default horizontal orientation * `.separator--horizontal` - Horizontal orientation (full width, 1px height) * `.separator--vertical` - Vertical orientation (full height, 1px width) #### Variant Classes * `.separator--default` - Default variant with standard contrast * `.separator--secondary` - Secondary variant with medium contrast * `.separator--tertiary` - Tertiary variant with subtle contrast ## API Reference ### Separator Props | Prop | Type | Default | Description | | ------------- | ----------------------------------------------------------------- | -------------- | ---------------------------------------------------------------- | | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | The orientation of the separator | | `variant` | `'default' \| 'secondary' \| 'tertiary'` | `'default'` | The visual variant of the separator | | `className` | `string` | - | Additional CSS classes | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | Overrides the default DOM element with a custom render function. | </page> <page url="/docs/react/components/surface"> # Surface **Category**: react **URL**: https://v3.heroui.com/docs/react/components/surface **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(layout)/surface.mdx > Container component that provides surface-level styling and context for child components ## Import ```tsx import { Surface } from '@heroui/react'; ``` ### Usage ```tsx import {Surface} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-4"> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Default</p> <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default"> <h3 className="text-base font-semibold text-foreground">Surface Content</h3> <p className="text-sm text-muted"> This is a default surface variant. It uses bg-surface styling. </p> </Surface> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Secondary</p> <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="secondary"> <h3 className="text-base font-semibold text-foreground">Surface Content</h3> <p className="text-sm text-muted"> This is a secondary surface variant. It uses bg-surface-secondary styling. </p> </Surface> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Tertiary</p> <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="tertiary"> <h3 className="text-base font-semibold text-foreground">Surface Content</h3> <p className="text-sm text-muted"> This is a tertiary surface variant. It uses bg-surface-tertiary styling. </p> </Surface> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Transparent</p> <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl border p-6" variant="transparent" > <h3 className="text-base font-semibold text-foreground">Surface Content</h3> <p className="text-sm text-muted"> This is a transparent surface variant. It has no background, suitable for overlays and cards with custom backgrounds. </p> </Surface> </div> </div> ); } ``` ## Overview The Surface component is a semantic container that provides different levels of visual prominence through variants. ### Variants Surface comes in semantic variants that describe their prominence level: * **`default`** - Standard surface appearance (bg-surface) * **`secondary`** - Medium prominence (bg-surface-secondary) * **`tertiary`** - Higher prominence (bg-surface-tertiary) ## Usage with Form Components When using form components inside a Surface, use the `variant="secondary"` prop to apply the lower emphasis variant suitable for surface backgrounds. ```tsx import { Surface, Input, TextArea } from '@heroui/react'; function App() { return ( <Surface variant="default"> <Input placeholder="Input with secondary variant" variant="secondary" /> <TextArea placeholder="TextArea with secondary variant" variant="secondary" /> </Surface> ); } ``` ## Related Components * **CheckboxGroup**: Group of checkboxes with shared state * **Fieldset**: Group related form controls with legends * **InputOTP**: One-time password input ## Styling ### Passing Tailwind CSS classes ```tsx import { Surface } from '@heroui/react'; function CustomSurface() { return ( <Surface className="rounded-2xl p-8 shadow-lg" variant="secondary" > <h2>Custom Styled Surface</h2> <p>Content goes here</p> </Surface> ); } ``` ### Customizing the component classes To customize the Surface component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .surface { @apply rounded-2xl border border-border; } .surface--secondary { @apply bg-gradient-to-br from-blue-50 to-purple-50; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Surface component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/surface.css)): #### Base Classes * `.surface` - Base surface container #### Variant Classes * `.surface--default` - Default surface variant (bg-surface) * `.surface--secondary` - Secondary surface variant (bg-surface-secondary) * `.surface--tertiary` - Tertiary surface variant (bg-surface-tertiary) ## API Reference ### Surface Props | Prop | Type | Default | Description | | ----------- | ---------------------------------------------------------- | ----------- | --------------------------------- | | `variant` | ` "transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | The visual variant of the surface | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | The surface content | ## Context API ### SurfaceContext Child components can access the Surface context to get the current variant: ```tsx import { useContext } from 'react'; import { SurfaceContext } from '@heroui/react'; function MyComponent() { const { variant } = useContext(SurfaceContext); // variant will be "transparent" | "default" | "secondary" | "tertiary" | undefined } ``` </page> <page url="/docs/react/components/avatar"> # Avatar **Category**: react **URL**: https://v3.heroui.com/docs/react/components/avatar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(media)/avatar.mdx > Display user profile images with customizable fallback content ## Import ```tsx import { Avatar } from '@heroui/react'; ``` ### Usage ```tsx import {Avatar} from "@heroui/react"; export function Basic() { return ( <div className="flex items-center gap-4"> <Avatar> <Avatar.Image alt="John Doe" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3" /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Avatar> <Avatar.Image alt="Blue" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>B</Avatar.Fallback> </Avatar> <Avatar> <Avatar.Fallback>JR</Avatar.Fallback> </Avatar> </div> ); } ``` ### Anatomy Import the Avatar component and access all parts using dot notation. ```tsx import { Avatar } from '@heroui/react'; export default () => ( <Avatar> <Avatar.Image/> <Avatar.Fallback/> </Avatar> ) ``` ### Sizes ```tsx import {Avatar} from "@heroui/react"; export function Sizes() { return ( <div className="flex items-center gap-4"> <Avatar size="sm"> <Avatar.Image alt="Small Avatar" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>SM</Avatar.Fallback> </Avatar> <Avatar size="md"> <Avatar.Image alt="Medium Avatar" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" /> <Avatar.Fallback>MD</Avatar.Fallback> </Avatar> <Avatar size="lg"> <Avatar.Image alt="Large Avatar" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg" /> <Avatar.Fallback>LG</Avatar.Fallback> </Avatar> </div> ); } ``` ### Colors ```tsx import {Avatar} from "@heroui/react"; export function Colors() { return ( <div className="flex items-center gap-4"> <Avatar color="default"> <Avatar.Fallback>DF</Avatar.Fallback> </Avatar> <Avatar color="accent"> <Avatar.Fallback>AC</Avatar.Fallback> </Avatar> <Avatar color="success"> <Avatar.Fallback>SC</Avatar.Fallback> </Avatar> <Avatar color="warning"> <Avatar.Fallback>WR</Avatar.Fallback> </Avatar> <Avatar color="danger"> <Avatar.Fallback>DG</Avatar.Fallback> </Avatar> </div> ); } ``` ### Variants ```tsx import {Person} from "@gravity-ui/icons"; import {Avatar, Separator} from "@heroui/react"; export function Variants() { const colors = ["accent", "default", "success", "warning", "danger"] as const; const variants = [ {content: "AG", label: "letter", type: "letter"}, {content: "AG", label: "letter soft", type: "letter-soft"}, {content: <Person />, label: "icon", type: "icon"}, {content: <Person />, label: "icon soft", type: "icon-soft"}, { content: [ "https://img.heroui.chat/image/avatar?w=400&h=400&u=3", "https://img.heroui.chat/image/avatar?w=400&h=400&u=4", "https://img.heroui.chat/image/avatar?w=400&h=400&u=5", "https://img.heroui.chat/image/avatar?w=400&h=400&u=8", "https://img.heroui.chat/image/avatar?w=400&h=400&u=16", ], label: "img", type: "img", }, ] as const; return ( <div className="flex flex-col gap-4"> {/* Color labels header */} <div className="flex items-center gap-3"> <div className="w-24 shrink-0" /> {colors.map((color) => ( <div key={color} className="flex w-20 shrink-0 items-center justify-center"> <span className="text-xs text-muted capitalize">{color}</span> </div> ))} </div> <Separator /> {/* Variant rows */} {variants.map((variant) => ( <div key={variant.label} className="flex items-center gap-3"> <div className="w-24 shrink-0 text-sm text-muted">{variant.label}</div> {colors.map((color, colorIndex) => ( <div key={color} className="flex w-20 shrink-0 items-center justify-center"> <Avatar color={color} variant={variant.type.includes("soft") ? "soft" : undefined}> {variant.type === "img" ? ( <> <Avatar.Image alt={`Avatar ${color}`} src={Array.isArray(variant.content) ? variant.content[colorIndex] : ""} /> <Avatar.Fallback>{color.charAt(0).toUpperCase()}</Avatar.Fallback> </> ) : ( <Avatar.Fallback>{variant.content}</Avatar.Fallback> )} </Avatar> </div> ))} </div> ))} </div> ); } ``` ### Fallback Content ```tsx import {Person} from "@gravity-ui/icons"; import {Avatar} from "@heroui/react"; export function Fallback() { return ( <div className="flex items-center gap-4"> {/* Text fallback */} <Avatar> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> {/* Icon fallback */} <Avatar> <Avatar.Fallback> <Person /> </Avatar.Fallback> </Avatar> {/* Fallback with delay */} <Avatar> <Avatar.Image alt="Delayed Avatar" src="https://invalid-url-to-show-fallback.com/image.jpg" /> <Avatar.Fallback delayMs={600}>NA</Avatar.Fallback> </Avatar> {/* Custom styled fallback */} <Avatar> <Avatar.Fallback className="border-none bg-gradient-to-br from-pink-500 to-purple-500 text-white"> GB </Avatar.Fallback> </Avatar> </div> ); } ``` ### Avatar Group ```tsx import {Avatar} from "@heroui/react"; const users = [ { id: 1, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", name: "John Doe", }, { id: 2, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", name: "Kate Wilson", }, { id: 3, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", name: "Emily Chen", }, { id: 4, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", name: "Michael Brown", }, { id: 5, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", name: "Olivia Davis", }, ]; export function Group() { return ( <div className="flex flex-col gap-6"> {/* Basic avatar group */} <div className="flex -space-x-2"> {users.slice(0, 4).map((user) => ( <Avatar key={user.id} className="ring-2 ring-background"> <Avatar.Image alt={user.name} src={user.image} /> <Avatar.Fallback> {user.name .split(" ") .map((n) => n[0]) .join("")} </Avatar.Fallback> </Avatar> ))} </div> {/* Avatar group with counter */} <div className="flex -space-x-2"> {users.slice(0, 3).map((user) => ( <Avatar key={user.id} className="ring-2 ring-background"> <Avatar.Image alt={user.name} src={user.image} /> <Avatar.Fallback> {user.name .split(" ") .map((n) => n[0]) .join("")} </Avatar.Fallback> </Avatar> ))} <Avatar className="ring-2 ring-background"> <Avatar.Fallback className="text-xs">+{users.length - 3}</Avatar.Fallback> </Avatar> </div> </div> ); } ``` ### Custom Styles ```tsx import {Avatar} from "@heroui/react"; export function CustomStyles() { return ( <div className="flex items-center gap-4"> {/* Custom size with Tailwind classes */} <Avatar className="size-16"> <Avatar.Image alt="Extra Large" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>XL</Avatar.Fallback> </Avatar> {/* Square avatar */} <Avatar className="rounded-lg"> <Avatar.Image alt="Square Avatar" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" /> <Avatar.Fallback className="rounded-lg">SQ</Avatar.Fallback> </Avatar> {/* Gradient border */} <Avatar className="bg-gradient-to-tr from-pink-500 to-yellow-500 p-0.5"> <div className="size-full rounded-full bg-background p-0.5"> <Avatar.Image alt="Gradient Border" className="rounded-full" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg" /> <Avatar.Fallback className="border-none">GB</Avatar.Fallback> </div> </Avatar> {/* Status indicator */} <div className="relative"> <Avatar> <Avatar.Image alt="Online User" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg" /> <Avatar.Fallback>ON</Avatar.Fallback> </Avatar> <span className="absolute right-0 bottom-0 size-3 rounded-full bg-green-500 ring-2 ring-background" /> </div> </div> ); } ``` ## Related Components * **Separator**: Visual divider between content * **Badge**: Small indicator positioned relative to another element ## Styling ### Passing Tailwind CSS classes ```tsx import { Avatar } from '@heroui/react'; function CustomAvatar() { return ( <Avatar className="size-20"> <Avatar.Image src="..." alt="..." /> <Avatar.Fallback>XL</Avatar.Fallback> </Avatar> ); } ``` ### Customizing the component classes To customize the Avatar component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .avatar { @apply size-16 border-2 border-primary; } .avatar__fallback { @apply bg-gradient-to-br from-purple-500 to-pink-500; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Avatar component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/avatar.css)): #### Base Classes * `.avatar` - Base container with default size (size-10) * `.avatar__image` - Image element with aspect-square sizing * `.avatar__fallback` - Fallback container with centered content #### Size Modifiers * `.avatar--sm` - Small avatar (size-8) * `.avatar--md` - Medium avatar (default, no additional styles) * `.avatar--lg` - Large avatar (size-12) #### Variant Modifiers * `.avatar--soft` - Soft variant with lighter background #### Color Modifiers * `.avatar__fallback--default` - Default text color * `.avatar__fallback--accent` - Accent text color * `.avatar__fallback--success` - Success text color * `.avatar__fallback--warning` - Warning text color * `.avatar__fallback--danger` - Danger text color ## API Reference ### Avatar Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------- | ----------- | ---------------------- | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Avatar size | | `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Fallback color theme | | `variant` | `'default' \| 'soft'` | `'default'` | Visual style variant | | `className` | `string` | - | Additional CSS classes | ### Avatar.Image Props | Prop | Type | Default | Description | | ------------- | --------------------------------------------------- | ------- | -------------------------------------------------- | | `src` | `string` | - | Image source URL | | `srcSet` | `string` | - | The image `srcset` attribute for responsive images | | `sizes` | `string` | - | The image `sizes` attribute for responsive images | | `alt` | `string` | - | Alternative text for the image | | `onLoad` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | Callback when the image loads successfully | | `onError` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | Callback when there's an error loading the image | | `crossOrigin` | `'anonymous' \| 'use-credentials'` | - | CORS setting for the image request | | `loading` | `'eager' \| 'lazy'` | - | Native lazy loading attribute | | `className` | `string` | - | Additional CSS classes | ### Avatar.Fallback Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------- | ------- | ---------------------------------------------- | | `delayMs` | `number` | - | Delay before showing fallback (prevents flash) | | `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | Override color from parent | | `className` | `string` | - | Additional CSS classes | </page> <page url="/docs/react/components/accordion"> # Accordion **Category**: react **URL**: https://v3.heroui.com/docs/react/components/accordion **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(navigation)/accordion.mdx > A collapsible content panel for organizing information in a compact space ## Import ```tsx import { Accordion } from '@heroui/react'; ``` ### Usage ```tsx import { ArrowsRotateLeft, Box, ChevronDown, CreditCard, PlanetEarth, Receipt, ShoppingBag, } from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; const items = [ { content: "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.", icon: <ShoppingBag />, title: "How do I place an order?", }, { content: "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.", icon: <Receipt />, title: "Can I modify or cancel my order?", }, { content: "We accept all major credit cards, including Visa, Mastercard, and American Express.", icon: <CreditCard />, title: "What payment methods do you accept?", }, { content: "Shipping costs vary based on your location and the size of your order. We offer free shipping for orders over $50.", icon: <Box />, title: "How much does shipping cost?", }, { content: "Yes, we ship to most countries. Please check our shipping rates and policies for more information.", icon: <PlanetEarth />, title: "Do you ship internationally?", }, { content: "If you're not satisfied with your purchase, you can request a refund within 30 days of purchase. Please contact our customer support team for assistance.", icon: <ArrowsRotateLeft />, title: "How do I request a refund?", }, ]; export function Basic() { return ( <Accordion className="w-full max-w-md"> {items.map((item, index) => ( <Accordion.Item key={index}> <Accordion.Heading> <Accordion.Trigger> {item.icon ? ( <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span> ) : null} {item.title} <Accordion.Indicator> <ChevronDown /> </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>{item.content}</Accordion.Body> </Accordion.Panel> </Accordion.Item> ))} </Accordion> ); } ``` ### Anatomy Import the Accordion component and access all parts using dot notation. ```tsx import { Accordion } from '@heroui/react'; export default () => ( <Accordion> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body/> </Accordion.Panel> </Accordion.Item> </Accordion> ) ``` ### Surface ```tsx import { ArrowsRotateLeft, Box, ChevronDown, CreditCard, PlanetEarth, Receipt, ShoppingBag, } from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; const items = [ { content: "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.", icon: <ShoppingBag />, title: "How do I place an order?", }, { content: "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.", icon: <Receipt />, title: "Can I modify or cancel my order?", }, { content: "We accept all major credit cards, including Visa, Mastercard, and American Express.", icon: <CreditCard />, title: "What payment methods do you accept?", }, { content: "Shipping costs vary based on your location and the size of your order. We offer free shipping for orders over $50.", icon: <Box />, title: "How much does shipping cost?", }, { content: "Yes, we ship to most countries. Please check our shipping rates and policies for more information.", icon: <PlanetEarth />, title: "Do you ship internationally?", }, { content: "If you're not satisfied with your purchase, you can request a refund within 30 days of purchase. Please contact our customer support team for assistance.", icon: <ArrowsRotateLeft />, title: "How do I request a refund?", }, ]; export function Surface() { return ( <Accordion className="w-full max-w-md" variant="surface"> {items.map((item, index) => ( <Accordion.Item key={index}> <Accordion.Heading> <Accordion.Trigger> {item.icon ? ( <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span> ) : null} {item.title} <Accordion.Indicator> <ChevronDown /> </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>{item.content}</Accordion.Body> </Accordion.Panel> </Accordion.Item> ))} </Accordion> ); } ``` ### Multiple Expanded ```tsx import {Accordion} from "@heroui/react"; export function Multiple() { return ( <Accordion allowsMultipleExpanded className="w-full max-w-md"> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> Getting Started <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> Learn the basics of HeroUI and how to integrate it into your React project. This section covers installation, setup, and your first component. </Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> Core Concepts <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> Understand the fundamental concepts behind HeroUI, including the compound component pattern, styling with Tailwind CSS, and accessibility features. </Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> Advanced Usage <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> Explore advanced features like custom variants, theme customization, and integration with other libraries in your React ecosystem. </Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> Best Practices <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> Follow our recommended best practices for building performant, accessible, and maintainable applications with HeroUI components. </Accordion.Body> </Accordion.Panel> </Accordion.Item> </Accordion> ); } ``` ### Custom Indicator ```tsx "use client"; import type {Key} from "@heroui/react"; import {ChevronsDown, CircleChevronDown, Minus, Plus} from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; import React from "react"; export function CustomIndicator() { const [expandedKeys, setExpandedKeys] = React.useState<Set<Key>>(new Set([""])); return ( <Accordion className="w-full max-w-md" expandedKeys={expandedKeys} variant="surface" onExpandedChange={setExpandedKeys} > <Accordion.Item id="1"> <Accordion.Heading> <Accordion.Trigger> Using Plus/Minus Icon <Accordion.Indicator> {expandedKeys.has("1") ? <Minus /> : <Plus />} </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> This accordion uses a plus icon that transforms when expanded. The icon automatically rotates 45 degrees to form an X. </Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item id="2"> <Accordion.Heading> <Accordion.Trigger> Using Caret Icon <Accordion.Indicator> <CircleChevronDown /> </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> This item uses a caret icon for the indicator. The rotation animation is applied automatically. </Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item id="3"> <Accordion.Heading> <Accordion.Trigger> Using Arrow Icon <Accordion.Indicator> <ChevronsDown /> </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> This item uses an arrow icon. Any icon you pass will receive the rotation animation when the item expands. </Accordion.Body> </Accordion.Panel> </Accordion.Item> </Accordion> ); } ``` ### Disabled State ```tsx import {Accordion} from "@heroui/react"; export function Disabled() { return ( <div className="flex w-full flex-col items-center gap-8"> <div className="w-full max-w-md space-y-2"> <h3 className="text-sm font-medium text-muted">Entire accordion disabled</h3> <Accordion isDisabled className="w-full max-w-md"> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> Disabled Item 1 <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> This content cannot be accessed when the accordion is disabled. </Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> Disabled Item 2 <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> This content cannot be accessed when the accordion is disabled. </Accordion.Body> </Accordion.Panel> </Accordion.Item> </Accordion> </div> <div className="w-full max-w-md space-y-2"> <h3 className="text-sm font-medium text-muted">Individual items disabled</h3> <Accordion className="w-full max-w-md"> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> Active Item <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>This item is active and can be toggled normally.</Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item isDisabled> <Accordion.Heading> <Accordion.Trigger> Disabled Item <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> This content cannot be accessed when the item is disabled. </Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> Another Active Item <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>This item is also active and can be toggled.</Accordion.Body> </Accordion.Panel> </Accordion.Item> </Accordion> </div> </div> ); } ``` ### FAQ Layout ```tsx import {ChevronDown} from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; export function FAQ() { const categories = [ { items: [ { content: "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.", title: "How do I place an order?", }, { content: "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.", title: "Can I modify or cancel my order?", }, ], title: "General", }, { items: [ { content: "You can purchase a license directly from our website. Select the license type that fits your needs and proceed to checkout.", title: "How do I purchase a license?", }, { content: "A standard license is for personal use or small projects, while a pro license includes commercial use rights and priority support.", title: "What is the difference between a standard and a pro license?", }, ], title: "Licensing", }, { items: [ { content: "You can reach our support team through the contact form on our website, or email us directly at support@example.com.", title: "How do I get support?", }, ], title: "Support", }, ]; return ( <div className="flex w-full flex-col gap-6"> <div className="flex flex-col gap-1"> <h2 className="text-2xl font-bold">Frequently Asked Questions</h2> <p className="mb-4 text-lg font-medium text-muted"> Everything you need to know about licensing and usage. </p> </div> {categories.map((category) => ( <div key={category.title}> <p className="text-md mb-2 font-medium text-muted">{category.title}</p> <Accordion className="w-full" variant="surface"> {category.items.map((item, index) => ( <Accordion.Item key={index}> <Accordion.Heading> <Accordion.Trigger> {item.title} <Accordion.Indicator> <ChevronDown /> </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>{item.content}</Accordion.Body> </Accordion.Panel> </Accordion.Item> ))} </Accordion> </div> ))} </div> ); } ``` ### Custom Styles ```tsx import {ChevronDown} from "@gravity-ui/icons"; import {Accordion, cn} from "@heroui/react"; const items = [ { content: "Stay informed about your account activity with real-time notifications. ", iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png", subtitle: "Receive account activity updates", title: "Set Up Notifications", }, { content: "Enhance your browsing experience by installing our official browser extension", iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png", subtitle: "Connect you browser to your account", title: "Set up Browser Extension", }, { content: "Begin your journey into the world of digital collectibles by creating your first NFT. ", iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png", subtitle: "Create your first collectible", title: "Mint Collectible", }, ]; export function CustomStyles() { return ( <Accordion className="bg-surface-1/10 w-full max-w-md rounded-2xl" variant="surface"> {items.map((item, index) => ( <Accordion.Item key={index} className={cn( "group/item", "first:[&_[data-slot=accordion-trigger]]:rounded-t-2xl", // First trigger we want to round the top "last:[&:not(:has([data-slot=accordion-trigger][aria-expanded='true']))_[data-slot=accordion-trigger]]:rounded-b-2xl", // Last trigger we want to round the bottom )} > <Accordion.Heading> <Accordion.Trigger className="hover:bgsurface group flex items-center gap-2 transition-none"> {item.iconUrl ? ( <img alt={item.title} className="h-11 w-11 transition-[scale,rotate] duration-300 ease-out group-hover/item:scale-120 group-hover/item:-rotate-10 group-hover/item:drop-shadow-lg" src={item.iconUrl} /> ) : null} <div className="flex flex-col gap-0"> <span className="leading-5 font-medium">{item.title}</span> <span className="leading-6 font-normal text-muted/80">{item.subtitle}</span> </div> <Accordion.Indicator className="text-muted/50 [&>svg]:size-4"> <ChevronDown /> </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body className="text-muted/80">{item.content}</Accordion.Body> </Accordion.Panel> </Accordion.Item> ))} </Accordion> ); } ``` ### Without Separator ```tsx import {ChevronDown, CreditCard, Receipt, ShoppingBag} from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; const items = [ { content: "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.", icon: <ShoppingBag />, title: "How do I place an order?", }, { content: "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.", icon: <Receipt />, title: "Can I modify or cancel my order?", }, { content: "We accept all major credit cards, including Visa, Mastercard, and American Express.", icon: <CreditCard />, title: "What payment methods do you accept?", }, ]; export function WithoutSeparator() { return ( <Accordion hideSeparator className="w-full max-w-md"> {items.map((item, index) => ( <Accordion.Item key={index}> <Accordion.Heading> <Accordion.Trigger> {item.icon ? ( <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span> ) : null} {item.title} <Accordion.Indicator> <ChevronDown /> </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>{item.content}</Accordion.Body> </Accordion.Panel> </Accordion.Item> ))} </Accordion> ); } ``` ### Custom Render Function ```tsx "use client"; import { ArrowsRotateLeft, Box, ChevronDown, CreditCard, PlanetEarth, Receipt, ShoppingBag, } from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; const items = [ { content: "Browse our products, add items to your cart, and proceed to checkout. You'll need to provide shipping and payment information to complete your purchase.", icon: <ShoppingBag />, title: "How do I place an order?", }, { content: "Yes, you can modify or cancel your order before it's shipped. Once your order is processed, you can't make changes.", icon: <Receipt />, title: "Can I modify or cancel my order?", }, { content: "We accept all major credit cards, including Visa, Mastercard, and American Express.", icon: <CreditCard />, title: "What payment methods do you accept?", }, { content: "Shipping costs vary based on your location and the size of your order. We offer free shipping for orders over $50.", icon: <Box />, title: "How much does shipping cost?", }, { content: "Yes, we ship to most countries. Please check our shipping rates and policies for more information.", icon: <PlanetEarth />, title: "Do you ship internationally?", }, { content: "If you're not satisfied with your purchase, you can request a refund within 30 days of purchase. Please contact our customer support team for assistance.", icon: <ArrowsRotateLeft />, title: "How do I request a refund?", }, ]; export function CustomRenderFunction() { return ( <Accordion className="w-full max-w-md" render={(props) => <div data-custom="accordion" {...props} />} > {items.map((item, index) => ( <Accordion.Item key={index} render={(props) => <div data-custom="item" {...props} />}> <Accordion.Heading render={(props) => <div data-custom="heading" {...props} />}> <Accordion.Trigger render={(props) => <button data-custom="trigger" {...props} />}> {item.icon ? ( <span className="mr-3 size-4 shrink-0 text-muted">{item.icon}</span> ) : null} {item.title} <Accordion.Indicator> <ChevronDown /> </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel render={(props) => <div data-custom="panel" {...props} />}> <Accordion.Body>{item.content}</Accordion.Body> </Accordion.Panel> </Accordion.Item> ))} </Accordion> ); } ``` ## Related Components * **DisclosureGroup**: Group of collapsible panels * **Disclosure**: Single collapsible content section ## Styling ### Passing Tailwind CSS classes ```tsx "use client"; import { Accordion, cn } from "@heroui/react"; import {Icon} from "@iconify/react"; const items = [ { content: "Stay informed about your account activity with real-time notifications. You'll receive instant alerts for important events like transactions, new messages, security updates, and system announcements. ", iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png", title: "Set Up Notifications", subtitle: "Receive account activity updates", }, { content: "Enhance your browsing experience by installing our official browser extension. The extension provides seamless integration with your account, allowing you to receive notifications directly in your browser, quickly access your dashboard, and interact with web3 applications securely. Compatible with Chrome, Firefox, Edge, and Brave browsers.", iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png", title: "Set up Browser Extension", subtitle: "Connect you browser to your account", }, { content: "Begin your journey into the world of digital collectibles by creating your first NFT. Our intuitive minting process guides you through uploading your artwork, setting metadata, choosing royalty percentages, and deploying to the blockchain. Whether you're an artist, creator, or collector, you'll find all the tools you need to bring your digital assets to life. Your collectibles are stored on IPFS for permanent decentralized storage.", iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png", title: "Mint Collectible", subtitle: "Create your first collectible", }, ]; export function CustomStyles() { return ( <Accordion className="bg-surface-secondary w-full max-w-md rounded-2xl" variant="surface"> {items.map((item, index) => ( <Accordion.Item key={index} className={cn( "group/item", "first:[&_[data-slot=accordion-trigger]]:rounded-t-2xl", // First trigger we want to round the top "last:[&:not(:has([data-slot=accordion-trigger][aria-expanded='true']))_[data-slot=accordion-trigger]]:rounded-b-2xl", // Last trigger we want to round the bottom )} > <Accordion.Heading> <Accordion.Trigger className="hover:bg-surface-tertiary group flex items-center gap-2"> {item.iconUrl ? ( <img alt={item.title} className="group-hover/item:scale-120 group-hover/item:-rotate-10 h-11 w-11 transition-[scale,rotate] duration-300 ease-out group-hover/item:drop-shadow-lg" src={item.iconUrl} /> ) : null} <div className="flex flex-col gap-0"> <span className="font-medium leading-5">{item.title}</span> <span className="text-muted/80 font-normal leading-6">{item.subtitle}</span> </div> <Accordion.Indicator className="text-muted/50 [&>svg]:size-4"> <Icon icon="gravity-ui:chevron-down" /> </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body className="text-muted/80">{item.content}</Accordion.Body> </Accordion.Panel> </Accordion.Item> ))} </Accordion> ); } ``` ### Customizing the component classes To customize the Accordion component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .accordion { @apply rounded-xl bg-gray-50; } .accordion__trigger { @apply font-semibold text-lg; } .accordion--outline { @apply shadow-lg border-2; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Accordion component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/accordion.css)): #### Base Classes * `.accordion` - Base accordion container * `.accordion__body` - Content body container * `.accordion__heading` - Heading wrapper * `.accordion__indicator` - Expand/collapse indicator icon * `.accordion__item` - Individual accordion item * `.accordion__panel` - Collapsible panel container * `.accordion__trigger` - Clickable trigger button #### Variant Classes * `.accordion--outline` - Outline variant with border and background #### State Classes * `.accordion__trigger[aria-expanded="true"]` - Expanded state * `.accordion__panel[aria-hidden="false"]` - Panel visible state ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Hover**: `:hover` or `[data-hovered="true"]` on trigger * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger * **Disabled**: `:disabled` or `[aria-disabled="true"]` on trigger * **Expanded**: `[aria-expanded="true"]` on trigger ## API Reference ### Accordion Props | Prop | Type | Default | Description | | ------------------------ | ---------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------- | | `allowsMultipleExpanded` | `boolean` | `false` | Whether multiple items can be expanded at once | | `defaultExpandedKeys` | `Iterable<Key>` | - | The initial expanded keys | | `expandedKeys` | `Iterable<Key>` | - | The controlled expanded keys | | `onExpandedChange` | `(keys: Set<Key>) => void` | - | Handler called when expanded keys change | | `isDisabled` | `boolean` | `false` | Whether the entire accordion is disabled | | `variant` | `"default" \| "surface"` | `"default"` | The visual variant of the accordion | | `hideSeparator` | `boolean` | `false` | Hide separator lines between accordion items | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | The accordion items | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Accordion.Item Props | Prop | Type | Default | Description | | ------------------ | -------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | `id` | `Key` | - | Unique identifier for the item | | `isDisabled` | `boolean` | `false` | Whether this item is disabled | | `defaultExpanded` | `boolean` | `false` | Whether item is initially expanded | | `isExpanded` | `boolean` | - | Controlled expanded state | | `onExpandedChange` | `(isExpanded: boolean) => void` | - | Handler for expanded state changes | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | The item content | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionItemRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Accordion.Trigger Props | Prop | Type | Default | Description | | ------------ | -------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Trigger content or render function | | `onPress` | `() => void` | - | Additional press handler | | `isDisabled` | `boolean` | - | Whether trigger is disabled | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TriggerRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Accordion.Panel Props | Prop | Type | Default | Description | | ----------- | --------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Panel content | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionPanelRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Accordion.Indicator Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom indicator icon | ### Accordion.Body Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Body content | </page> <page url="/docs/react/components/breadcrumbs"> # Breadcrumbs **Category**: react **URL**: https://v3.heroui.com/docs/react/components/breadcrumbs **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(navigation)/breadcrumbs.mdx > Navigation breadcrumbs showing the current page's location within a hierarchy ## Import ```tsx import { Breadcrumbs } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export default function BreadcrumbsBasic() { return ( <Breadcrumbs> <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item> <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item> <Breadcrumbs.Item href="#">Electronics</Breadcrumbs.Item> <Breadcrumbs.Item>Laptop</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ### Anatomy Import the Breadcrumbs component and access all parts using dot notation. ```tsx import { Breadcrumbs } from '@heroui/react'; export default () => ( <Breadcrumbs> <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item> <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item> <Breadcrumbs.Item>Current Page</Breadcrumbs.Item> </Breadcrumbs> ) ``` ### Navigation Levels ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export default function BreadcrumbsLevel2() { return ( <Breadcrumbs> <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item> <Breadcrumbs.Item>Current Page</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export default function BreadcrumbsLevel3() { return ( <Breadcrumbs> <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item> <Breadcrumbs.Item href="#">Category</Breadcrumbs.Item> <Breadcrumbs.Item>Current Page</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ### Custom Separator ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export default function BreadcrumbsCustomSeparator() { return ( <Breadcrumbs separator={ <svg viewBox="0 0 256 512" xmlns="http://www.w3.org/2000/svg"> <path d="M249.3 235.8c10.2 12.6 9.5 31.1-2.2 42.8l-128 128c-9.2 9.2-22.9 11.9-34.9 6.9S64.5 396.9 64.5 384l0-256c0-12.9 7.8-24.6 19.8-29.6s25.7-2.2 34.9 6.9l128 128 2.2 2.4z" /> </svg> } > <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item> <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item> <Breadcrumbs.Item href="#">Electronics</Breadcrumbs.Item> <Breadcrumbs.Item>Laptop</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ### Disabled State ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export default function BreadcrumbsDisabled() { return ( <Breadcrumbs isDisabled> <Breadcrumbs.Item href="#">Home</Breadcrumbs.Item> <Breadcrumbs.Item href="#">Products</Breadcrumbs.Item> <Breadcrumbs.Item href="#">Electronics</Breadcrumbs.Item> <Breadcrumbs.Item>Laptop</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ### Custom Render Function ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export function CustomRenderFunction() { return ( <Breadcrumbs render={(props) => <ol {...props} data-custom="foo" />}> <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}> Home </Breadcrumbs.Item> <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}> Products </Breadcrumbs.Item> <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}> Electronics </Breadcrumbs.Item> <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}> Laptop </Breadcrumbs.Item> </Breadcrumbs> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import { Breadcrumbs } from '@heroui/react'; function CustomBreadcrumbs() { return ( <Breadcrumbs className="gap-2"> <Breadcrumbs.Item href="#" className="text-blue-600"> Home </Breadcrumbs.Item> <Breadcrumbs.Item>Current</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ### Customizing the component classes To customize the Breadcrumbs component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .breadcrumbs { @apply gap-4 text-lg; } .breadcrumbs__link { @apply font-semibold; } .breadcrumbs__separator { @apply text-blue-500; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Breadcrumbs component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/breadcrumbs.css)): #### Base Classes * `.breadcrumbs` - Base breadcrumbs container * `.breadcrumbs__item` - Individual breadcrumb item wrapper * `.breadcrumbs__link` - Breadcrumb link element * `.breadcrumbs__separator` - Separator icon between items #### State Classes * `.breadcrumbs__link[data-current="true"]` - Current page indicator (not a link) ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Current**: `[data-current="true"]` on link (indicates current page) * **Hover**: Link elements support standard hover states * **Disabled**: `isDisabled` prop disables all links ## API Reference ### Breadcrumbs Props | Prop | Type | Default | Description | | ------------ | ----------------------------------------------------------------- | ------------------ | --------------------------------------------------------------- | | `separator` | `ReactNode` | chevron-right icon | Custom separator between breadcrumb items | | `isDisabled` | `boolean` | `false` | Whether all breadcrumb links are disabled | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | The breadcrumb items | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | Overrides the default DOM element with a custom render function | ### Breadcrumbs.Item Props | Prop | Type | Default | Description | | ----------- | ----------------------------------------------------------------------------- | ------- | --------------------------------------------------------------- | | `href` | `string` | - | The URL to link to (omit for current page) | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Item content or render function | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, BreadcrumbRenderProps>` | - | Overrides the default DOM element with a custom render function | ## Accessibility Breadcrumbs uses React Aria Components' Breadcrumbs primitive, which provides: * Proper ARIA attributes for navigation landmarks * Current page indication via `aria-current="page"` * Keyboard navigation support * Screen reader announcements for navigation context The last breadcrumb item (without `href`) automatically becomes the current page indicator. </page> <page url="/docs/react/components/disclosure-group"> # DisclosureGroup **Category**: react **URL**: https://v3.heroui.com/docs/react/components/disclosure-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(navigation)/disclosure-group.mdx > Container that manages multiple Disclosure items with coordinated expanded states ## Import ```tsx import { DisclosureGroup } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {QrCode} from "@gravity-ui/icons"; import {Button, Disclosure, DisclosureGroup, Separator} from "@heroui/react"; import {Icon} from "@iconify/react"; import React from "react"; import {cn} from "tailwind-variants"; export function Basic() { const [expandedKeys, setExpandedKeys] = React.useState(new Set<string | number>(["preview"])); return ( <div className="w-full max-w-md"> <div className="flex flex-col gap-4 bg-transparent p-4"> <DisclosureGroup expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}> <Disclosure aria-label="Preview HeroUI Native" id="preview"> <Disclosure.Heading> <Button slot="trigger" variant={expandedKeys.has("preview") ? "secondary" : "tertiary"} className={cn("w-full border-none", { "bg-transparent": !expandedKeys.has("preview"), })} > <div className="flex w-full items-center justify-start gap-2"> <QrCode /> Preview HeroUI Native </div> <Disclosure.Indicator className="text-muted" /> </Button> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center"> <p className="text-sm text-muted"> Scan this QR code with your camera app to preview the HeroUI native components. </p> <img alt="Expo Go QR Code" className="aspect-square w-full max-w-54 object-cover" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png" /> <p className="text-sm text-muted">Expo must be installed on your device.</p> <Button className="mt-4" variant="primary"> <Icon className="[&_path]:fill-accent-foreground" icon="logos:expo-icon" /> Preview on Expo Go </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> <Separator className="my-2" /> <Disclosure id="download"> <Disclosure.Heading aria-label="Download HeroUI Native"> <Button slot="trigger" variant={expandedKeys.has("download") ? "secondary" : "tertiary"} className={cn("w-full border-none", { "bg-transparent": !expandedKeys.has("download"), })} > <div className="flex w-full items-center justify-start gap-2"> <Icon icon="tabler:brand-apple-filled" /> Download App </div> <Disclosure.Indicator className="text-muted" /> </Button> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center"> <p className="text-sm text-muted"> Download the HeroUI native app to explore our mobile components directly on your device. </p> <img alt="App Store QR Code" className="aspect-square w-full max-w-54 object-cover" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png" /> <p className="text-sm text-muted">Available on iOS and Android devices.</p> <Button className="mt-4" variant="primary"> <Icon icon="tabler:brand-apple-filled" /> Download on App Store </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> </DisclosureGroup> </div> </div> ); } ``` ### Anatomy Import all parts and piece them together. ```tsx import {DisclosureGroup, Disclosure} from '@heroui/react'; export default () => ( <DisclosureGroup> <Disclosure id="item1"> <Disclosure.Heading> <Disclosure.Trigger> <Disclosure.Indicator /> </Disclosure.Trigger> </Disclosure.Heading> <Disclosure.Content /> </Disclosure> </DisclosureGroup> ) ``` ### Controlled You can control which disclosures are expanded with external navigation controls using the `expandedKeys` and `onExpandedChange` props. ```tsx "use client"; import {ChevronDown, ChevronUp, QrCode} from "@gravity-ui/icons"; import { Button, Disclosure, DisclosureGroup, Separator, useDisclosureGroupNavigation, } from "@heroui/react"; import {Icon} from "@iconify/react"; import React from "react"; import {cn} from "tailwind-variants"; export function Controlled() { const [expandedKeys, setExpandedKeys] = React.useState(new Set<string | number>(["preview"])); const itemIds = ["preview", "download"]; // Track our disclosure items const {isNextDisabled, isPrevDisabled, onNext, onPrevious} = useDisclosureGroupNavigation({ expandedKeys, itemIds, onExpandedChange: setExpandedKeys, }); return ( <div className="w-full max-w-md"> <div className="flex flex-col gap-4 rounded-3xl p-4"> <div className="mb-2 flex items-center justify-between"> <h3 className="text-lg font-semibold">HeroUI Native</h3> <div className="flex gap-2"> <Button aria-label="Previous disclosure" isDisabled={isPrevDisabled} size="sm" variant="secondary" onPress={onPrevious} > <ChevronUp className="size-4" /> </Button> <Button aria-label="Next disclosure" isDisabled={isNextDisabled} size="sm" variant="secondary" onPress={onNext} > <ChevronDown className="size-4" /> </Button> </div> </div> <DisclosureGroup expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}> <Disclosure aria-label="Preview HeroUI Native" id="preview"> <Disclosure.Heading> <Button slot="trigger" variant={expandedKeys.has("preview") ? "secondary" : "tertiary"} className={cn("w-full border-none", { "bg-transparent": !expandedKeys.has("preview"), })} > <div className="flex w-full items-center justify-start gap-2"> <QrCode /> Preview HeroUI Native </div> <Disclosure.Indicator className="text-muted" /> </Button> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center"> <p className="text-sm text-muted"> Scan this QR code with your camera app to preview the HeroUI native components. </p> <img alt="Expo Go QR Code" className="aspect-square w-full max-w-54 object-cover" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png" /> <p className="text-sm text-muted">Expo must be installed on your device.</p> <Button className="mt-4" variant="primary"> <Icon className="[&_path]:fill-accent-foreground" icon="logos:expo-icon" /> Preview on Expo Go </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> <Separator className="my-2" /> <Disclosure id="download"> <Disclosure.Heading aria-label="Download HeroUI Native"> <Button slot="trigger" variant={expandedKeys.has("download") ? "secondary" : "tertiary"} className={cn("w-full border-none", { "bg-transparent": !expandedKeys.has("download"), })} > <div className="flex w-full items-center justify-start gap-2"> <Icon icon="tabler:brand-apple-filled" /> Download HeroUI Native </div> <Disclosure.Indicator className="text-muted" /> </Button> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="mx-2 flex flex-col items-center gap-2 p-4 text-center"> <p className="text-sm text-muted"> Scan this QR code with your camera app to preview the HeroUI native components. </p> <img alt="Expo Go QR Code" className="aspect-square w-full max-w-54 object-cover" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png" /> <p className="text-sm text-muted">Expo must be installed on your device.</p> <Button className="mt-4" variant="primary"> <Icon icon="tabler:brand-apple-filled" /> Download on App Store </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> </DisclosureGroup> </div> </div> ); } ``` ## Related Components * **Accordion**: Collapsible content sections * **Disclosure**: Single collapsible content section * **Button**: Allows a user to perform an action ## Styling ### Passing Tailwind CSS classes ```tsx import { DisclosureGroup, Disclosure, DisclosureTrigger, DisclosurePanel } from '@heroui/react'; function CustomDisclosureGroup() { return ( <DisclosureGroup className="border rounded-lg p-4 space-y-2"> <Disclosure id="first" className="border-b pb-2"> <DisclosureTrigger>Item 1</DisclosureTrigger> <DisclosurePanel>Content 1</DisclosurePanel> </Disclosure> <Disclosure id="second"> <DisclosureTrigger>Item 2</DisclosureTrigger> <DisclosurePanel>Content 2</DisclosurePanel> </Disclosure> </DisclosureGroup> ); } ``` ### Customizing the component classes To customize the DisclosureGroup component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .disclosure-group { @apply w-full; /* Performance optimization */ contain: layout style; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The DisclosureGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/disclosure-group.css)): #### Base Classes * `.disclosure-group` - Base container styles with layout containment ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Disabled**: `:disabled` or `[aria-disabled="true"]` on entire group * **Expanded Management**: Automatically manages `[data-expanded]` states on child Disclosure items ## API Reference ### DisclosureGroup Props | Prop | Type | Default | Description | | ------------------------ | ----------------------------- | ------- | ----------------------------------------------------- | | `expandedKeys` | `Set<Key>` | - | The currently expanded items (controlled) | | `defaultExpandedKeys` | `Iterable<Key>` | - | The initially expanded items (uncontrolled) | | `onExpandedChange` | `(keys: Set<Key>) => void` | - | Handler called when expanded items change | | `allowsMultipleExpanded` | `boolean` | `false` | Whether multiple items can be expanded simultaneously | | `isDisabled` | `boolean` | `false` | Whether all disclosures in the group are disabled | | `children` | `ReactNode \| RenderFunction` | - | Disclosure items to render | | `className` | `string` | - | Additional CSS classes | ### RenderProps When using the render prop pattern, these values are provided: | Prop | Type | Description | | -------------- | ---------- | ----------------------------- | | `expandedKeys` | `Set<Key>` | Currently expanded item keys | | `isDisabled` | `boolean` | Whether the group is disabled | </page> <page url="/docs/react/components/disclosure"> # Disclosure **Category**: react **URL**: https://v3.heroui.com/docs/react/components/disclosure **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(navigation)/disclosure.mdx > A disclosure is a collapsible section with a header containing a heading and a trigger button, and a panel that wraps the content. ## Import ```tsx import { Disclosure } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {QrCode} from "@gravity-ui/icons"; import {Button, Disclosure} from "@heroui/react"; import {Icon} from "@iconify/react"; import React from "react"; export function Basic() { const [isExpanded, setIsExpanded] = React.useState(true); return ( <div className="w-full max-w-md text-center"> <Disclosure isExpanded={isExpanded} onExpandedChange={setIsExpanded}> <Disclosure.Heading> <Button slot="trigger" variant="secondary"> <QrCode /> Preview HeroUI Native <Disclosure.Indicator /> </Button> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="shadow-panel flex flex-col items-center rounded-3xl bg-surface p-4 text-center"> <p className="text-sm text-muted"> Scan this QR code with your camera app to preview the HeroUI native components. </p> <img alt="Expo Go QR Code" className="aspect-square w-full max-w-54 object-cover" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png" /> <p className="text-sm text-muted">Expo must be installed on your device.</p> <Button className="mt-4" variant="primary"> <Icon icon="tabler:brand-apple-filled" /> Download on App Store </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> </div> ); } ``` ### Anatomy Import the Disclosure component and access all parts using dot notation. ```tsx import { Disclosure } from '@heroui/react'; export default () => ( <Disclosure> <Disclosure.Heading> <Disclosure.Trigger> <Disclosure.Indicator /> </Disclosure.Trigger> </Disclosure.Heading> <Disclosure.Content/> </Disclosure> ) ``` ## Related Components * **Accordion**: Collapsible content sections * **DisclosureGroup**: Group of collapsible panels * **Button**: Allows a user to perform an action ### Custom Render Function ```tsx "use client"; import {QrCode} from "@gravity-ui/icons"; import {Button, Disclosure} from "@heroui/react"; import {Icon} from "@iconify/react"; import React from "react"; export function CustomRenderFunction() { const [isExpanded, setIsExpanded] = React.useState(true); return ( <div className="w-full max-w-md text-center"> <Disclosure isExpanded={isExpanded} render={(props) => <div {...props} data-custom="foo" />} onExpandedChange={setIsExpanded} > <Disclosure.Heading> <Button slot="trigger" variant="secondary"> <QrCode /> Preview HeroUI Native <Disclosure.Indicator /> </Button> </Disclosure.Heading> <Disclosure.Content render={(props) => <div data-custom="bar" {...props} />}> <Disclosure.Body className="shadow-panel flex flex-col items-center rounded-3xl bg-surface p-4 text-center"> <p className="text-sm text-muted"> Scan this QR code with your camera app to preview the HeroUI native components. </p> <img alt="Expo Go QR Code" className="aspect-square w-full max-w-54 object-cover" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/images/qr-code-native.png" /> <p className="text-sm text-muted">Expo must be installed on your device.</p> <Button className="mt-4" variant="primary"> <Icon icon="tabler:brand-apple-filled" /> Download on App Store </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> </div> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import { Disclosure } from '@heroui/react'; function CustomDisclosure() { return ( <Disclosure className="border rounded-lg p-4"> <Disclosure.Heading> <Disclosure.Trigger className="text-lg font-semibold"> Click to expand <Disclosure.Indicator /> </Disclosure.Trigger> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="mt-4 text-gray-600"> Hidden content </Disclosure.Body> </Disclosure.Content> </Disclosure> ); } ``` ### Customizing the component classes To customize the Disclosure component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .disclosure { @apply relative; } .disclosure__trigger { @apply cursor-pointer; } .disclosure__indicator { @apply transition-transform duration-300; } .disclosure__content { @apply overflow-hidden transition-all; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Disclosure component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/disclosure.css)): #### Base Classes * `.disclosure` - Base container styles * `.disclosure__heading` - Heading wrapper * `.disclosure__trigger` - Trigger button styles * `.disclosure__indicator` - Chevron indicator styles * `.disclosure__content` - Content container with animations ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Expanded**: `[data-expanded="true"]` on indicator for rotation * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger * **Disabled**: `:disabled` or `[aria-disabled="true"]` on trigger * **Hidden**: `[aria-hidden="false"]` on content for visibility ## API Reference ### Disclosure Props | Prop | Type | Default | Description | | ------------------ | ----------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | `isExpanded` | `boolean` | `false` | Controls the expanded state | | `onExpandedChange` | `(isExpanded: boolean) => void` | - | Callback when expanded state changes | | `isDisabled` | `boolean` | `false` | Whether the disclosure is disabled | | `children` | `ReactNode \| RenderFunction` | - | Content to render | | `className` | `string` | - | Additional CSS classes | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### DisclosureTrigger Props | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | ---------------------- | | `children` | `ReactNode \| RenderFunction` | - | Trigger content | | `className` | `string` | - | Additional CSS classes | ### DisclosureContent Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------- | | `children` | `ReactNode` | - | Content to show/hide | | `className` | `string` | - | Additional CSS classes | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureContentRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### RenderProps When using the render prop pattern, these values are provided: | Prop | Type | Description | | ------------ | --------- | ------------------------------ | | `isExpanded` | `boolean` | Current expanded state | | `isDisabled` | `boolean` | Whether disclosure is disabled | </page> <page url="/docs/react/components/link"> # Link **Category**: react **URL**: https://v3.heroui.com/docs/react/components/link **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(navigation)/link.mdx > A styled anchor component for navigation with built-in icon support ## Import ```tsx import { Link } from '@heroui/react'; ``` ### Usage ```tsx import {Link} from "@heroui/react"; export function LinkBasic() { return ( <Link href="#"> Call to action <Link.Icon /> </Link> ); } ``` ### Anatomy Import the Link component and access all parts using dot notation. ```tsx import { Link } from '@heroui/react'; export default () => ( <Link href="#"> Call to action <Link.Icon /> </Link> ); ``` ### Custom Icon ```tsx import {ArrowUpRightFromSquare, Link as LinkIcon} from "@gravity-ui/icons"; import {Link} from "@heroui/react"; export function LinkCustomIcon() { return ( <div className="flex flex-col gap-3"> <Link href="#"> External link <Link.Icon className="ml-1.5 size-3"> <ArrowUpRightFromSquare /> </Link.Icon> </Link> <Link className="gap-1" href="#"> Go to page <Link.Icon className="size-3"> <LinkIcon /> </Link.Icon> </Link> </div> ); } ``` ### Icon Placement ```tsx import {Link} from "@heroui/react"; export function LinkIconPlacement() { return ( <div className="flex flex-col gap-3"> <Link href="#"> Icon at end (default) <Link.Icon /> </Link> <Link className="gap-1" href="#"> <Link.Icon /> Icon at start </Link> </div> ); } ``` ### Text Decoration with Tailwind CSS ```tsx import {Link} from "@heroui/react"; export function LinkUnderlineAndOffset() { return ( <div className="flex flex-col gap-6"> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Always visible underline</p> <Link className="underline" href="#"> Underline always visible <Link.Icon /> </Link> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Underline visible on hover</p> <Link className="no-underline hover:underline" href="#"> Hover to see the underline <Link.Icon /> </Link> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">No underline</p> <Link className="no-underline" href="#"> Link without any underline <Link.Icon /> </Link> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Changing the underline offset</p> <div className="flex flex-col gap-3"> <Link className="underline-offset-1 hover:underline" href="#"> Offset 1 (1px space) <Link.Icon /> </Link> <Link className="underline-offset-2 hover:underline" href="#"> Offset 2 (2px space) <Link.Icon /> </Link> <Link className="underline-offset-3 hover:underline" href="#"> Offset 3 (3px space) <Link.Icon /> </Link> <Link className="underline-offset-4 hover:underline" href="#"> Offset 4 (4px space) <Link.Icon /> </Link> </div> </div> </div> ); } ``` **Text Decoration Line:** * `underline` - Always visible underline * `no-underline` - Remove underline * `hover:underline` - Underline appears on hover **Text Decoration Color:** * `decoration-primary`, `decoration-secondary`, etc. - Set underline color using theme colors * `decoration-muted/50` - Use opacity modifiers for semi-transparent underlines **Text Decoration Style:** * `decoration-solid` - Solid line (default) * `decoration-double` - Double line * `decoration-dotted` - Dotted line * `decoration-dashed` - Dashed line * `decoration-wavy` - Wavy line **Text Decoration Thickness:** * `decoration-1`, `decoration-2`, `decoration-4`, etc. - Control underline thickness **Underline Offset:** * `underline-offset-1`, `underline-offset-2`, `underline-offset-4`, etc. - Adjust spacing between text and underline For more details, see the Tailwind CSS documentation: * [text-decoration-line](https://tailwindcss.com/docs/text-decoration-line) * [text-decoration-color](https://tailwindcss.com/docs/text-decoration-color) * [text-decoration-style](https://tailwindcss.com/docs/text-decoration-style) * [text-decoration-thickness](https://tailwindcss.com/docs/text-decoration-thickness) * [text-underline-offset](https://tailwindcss.com/docs/text-underline-offset) Available BEM classes: * Base: `link` * Icon: `link__icon` ## Related Components * **Breadcrumbs**: Display the user's current location within a hierarchy ### Custom Render Function ```tsx "use client"; import {Link} from "@heroui/react"; export function CustomRenderFunction() { return ( <Link href="#" render={(props) => <span {...props} data-custom="foo" />}> Call to action <Link.Icon /> </Link> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import { Link } from '@heroui/react'; function CustomLink() { return ( <Link href="#" className="text-lg font-bold text-accent hover:text-accent/80" > Custom styled link </Link> ); } ``` ### Customizing the component classes To customize the Link component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .link { @apply font-semibold no-underline hover:underline; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Link component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/link.css)): #### Base Classes * `.link` - Base link styles * `.link__icon` - Link icon styles ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` * **Disabled**: `:disabled` or `[aria-disabled="true"]` ## API Reference ### Link Props | Prop | Type | Default | Description | | ------------ | ----------------------------------------------------------------------- | --------- | ---------------------------------------------------------------- | | `href` | `string` | - | Destination URL for the anchor | | `target` | `string` | `"_self"` | Controls where to open the linked document | | `rel` | `string` | - | Relationship between the current and linked documents | | `download` | `boolean \| string` | - | Prompts file download instead of navigation | | `isDisabled` | `boolean` | `false` | Disables pointer and keyboard interaction | | `className` | `string` | - | Custom classes merged with the default styles | | `children` | `React.ReactNode` | - | Content rendered inside the link | | `onPress` | `(e: PressEvent) => void` | - | Fired when the link is activated | | `autoFocus` | `boolean` | - | Whether the element should receive focus on render | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, LinkRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Link.Icon Props | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | --------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Custom icon element; defaults to the built-in arrow icon when omitted | | `className` | `string` | - | Additional CSS classes | ### Using with Routing Libraries Use variant functions to style framework-specific links like Next.js: ```tsx import { Link } from '@heroui/react'; import { linkVariants } from '@heroui/styles'; import NextLink from 'next/link'; export default function Demo() { const slots = linkVariants(); return ( <NextLink className={slots.base()} href="/about"> About Page <Link.Icon className={slots.icon()} /> </NextLink> ); } ``` ### Direct Class Application Since HeroUI uses [BEM](https://getbem.com/) classes, you can apply Link styles directly to any link element: ```tsx import NextLink from 'next/link'; // Apply classes directly with Tailwind utilities export default function Demo() { return ( <NextLink href="/about" className="link hover:underline underline-offset-2"> About Page </NextLink> ); } // Or with a native anchor export default function NativeLink() { return ( <a href="/about" className="link underline decoration-primary underline-offset-4"> About Page <Link.Icon className="link__icon" /> </a> ); } ``` </page> <page url="/docs/react/components/pagination"> # Pagination **Category**: react **URL**: https://v3.heroui.com/docs/react/components/pagination **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(navigation)/pagination.mdx > Page navigation with composable page links, previous/next buttons, and ellipsis indicators ## Import ```tsx import { Pagination } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {Pagination} from "@heroui/react"; import {useState} from "react"; export function PaginationBasic() { const [page, setPage] = useState(1); const totalPages = 3; return ( <Pagination className="justify-center"> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}> <Pagination.PreviousIcon /> <span>Previous</span> </Pagination.Previous> </Pagination.Item> {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => ( <Pagination.Item key={p}> <Pagination.Link isActive={p === page} onPress={() => setPage(p)}> {p} </Pagination.Link> </Pagination.Item> ))} <Pagination.Item> <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}> <span>Next</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### Anatomy Import the Pagination component and access all parts using dot notation. ```tsx import { Pagination } from '@heroui/react'; export default () => ( <Pagination> <Pagination.Summary>Showing 1-10 of 100 results</Pagination.Summary> <Pagination.Content> <Pagination.Item> <Pagination.Previous> <Pagination.PreviousIcon /> <span>Previous</span> </Pagination.Previous> </Pagination.Item> <Pagination.Item> <Pagination.Link isActive>1</Pagination.Link> </Pagination.Item> <Pagination.Item> <Pagination.Ellipsis /> </Pagination.Item> <Pagination.Item> <Pagination.Link>10</Pagination.Link> </Pagination.Item> <Pagination.Item> <Pagination.Next> <span>Next</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); ``` ### Sizes ```tsx "use client"; import {Pagination} from "@heroui/react"; import {useState} from "react"; function SizePagination({size}: {size: "sm" | "md" | "lg"}) { const [page, setPage] = useState(1); const totalPages = 3; return ( <div className="flex flex-col gap-2"> <span className="text-xs font-medium text-muted capitalize">{size}</span> <Pagination className="justify-center" size={size}> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}> <Pagination.PreviousIcon /> <span>Previous</span> </Pagination.Previous> </Pagination.Item> {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => ( <Pagination.Item key={p}> <Pagination.Link isActive={p === page} onPress={() => setPage(p)}> {p} </Pagination.Link> </Pagination.Item> ))} <Pagination.Item> <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}> <span>Next</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> </div> ); } export function PaginationSizes() { return ( <div className="flex flex-col gap-6"> {(["sm", "md", "lg"] as const).map((size) => ( <SizePagination key={size} size={size} /> ))} </div> ); } ``` ### With Ellipsis ```tsx "use client"; import {Pagination} from "@heroui/react"; import {useState} from "react"; export function PaginationWithEllipsis() { const [page, setPage] = useState(1); const totalPages = 12; const getPageNumbers = () => { const pages: (number | "ellipsis")[] = []; pages.push(1); if (page > 3) { pages.push("ellipsis"); } const start = Math.max(2, page - 1); const end = Math.min(totalPages - 1, page + 1); for (let i = start; i <= end; i++) { pages.push(i); } if (page < totalPages - 2) { pages.push("ellipsis"); } pages.push(totalPages); return pages; }; return ( <div className="w-full max-w-2xs overflow-x-auto sm:max-w-full"> <Pagination className="justify-center"> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}> <Pagination.PreviousIcon /> <span>Previous</span> </Pagination.Previous> </Pagination.Item> {getPageNumbers().map((p, i) => p === "ellipsis" ? ( <Pagination.Item key={`ellipsis-${i}`}> <Pagination.Ellipsis /> </Pagination.Item> ) : ( <Pagination.Item key={p}> <Pagination.Link isActive={p === page} onPress={() => setPage(p)}> {p} </Pagination.Link> </Pagination.Item> ), )} <Pagination.Item> <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}> <span>Next</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> </div> ); } ``` ### Simple (Previous / Next) ```tsx "use client"; import {Pagination} from "@heroui/react"; import {useState} from "react"; export function PaginationSimplePrevNext() { const [page, setPage] = useState(1); const totalPages = 10; const itemsPerPage = 5; const totalItems = 50; const startItem = (page - 1) * itemsPerPage + 1; const endItem = Math.min(page * itemsPerPage, totalItems); return ( <Pagination className="w-full"> <Pagination.Summary> {startItem} to {endItem} of {totalItems} invoices </Pagination.Summary> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}> <Pagination.PreviousIcon /> <span>Prev</span> </Pagination.Previous> </Pagination.Item> <Pagination.Item> <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}> <span>Next</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### With Summary ```tsx "use client"; import {Pagination} from "@heroui/react"; import {useState} from "react"; export function PaginationWithSummary() { const [page, setPage] = useState(1); const totalPages = 12; const itemsPerPage = 10; const totalItems = 120; const getPageNumbers = () => { const pages: (number | "ellipsis")[] = []; pages.push(1); if (page > 3) { pages.push("ellipsis"); } const start = Math.max(2, page - 1); const end = Math.min(totalPages - 1, page + 1); for (let i = start; i <= end; i++) { pages.push(i); } if (page < totalPages - 2) { pages.push("ellipsis"); } pages.push(totalPages); return pages; }; const startItem = (page - 1) * itemsPerPage + 1; const endItem = Math.min(page * itemsPerPage, totalItems); return ( <Pagination className="w-full"> <Pagination.Summary> Showing {startItem}-{endItem} of {totalItems} results </Pagination.Summary> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}> <Pagination.PreviousIcon /> <span>Previous</span> </Pagination.Previous> </Pagination.Item> {getPageNumbers().map((p, i) => p === "ellipsis" ? ( <Pagination.Item key={`ellipsis-${i}`}> <Pagination.Ellipsis /> </Pagination.Item> ) : ( <Pagination.Item key={p}> <Pagination.Link isActive={p === page} onPress={() => setPage(p)}> {p} </Pagination.Link> </Pagination.Item> ), )} <Pagination.Item> <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}> <span>Next</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### Custom Icons You can replace the default chevron icons by passing custom children to `PreviousIcon` and `NextIcon`. ```tsx "use client"; import {Pagination} from "@heroui/react"; import {Icon} from "@iconify/react"; import {useState} from "react"; export function PaginationCustomIcons() { const [page, setPage] = useState(1); const totalPages = 3; return ( <Pagination className="justify-center"> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}> <Pagination.PreviousIcon> <Icon icon="gravity-ui:arrow-left" /> </Pagination.PreviousIcon> <span>Back</span> </Pagination.Previous> </Pagination.Item> {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => ( <Pagination.Item key={p}> <Pagination.Link isActive={p === page} onPress={() => setPage(p)}> {p} </Pagination.Link> </Pagination.Item> ))} <Pagination.Item> <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}> <span>Forward</span> <Pagination.NextIcon> <Icon icon="gravity-ui:arrow-right" /> </Pagination.NextIcon> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### Controlled ```tsx "use client"; import {Pagination} from "@heroui/react"; import {useState} from "react"; export function PaginationControlled() { const [page, setPage] = useState(1); const totalPages = 12; const itemsPerPage = 10; const totalItems = 120; const getPageNumbers = () => { const pages: (number | "ellipsis")[] = []; if (totalPages <= 7) { for (let i = 1; i <= totalPages; i++) { pages.push(i); } } else { pages.push(1); if (page > 3) { pages.push("ellipsis"); } const start = Math.max(2, page - 1); const end = Math.min(totalPages - 1, page + 1); for (let i = start; i <= end; i++) { pages.push(i); } if (page < totalPages - 2) { pages.push("ellipsis"); } pages.push(totalPages); } return pages; }; const startItem = (page - 1) * itemsPerPage + 1; const endItem = Math.min(page * itemsPerPage, totalItems); return ( <Pagination> <Pagination.Summary> Showing {startItem}-{endItem} of {totalItems} results </Pagination.Summary> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}> <Pagination.PreviousIcon /> <span>Previous</span> </Pagination.Previous> </Pagination.Item> {getPageNumbers().map((p, i) => p === "ellipsis" ? ( <Pagination.Item key={`ellipsis-${i}`}> <Pagination.Ellipsis /> </Pagination.Item> ) : ( <Pagination.Item key={p}> <Pagination.Link isActive={p === page} onPress={() => setPage(p)}> {p} </Pagination.Link> </Pagination.Item> ), )} <Pagination.Item> <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}> <span>Next</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### Disabled ```tsx "use client"; import {Pagination} from "@heroui/react"; import {useState} from "react"; export function PaginationDisabled() { const [page, setPage] = useState(1); const totalPages = 3; return ( <Pagination className="justify-center"> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled onPress={() => setPage((p) => p - 1)}> <Pagination.PreviousIcon /> <span>Previous</span> </Pagination.Previous> </Pagination.Item> {Array.from({length: totalPages}, (_, i) => i + 1).map((p) => ( <Pagination.Item key={p}> <Pagination.Link isActive={p === page} onPress={() => setPage(p)}> {p} </Pagination.Link> </Pagination.Item> ))} <Pagination.Item> <Pagination.Next isDisabled onPress={() => setPage((p) => p + 1)}> <span>Next</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ## Related Components * **Button**: Allows a user to perform an action * **Link**: Styled anchor links ## Styling ### Passing Tailwind CSS classes You can customize individual Pagination parts: ```tsx import { Pagination } from '@heroui/react'; function CustomPagination() { return ( <Pagination className="gap-8"> <Pagination.Content className="gap-2"> <Pagination.Item> <Pagination.Link className="rounded-md" isActive>1</Pagination.Link> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### Customizing the component classes To customize the Pagination component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .pagination { @apply gap-8; } .pagination__link { @apply rounded-md; } .pagination__summary { @apply text-xs font-semibold; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Pagination component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/pagination.css)): #### Base & Layout Classes * `.pagination` - Root navigation container with flex layout * `.pagination__summary` - Left-side info text container * `.pagination__content` - Container for pagination items * `.pagination__item` - Individual item wrapper * `.pagination__link` - Page number button (ghost button style) * `.pagination__link--nav` - Navigation button modifier (Previous/Next) * `.pagination__ellipsis` - Ellipsis indicator #### Size Classes * `.pagination--sm` - Small size variant * `.pagination--md` - Medium size variant (default) * `.pagination--lg` - Large size variant ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Active page**: `[data-active="true"]` or `[aria-current="page"]` * **Hover**: `:hover` or `[data-hovered="true"]` * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` * **Disabled**: `:disabled` or `[aria-disabled="true"]` * **Pressed**: `:active` or `[data-pressed="true"]` ## API Reference ### Pagination Props | Prop | Type | Default | Description | | ----------- | ---------------------- | ------- | ----------------------------------- | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size of the pagination items | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Pagination parts (Summary, Content) | ### Pagination.Summary Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | --------------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Summary content (e.g., "Showing 1-10 of 120") | ### Pagination.Content Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Pagination items | ### Pagination.Item Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Item content (Link, Previous, Next, or Ellipsis) | ### Pagination.Link Props | Prop | Type | Default | Description | | ------------ | ------------------------- | ------- | -------------------------------- | | `isActive` | `boolean` | `false` | Whether this is the current page | | `isDisabled` | `boolean` | `false` | Whether the link is disabled | | `onPress` | `(e: PressEvent) => void` | - | Press handler (from React Aria) | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Page number content | ### Pagination.Previous / Pagination.Next Props | Prop | Type | Default | Description | | ------------ | ------------------------- | ------- | --------------------------------------------------- | | `isDisabled` | `boolean` | `false` | Whether the button is disabled | | `onPress` | `(e: PressEvent) => void` | - | Press handler (from React Aria) | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Button content (compose with PreviousIcon/NextIcon) | ### Pagination.PreviousIcon / Pagination.NextIcon Props | Prop | Type | Default | Description | | ----------- | ----------- | ------------------- | ------------------------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | Default chevron SVG | Custom icon to replace the default chevron | ### Pagination.Ellipsis Props | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | ## Accessibility The Pagination component is built on [React Aria's Button](https://react-spectrum.adobe.com/react-aria/Button.html) primitive for all interactive elements, providing: * Semantic `<nav>` element with `aria-label="pagination"` and `role="navigation"` * Active page indicated via `aria-current="page"` on the current link * Keyboard navigation via Tab key through all interactive elements * Press events handled across mouse, touch, and keyboard interactions via React Aria * Focus ring on keyboard navigation via `:focus-visible` * Ellipsis marked with `aria-hidden="true"` to avoid screen reader confusion * Disabled states properly communicated to assistive technology via `isDisabled` > **Note:** Pagination buttons use `onPress` instead of `onClick`. The `onPress` handler from React Aria normalizes press behavior across pointer types and provides accessibility improvements out of the box. </page> <page url="/docs/react/components/tabs"> # Tabs **Category**: react **URL**: https://v3.heroui.com/docs/react/components/tabs **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(navigation)/tabs.mdx > Tabs organize content into multiple sections and allow users to navigate between them. ## Import ```tsx import { Tabs } from '@heroui/react'; ``` ### Usage ### Anatomy Import the Tabs component and access all parts using dot notation. ```tsx import { Tabs } from '@heroui/react'; export default () => ( <Tabs> <Tabs.ListContainer> <Tabs.List aria-label="Options"> <Tabs.Tab> <Tabs.Separator /> {/* Optional */} <Tabs.Indicator /> </Tabs.Tab> </Tabs.List> </Tabs.ListContainer> <Tabs.Panel/> </Tabs> ) ``` ### Vertical ### Disabled Tab ### With Separator Add `<Tabs.Separator />` inside each `<Tabs.Tab>` (except the first) to display separator lines between tabs. ### Custom Styles ### Secondary Variant ### Secondary Variant Vertical ## Related Components * **Breadcrumbs**: Display the user's current location within a hierarchy ### Custom Render Function ```tsx "use client"; import {Tabs} from "@heroui/react"; import Link from "next/link"; export function CustomRenderFunction() { return ( <Tabs className="w-full max-w-md" render={(props) => <div {...props} data-custom="foo" />}> <Tabs.ListContainer> <Tabs.List aria-label="Options"> <Tabs.Tab href="/docs/react/getting-started" id="getting-started" render={(domProps: any) => <Link {...domProps} />} > Getting Started <Tabs.Indicator /> </Tabs.Tab> <Tabs.Tab href="/docs/react/components" id="components" render={(domProps: any) => <Link {...domProps} />} > Components <Tabs.Indicator /> </Tabs.Tab> <Tabs.Tab href="/docs/react/releases" id="releases" render={(domProps: any) => <Link {...domProps} />} > Releases <Tabs.Indicator /> </Tabs.Tab> </Tabs.List> </Tabs.ListContainer> <Tabs.Panel className="pt-4" id="overview"> <p>View your project overview and recent activity.</p> </Tabs.Panel> <Tabs.Panel className="pt-4" id="analytics"> <p>Track your metrics and analyze performance data.</p> </Tabs.Panel> <Tabs.Panel className="pt-4" id="reports"> <p>Generate and download detailed reports.</p> </Tabs.Panel> </Tabs> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import { Tabs } from '@heroui/react'; function CustomTabs() { return ( <Tabs className="w-full max-w-lg text-center"> <Tabs.ListContainer> <Tabs.List aria-label="Options" className="*:data-[selected=true]:text-accent-foreground w-fit *:h-6 *:w-fit *:px-3 *:text-sm *:font-normal" > <Tabs.Tab id="daily">Daily<Tabs.Indicator /></Tabs.Tab> <Tabs.Tab id="weekly">Weekly<Tabs.Indicator /></Tabs.Tab> <Tabs.Tab id="bi-weekly">Bi-Weekly<Tabs.Indicator /></Tabs.Tab> <Tabs.Tab id="monthly">Monthly<Tabs.Indicator /></Tabs.Tab> </Tabs.List> </Tabs.ListContainer> <Tabs.Panel className="px-4" id="daily"> <h3 className="mb-2 font-semibold">Daily</h3> <p className="text-sm text-gray-600">Manage your daily tasks and goals.</p> </Tabs.Panel> <Tabs.Panel className="px-4" id="weekly"> <h3 className="mb-2 font-semibold">Weekly</h3> <p className="text-sm text-gray-600">Manage your weekly tasks and goals.</p> </Tabs.Panel> <Tabs.Panel className="px-4" id="bi-weekly"> <h3 className="mb-2 font-semibold">Bi-Weekly</h3> <p className="text-sm text-gray-600">Manage your bi-weekly tasks and goals.</p> </Tabs.Panel> <Tabs.Panel className="px-4" id="monthly"> <h3 className="mb-2 font-semibold">Monthly</h3> <p className="text-sm text-gray-600">Manage your monthly tasks and goals.</p> </Tabs.Panel> </Tabs> ); } ``` ### CSS Classes The Tabs component uses these CSS classes: #### Base Classes * `.tabs` - Base tabs container * `.tabs__list-container` - Tab list container wrapper * `.tabs__list` - Tab list container * `.tabs__tab` - Individual tab button * `.tabs__separator` - Separator between tabs * `.tabs__panel` - Tab panel content * `.tabs__indicator` - Tab indicator #### Orientation Attributes * `.tabs[data-orientation="horizontal"]` - Horizontal tab layout (default) * `.tabs[data-orientation="vertical"]` - Vertical tab layout #### Variant Classes * `.tabs--secondary` - Secondary variant with underline indicator ### Interactive States The component supports both CSS pseudo-classes and data attributes: * **Selected**: `[aria-selected="true"]` * **Hover**: `:hover` or `[data-hovered="true"]` * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` * **Disabled**: `[aria-disabled="true"]` ## API Reference ### Tabs Props | Prop | Type | Default | Description | | -------------------- | ----------------------------------------------------------------------- | -------------- | -------------------------------------------------------------------------------------------- | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual style variant. Primary uses a filled indicator, secondary uses an underline indicator | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Tab layout orientation | | `selectedKey` | `string` | - | Controlled selected tab key | | `defaultSelectedKey` | `string` | - | Default selected tab key | | `onSelectionChange` | `(key: Key) => void` | - | Selection change handler | | `className` | `string` | - | Additional CSS classes | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabsRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Tabs.List Props | Prop | Type | Default | Description | | ------------ | -------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | `aria-label` | `string` | - | Accessibility label for tab list | | `className` | `string` | - | Additional CSS classes | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabListRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Tabs.Tab Props | Prop | Type | Default | Description | | ------------ | ---------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | `id` | `string` | - | Unique tab identifier | | `isDisabled` | `boolean` | `false` | Whether tab is disabled | | `className` | `string` | - | Additional CSS classes | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Tabs.Separator Props | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | ### Tabs.Panel Props | Prop | Type | Default | Description | | ----------- | --------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | `id` | `string` | - | Panel identifier matching tab id | | `className` | `string` | - | Additional CSS classes | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabPanelRenderProps>` | - | Overrides the default DOM element with a custom render function. | </page> <page url="/docs/react/components/alert-dialog"> # AlertDialog **Category**: react **URL**: https://v3.heroui.com/docs/react/components/alert-dialog **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(overlays)/alert-dialog.mdx > Modal dialog for critical confirmations requiring user attention and explicit action ## Import ```tsx import { AlertDialog } from "@heroui/react"; ``` ### Usage ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; export function Default() { return ( <AlertDialog> <Button variant="danger">Delete Project</Button> <AlertDialog.Backdrop> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="danger" /> <AlertDialog.Heading>Delete project permanently?</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> This will permanently delete <strong>My Awesome Project</strong> and all of its data. This action cannot be undone. </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close" variant="danger"> Delete Project </Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); } ``` ### Anatomy Import the AlertDialog component and access all parts using dot notation. ```tsx import {AlertDialog, Button} from "@heroui/react"; export default () => ( <AlertDialog> <Button>Open Alert Dialog</Button> <AlertDialog.Backdrop> <AlertDialog.Container> <AlertDialog.Dialog> <AlertDialog.CloseTrigger /> {/* Optional: Close button */} <AlertDialog.Header> <AlertDialog.Icon /> {/* Optional: Status icon */} <AlertDialog.Heading /> </AlertDialog.Header> <AlertDialog.Body /> <AlertDialog.Footer /> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); ``` ### Statuses ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; export function Statuses() { const examples = [ { actions: { cancel: "Stay Signed In", confirm: "Sign Out", }, body: "You'll need to sign in again to access your account. Any unsaved changes will be lost.", classNames: "bg-accent-soft text-accent-soft-foreground", header: "Sign out of your account?", status: "accent", trigger: "Sign Out", }, { actions: { cancel: "Not Yet", confirm: "Mark Complete", }, body: "This will mark the task as complete and notify all team members. The task will be moved to your completed list.", classNames: "bg-success-soft text-success-soft-foreground", header: "Complete this task?", status: "success", trigger: "Complete Task", }, { actions: { cancel: "Keep Editing", confirm: "Discard", }, body: "You have unsaved changes that will be permanently lost. Are you sure you want to discard them?", classNames: "bg-warning-soft text-warning-soft-foreground", header: "Discard unsaved changes?", status: "warning", trigger: "Discard Changes", }, { actions: { cancel: "Cancel", confirm: "Delete Account", }, body: "This will permanently delete your account and remove all your data from our servers. This action is irreversible.", classNames: "bg-danger-soft text-danger-soft-foreground", header: "Delete your account?", status: "danger", trigger: "Delete Account", }, ] as const; return ( <div className="flex flex-wrap gap-4"> {examples.map(({actions, body, classNames, header, status, trigger}) => ( <AlertDialog key={status}> <Button className={classNames}>{trigger}</Button> <AlertDialog.Backdrop> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status={status} /> <AlertDialog.Heading>{header}</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p>{body}</p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> {actions.cancel} </Button> <Button slot="close" variant={status === "danger" ? "danger" : "primary"}> {actions.confirm} </Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ))} </div> ); } ``` ### Placements ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; export function Placements() { const placements = ["auto", "top", "center", "bottom"] as const; return ( <div className="flex flex-wrap gap-4"> {placements.map((placement) => ( <AlertDialog key={placement}> <Button variant="secondary"> {placement.charAt(0).toUpperCase() + placement.slice(1)} </Button> <AlertDialog.Backdrop> <AlertDialog.Container placement={placement}> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="accent" /> <AlertDialog.Heading> {placement === "auto" ? "Auto Placement" : `${placement.charAt(0).toUpperCase() + placement.slice(1)} Position`} </AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> {placement === "auto" ? "Automatically positions at the bottom on mobile and center on desktop for optimal user experience." : `This dialog is positioned at the ${placement} of the viewport. Critical confirmations are typically centered for maximum attention.`} </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close">Confirm</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ))} </div> ); } ``` ### Backdrop Variants ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; export function BackdropVariants() { const variants = ["opaque", "blur", "transparent"] as const; return ( <div className="flex flex-wrap gap-4"> {variants.map((variant) => ( <AlertDialog key={variant}> <Button variant="secondary">{variant.charAt(0).toUpperCase() + variant.slice(1)}</Button> <AlertDialog.Backdrop variant={variant}> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="accent" /> <AlertDialog.Heading> Backdrop: {variant.charAt(0).toUpperCase() + variant.slice(1)} </AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> {variant === "opaque" ? "An opaque dark backdrop that completely obscures the background, providing maximum focus on the dialog." : variant === "blur" ? "A blurred backdrop that softly obscures the background while maintaining visual context." : "A transparent backdrop that keeps the background fully visible, useful for less critical confirmations."} </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close">Confirm</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ))} </div> ); } ``` ### Sizes ```tsx "use client"; import {Rocket} from "@gravity-ui/icons"; import {AlertDialog, Button} from "@heroui/react"; export function Sizes() { const sizes = ["xs", "sm", "md", "lg", "cover"] as const; return ( <div className="flex flex-wrap gap-4"> {sizes.map((size) => ( <AlertDialog key={size}> <Button variant="secondary">{size.charAt(0).toUpperCase() + size.slice(1)}</Button> <AlertDialog.Backdrop> <AlertDialog.Container size={size}> <AlertDialog.Dialog> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon className="bg-default text-foreground"> <Rocket className="size-5" /> </AlertDialog.Icon> <AlertDialog.Heading> Size: {size.charAt(0).toUpperCase() + size.slice(1)} </AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> {size === "cover" ? ( <> This alert dialog uses the <code>cover</code> size variant. It spans the full screen with margins: 16px on mobile and 40px on desktop. Maintains rounded corners and standard padding. Perfect for critical confirmations that need maximum width while preserving alert dialog aesthetics. </> ) : ( <> This alert dialog uses the <code>{size}</code> size variant. On mobile devices, all sizes adapt to near full-width for optimal viewing. On desktop, each size provides a different maximum width to suit various content needs. </> )} </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close">Confirm</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ))} </div> ); } ``` ### Custom Icon ```tsx "use client"; import {LockOpen} from "@gravity-ui/icons"; import {AlertDialog, Button} from "@heroui/react"; export function CustomIcon() { return ( <AlertDialog> <Button variant="secondary">Reset Password</Button> <AlertDialog.Backdrop> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="warning"> <LockOpen className="size-5" /> </AlertDialog.Icon> <AlertDialog.Heading>Reset your password?</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> We'll send a password reset link to your email address. You'll need to create a new password to regain access to your account. </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close">Send Reset Link</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); } ``` ### Custom Backdrop ```tsx "use client"; import {TriangleExclamation} from "@gravity-ui/icons"; import {AlertDialog, Button} from "@heroui/react"; export function CustomBackdrop() { return ( <AlertDialog> <Button variant="danger">Delete Account</Button> <AlertDialog.Backdrop className="bg-linear-to-t from-red-950/90 via-red-950/50 to-transparent dark:from-red-950/95 dark:via-red-950/60" variant="blur" > <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[420px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header className="items-center text-center"> <AlertDialog.Icon status="danger"> <TriangleExclamation className="size-5" /> </AlertDialog.Icon> <AlertDialog.Heading>Permanently delete your account?</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> This action cannot be undone. All your data, settings, and content will be permanently removed from our servers. The dramatic red backdrop emphasizes the severity and irreversibility of this decision. </p> </AlertDialog.Body> <AlertDialog.Footer className="flex-col-reverse"> <Button className="w-full" slot="close"> Keep Account </Button> <Button className="w-full" slot="close" variant="danger"> Delete Forever </Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); } ``` ### Dismiss Behavior ```tsx "use client"; import {CircleInfo} from "@gravity-ui/icons"; import {AlertDialog, Button} from "@heroui/react"; export function DismissBehavior() { return ( <div className="flex max-w-sm flex-col gap-6"> <div className="flex flex-col gap-2"> <h3 className="text-lg font-semibold">isDismissable</h3> <p className="text-sm text-muted"> Controls whether the alert dialog can be dismissed by clicking the overlay backdrop. Alert dialogs typically require explicit action, so this defaults to <code>false</code>. Set to{" "} <code>true</code> for less critical confirmations. </p> <AlertDialog> <Button variant="secondary">Open Alert Dialog</Button> <AlertDialog.Backdrop isDismissable={false}> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="danger"> <CircleInfo className="size-5" /> </AlertDialog.Icon> <AlertDialog.Heading>isDismissable = false</AlertDialog.Heading> <p className="text-sm leading-5 text-muted"> Clicking the backdrop won't close this alert dialog </p> </AlertDialog.Header> <AlertDialog.Body> <p> Try clicking outside this alert dialog on the overlay - it won't close. You must use the action buttons to dismiss it. </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close">Confirm</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> </div> <div className="flex flex-col gap-2"> <h3 className="text-lg font-semibold">isKeyboardDismissDisabled</h3> <p className="text-sm text-muted"> Controls whether the ESC key can dismiss the alert dialog. Alert dialogs typically require explicit action, so this defaults to <code>true</code>. When set to <code>false</code>, the ESC key will be enabled. </p> <AlertDialog> <Button variant="secondary">Open Alert Dialog</Button> <AlertDialog.Backdrop isKeyboardDismissDisabled> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="accent"> <CircleInfo className="size-5" /> </AlertDialog.Icon> <AlertDialog.Heading>isKeyboardDismissDisabled = true</AlertDialog.Heading> <p className="text-sm leading-5 text-muted">ESC key is disabled</p> </AlertDialog.Header> <AlertDialog.Body> <p> Press ESC - nothing happens. You must use the action buttons to dismiss this alert dialog. </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close">Confirm</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> </div> </div> ); } ``` ### Close Methods ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; export function CloseMethods() { return ( <div className="flex max-w-2xl flex-col gap-8"> <div className="flex flex-col gap-2"> <h3 className="text-lg font-semibold">Using slot="close"</h3> <p className="text-sm text-muted"> The simplest way to close a dialog. Add <code>slot="close"</code> to any Button component within the dialog. When clicked, it will automatically close the dialog. </p> <AlertDialog> <Button variant="secondary">Open Dialog</Button> <AlertDialog.Backdrop> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.Header> <AlertDialog.Icon status="accent" /> <AlertDialog.Heading>Using slot="close"</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> Click either button below - both have <code>slot="close"</code> and will close the dialog automatically. </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close">Confirm</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> </div> <div className="flex flex-col gap-2"> <h3 className="text-lg font-semibold">Using Dialog render props</h3> <p className="text-sm text-muted"> Access the <code>close</code> method from the Dialog's render props. This gives you full control over when and how to close the dialog, allowing you to add custom logic before closing. </p> <AlertDialog> <Button variant="secondary">Open Dialog</Button> <AlertDialog.Backdrop> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> {(renderProps) => ( <> <AlertDialog.Header> <AlertDialog.Icon status="success" /> <AlertDialog.Heading>Using Dialog render props</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> The buttons below use the <code>close</code> method from render props. You can add validation or other logic before calling{" "} <code>renderProps.close()</code>. </p> </AlertDialog.Body> <AlertDialog.Footer> <Button variant="tertiary" onPress={() => renderProps.close()}> Cancel </Button> <Button onPress={() => renderProps.close()}>Confirm</Button> </AlertDialog.Footer> </> )} </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> </div> </div> ); } ``` ### Controlled State ```tsx "use client"; import {AlertDialog, Button, useOverlayState} from "@heroui/react"; import React from "react"; export function Controlled() { const [isOpen, setIsOpen] = React.useState(false); const state = useOverlayState(); return ( <div className="flex max-w-md flex-col gap-8"> <div className="flex flex-col gap-3"> <h3 className="text-lg font-semibold text-foreground">With React.useState()</h3> <p className="text-sm leading-relaxed text-pretty text-muted"> Control the alert dialog using React's <code className="text-foreground">useState</code>{" "} hook for simple state management. Perfect for basic use cases. </p> <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm"> <div className="flex w-full items-center justify-between"> <p className="text-xs text-muted"> Status:{" "} <span className="font-mono font-medium text-foreground"> {isOpen ? "open" : "closed"} </span> </p> </div> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}> Open Dialog </Button> <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}> Toggle </Button> </div> </div> <AlertDialog.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="accent" /> <AlertDialog.Heading>Controlled with useState()</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> This alert dialog is controlled by React's <code>useState</code> hook. Pass{" "} <code>isOpen</code> and <code>onOpenChange</code> props to manage the dialog state externally. </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close">Confirm</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </div> <div className="flex flex-col gap-3"> <h3 className="text-lg font-semibold text-foreground">With useOverlayState()</h3> <p className="text-sm leading-relaxed text-pretty text-muted"> Use the <code className="text-foreground">useOverlayState</code> hook for a cleaner API with convenient methods like <code>open()</code>, <code>close()</code>, and{" "} <code>toggle()</code>. </p> <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm"> <div className="flex w-full items-center justify-between"> <p className="text-xs text-muted"> Status:{" "} <span className="font-mono font-medium text-foreground"> {state.isOpen ? "open" : "closed"} </span> </p> </div> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={state.open}> Open Dialog </Button> <Button size="sm" variant="tertiary" onPress={state.toggle}> Toggle </Button> </div> </div> <AlertDialog.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="success" /> <AlertDialog.Heading>Controlled with useOverlayState()</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> The <code>useOverlayState</code> hook provides dedicated methods for common operations. No need to manually create callbacks—just use{" "} <code>state.open()</code>, <code>state.close()</code>, or{" "} <code>state.toggle()</code>. </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close">Confirm</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </div> </div> ); } ``` ### Custom Trigger ```tsx "use client"; import {TrashBin} from "@gravity-ui/icons"; import {AlertDialog, Button} from "@heroui/react"; export function CustomTrigger() { return ( <AlertDialog> <AlertDialog.Trigger className="group flex items-center gap-3 rounded-2xl bg-surface p-4 shadow-xs select-none hover:bg-surface-secondary"> <div className="flex size-12 shrink-0 items-center justify-center rounded-xl bg-danger-soft text-danger-soft-foreground"> <TrashBin className="size-6" /> </div> <div className="flex flex-1 flex-col gap-0.5"> <p className="text-sm font-semibold">Delete Item</p> <p className="text-xs text-muted">Permanently remove this item</p> </div> </AlertDialog.Trigger> <AlertDialog.Backdrop> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="danger"> <TrashBin className="size-5" /> </AlertDialog.Icon> <AlertDialog.Heading>Delete this item?</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> Use <code>AlertDialog.Trigger</code> to create custom trigger elements beyond standard buttons. This example shows a card-style trigger with icons and descriptive text. </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close" variant="danger"> Delete Item </Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); } ``` ### Custom Animations ```tsx "use client"; import {ArrowUpFromLine, Sparkles} from "@gravity-ui/icons"; import {AlertDialog, Button} from "@heroui/react"; import React from "react"; const iconMap: Record<string, React.ComponentType<{className?: string}>> = { "gravity-ui:arrow-up-from-line": ArrowUpFromLine, "gravity-ui:sparkles": Sparkles, }; export function CustomAnimations() { const animations = [ { classNames: { backdrop: [ "data-[entering]:duration-400", "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]", "data-[exiting]:duration-200", "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]", ].join(" "), container: [ "data-[entering]:animate-in", "data-[entering]:fade-in-0", "data-[entering]:zoom-in-95", "data-[entering]:duration-400", "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]", "data-[exiting]:animate-out", "data-[exiting]:fade-out-0", "data-[exiting]:zoom-out-95", "data-[exiting]:duration-200", "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]", ].join(" "), }, description: "Physics-based elastic scaling. Simulates a high-damping spring system with fast transient response and prolonged settling time. Ideal for Alert Dialogs and Modals.", icon: "gravity-ui:sparkles", name: "Kinematic Scale", }, { classNames: { backdrop: [ "data-[entering]:duration-500", "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]", "data-[exiting]:duration-200", "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]", ].join(" "), container: [ "data-[entering]:animate-in", "data-[entering]:fade-in-0", "data-[entering]:slide-in-from-bottom-4", "data-[entering]:duration-500", "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]", "data-[exiting]:animate-out", "data-[exiting]:fade-out-0", "data-[exiting]:slide-out-to-bottom-2", "data-[exiting]:duration-200", "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]", ].join(" "), }, description: "Simulates movement through a medium with fluid resistance. Eliminates mechanical linearity for a natural, grounded feel. Perfect for Bottom Sheets or Toasts.", icon: "gravity-ui:arrow-up-from-line", name: "Fluid Slide", }, ]; return ( <div className="flex flex-wrap gap-4"> {animations.map(({classNames, description, icon, name}) => { const IconComponent = iconMap[icon]; return ( <AlertDialog key={name}> <Button variant="secondary">{name}</Button> <AlertDialog.Backdrop className={classNames.backdrop}> <AlertDialog.Container className={classNames.container}> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="accent"> {!!IconComponent && <IconComponent className="size-5" />} </AlertDialog.Icon> <AlertDialog.Heading>{name} Animation</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p className="mt-1">{description}</p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Close </Button> <Button slot="close">Try Again</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); })} </div> ); } ``` ### Custom Portal ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; import {useCallback, useRef, useState} from "react"; export function CustomPortal() { const portalRef = useRef<HTMLDivElement>(null); const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null); const setPortalRef = useCallback((node: HTMLDivElement | null) => { portalRef.current = node; setPortalContainer(node); }, []); return ( <div className="flex flex-col gap-4"> <div> <p className="text-sm"> Render alert dialogs inside a custom container instead of <code>document.body</code> </p> <p className="text-sm text-muted"> Apply <code className="rounded px-1 py-0.5 text-xs">transform: translateZ(0)</code> to the container to create a new stacking context. </p> </div> <div ref={setPortalRef} className="relative flex h-[380px] items-center justify-center overflow-hidden rounded bg-muted/20" // new stacking context style={{transform: "translate(0)"}} > {!!portalContainer && ( <AlertDialog> <Button>Open Alert Dialog</Button> <AlertDialog.Backdrop className="h-full" UNSTABLE_portalContainer={portalContainer}> <AlertDialog.Container className="h-full max-h-full"> <AlertDialog.Dialog className="h-full max-h-full sm:max-w-md"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="accent" /> <AlertDialog.Heading>Custom Portal</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p className="text-sm text-muted"> 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 nisi ut aliquip ex ea commodo consequat. </p> <p className="text-sm text-muted"> 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 nisi ut aliquip ex ea commodo consequat. </p> <p className="text-sm text-muted"> 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 nisi ut aliquip ex ea commodo consequat. </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close">Confirm</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> )} </div> </div> ); } ``` ## Related Components * **Button**: Allows a user to perform an action * **CloseButton**: Button for dismissing overlays ## Styling ### Passing Tailwind CSS classes ```tsx import {AlertDialog, Button} from "@heroui/react"; function CustomAlertDialog() { return ( <AlertDialog> <Button variant="danger">Delete</Button> <AlertDialog.Backdrop className="bg-red-950/90"> <AlertDialog.Container className="items-start pt-20"> <AlertDialog.Dialog className="border-2 border-red-500 sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="danger" /> <AlertDialog.Heading>Custom Styled Alert</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p>This alert dialog has custom styling applied via Tailwind classes</p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Cancel </Button> <Button slot="close" variant="danger"> Delete </Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); } ``` ### Customizing the component classes To customize the AlertDialog component classes, you can use the `@layer components` directive. <br /> [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .alert-dialog__backdrop { @apply bg-gradient-to-br from-black/60 to-black/80; } .alert-dialog__dialog { @apply rounded-2xl border border-red-500/20 shadow-2xl; } .alert-dialog__header { @apply gap-4; } .alert-dialog__icon { @apply size-16; } .alert-dialog__close-trigger { @apply rounded-full bg-white/10 hover:bg-white/20; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The AlertDialog component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert-dialog.css)): #### Base Classes * `.alert-dialog__trigger` - Trigger element that opens the alert dialog * `.alert-dialog__backdrop` - Overlay backdrop behind the dialog * `.alert-dialog__container` - Positioning wrapper with placement support * `.alert-dialog__dialog` - Dialog content container * `.alert-dialog__header` - Header section for icon and title * `.alert-dialog__heading` - Heading text styles * `.alert-dialog__body` - Main content area * `.alert-dialog__footer` - Footer section for actions * `.alert-dialog__icon` - Icon container with status colors * `.alert-dialog__close-trigger` - Close button element #### Backdrop Variants * `.alert-dialog__backdrop--opaque` - Opaque colored backdrop (default) * `.alert-dialog__backdrop--blur` - Blurred backdrop with glass effect * `.alert-dialog__backdrop--transparent` - Transparent backdrop (no overlay) #### Status Variants (Icon) * `.alert-dialog__icon--default` - Default gray status * `.alert-dialog__icon--accent` - Accent blue status * `.alert-dialog__icon--success` - Success green status * `.alert-dialog__icon--warning` - Warning orange status * `.alert-dialog__icon--danger` - Danger red status ### Interactive States The component supports these interactive states: * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` - Applied to trigger, dialog, and close button * **Hover**: `:hover` or `[data-hovered="true"]` - Applied to close button on hover * **Active**: `:active` or `[data-pressed="true"]` - Applied to close button when pressed * **Entering**: `[data-entering]` - Applied during dialog opening animation * **Exiting**: `[data-exiting]` - Applied during dialog closing animation * **Placement**: `[data-placement="*"]` - Applied based on dialog position (auto, top, center, bottom) ## API Reference ### AlertDialog | Prop | Type | Default | Description | | ---------- | ----------- | ------- | ------------------------------ | | `children` | `ReactNode` | - | Trigger and container elements | ### AlertDialog.Trigger | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `children` | `ReactNode` | - | Custom trigger content | | `className` | `string` | - | CSS classes | ### AlertDialog.Backdrop | Prop | Type | Default | Description | | --------------------------- | ------------------------------------- | ---------- | ------------------------- | | `variant` | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | Backdrop overlay style | | `isDismissable` | `boolean` | `false` | Close on backdrop click | | `isKeyboardDismissDisabled` | `boolean` | `true` | Disable ESC key to close | | `isOpen` | `boolean` | - | Controlled open state | | `onOpenChange` | `(isOpen: boolean) => void` | - | Open state change handler | | `className` | `string \| (values) => string` | - | Backdrop CSS classes | | `UNSTABLE_portalContainer` | `HTMLElement` | - | Custom portal container | ### AlertDialog.Container | Prop | Type | Default | Description | | ----------- | ----------------------------------------- | -------- | ------------------------- | | `placement` | `"auto" \| "center" \| "top" \| "bottom"` | `"auto"` | Dialog position on screen | | `size` | `"xs" \| "sm" \| "md" \| "lg" \| "cover"` | `"md"` | Alert Dialog size variant | | `className` | `string \| (values) => string` | - | Container CSS classes | ### AlertDialog.Dialog | Prop | Type | Default | Description | | ------------------ | ------------------------------------- | --------------- | -------------------------- | | `children` | `ReactNode \| ({close}) => ReactNode` | - | Content or render function | | `className` | `string` | - | CSS classes | | `role` | `string` | `"alertdialog"` | ARIA role | | `aria-label` | `string` | - | Accessibility label | | `aria-labelledby` | `string` | - | ID of label element | | `aria-describedby` | `string` | - | ID of description element | ### AlertDialog.Header | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------------------------- | | `children` | `ReactNode` | - | Header content (typically Icon and Heading) | | `className` | `string` | - | CSS classes | ### AlertDialog.Heading | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------ | | `children` | `ReactNode` | - | Heading text | | `className` | `string` | - | CSS classes | ### AlertDialog.Body | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------ | | `children` | `ReactNode` | - | Body content | | `className` | `string` | - | CSS classes | ### AlertDialog.Footer | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ----------------------------------------- | | `children` | `ReactNode` | - | Footer content (typically action buttons) | | `className` | `string` | - | CSS classes | ### AlertDialog.Icon | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------- | ---------- | -------------------- | | `children` | `ReactNode` | - | Custom icon element | | `status` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"danger"` | Status color variant | | `className` | `string` | - | CSS classes | ### AlertDialog.CloseTrigger | Prop | Type | Default | Description | | ----------- | ------------------------------ | ------- | ------------------- | | `children` | `ReactNode` | - | Custom close button | | `className` | `string \| (values) => string` | - | CSS classes | ### useOverlayState Hook ```tsx import {useOverlayState} from "@heroui/react"; const state = useOverlayState({ defaultOpen: false, onOpenChange: (isOpen) => console.log(isOpen), }); state.isOpen; // Current state state.open(); // Open dialog state.close(); // Close dialog state.toggle(); // Toggle state state.setOpen(); // Set state directly ``` ## Accessibility Implements [WAI-ARIA AlertDialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/): * **Focus trap**: Focus locked within alert dialog * **Keyboard**: `ESC` closes (when enabled), `Tab` cycles elements * **Screen readers**: Proper ARIA attributes with `role="alertdialog"` * **Scroll lock**: Body scroll disabled when open * **Required action**: Defaults to requiring explicit user action (no backdrop/ESC dismiss) </page> <page url="/docs/react/components/modal"> # Modal **Category**: react **URL**: https://v3.heroui.com/docs/react/components/modal **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(overlays)/modal.mdx > Dialog overlay for focused user interactions and important content ## Import ```tsx import { Modal } from "@heroui/react"; ``` ### Usage ```tsx "use client"; import {Rocket} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function Default() { return ( <Modal> <Button variant="secondary">Open Modal</Button> <Modal.Backdrop> <Modal.Container> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Icon className="bg-default text-foreground"> <Rocket className="size-5" /> </Modal.Icon> <Modal.Heading>Welcome to HeroUI</Modal.Heading> </Modal.Header> <Modal.Body> <p> A beautiful, fast, and modern React UI library for building accessible and customizable web applications with ease. </p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="close"> Continue </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); } ``` ### Anatomy Import the Modal component and access all parts using dot notation. ```tsx import {Modal, Button} from "@heroui/react"; export default () => ( <Modal> <Button>Open Modal</Button> <Modal.Backdrop> <Modal.Container> <Modal.Dialog> <Modal.CloseTrigger /> {/* Optional: Close button */} <Modal.Header> <Modal.Icon /> {/* Optional: Icon */} <Modal.Heading /> </Modal.Header> <Modal.Body /> <Modal.Footer /> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); ``` ### Placement ```tsx "use client"; import {Rocket} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function Placements() { const placements = ["auto", "top", "center", "bottom"] as const; return ( <div className="flex flex-wrap gap-4"> {placements.map((placement) => ( <Modal key={placement}> <Button variant="secondary"> {placement.charAt(0).toUpperCase() + placement.slice(1)} </Button> <Modal.Backdrop> <Modal.Container placement={placement}> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Icon className="bg-default text-foreground"> <Rocket className="size-5" /> </Modal.Icon> <Modal.Heading> Placement: {placement.charAt(0).toUpperCase() + placement.slice(1)} </Modal.Heading> </Modal.Header> <Modal.Body> <p> This modal uses the <code>{placement}</code> placement option. Try different placements to see how the modal positions itself on the screen. </p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="close"> Continue </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ))} </div> ); } ``` ### Backdrop Variants ```tsx "use client"; import {Rocket} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function BackdropVariants() { const variants = ["opaque", "blur", "transparent"] as const; return ( <div className="flex flex-wrap gap-4"> {variants.map((variant) => ( <Modal key={variant}> <Button variant="secondary">{variant.charAt(0).toUpperCase() + variant.slice(1)}</Button> <Modal.Backdrop variant={variant}> <Modal.Container> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Icon className="bg-default text-foreground"> <Rocket className="size-5" /> </Modal.Icon> <Modal.Heading> Backdrop: {variant.charAt(0).toUpperCase() + variant.slice(1)} </Modal.Heading> </Modal.Header> <Modal.Body> <p> This modal uses the <code>{variant}</code> backdrop variant. Compare the different visual effects: opaque provides full opacity, blur adds a backdrop filter, and transparent removes the background. </p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="close"> Continue </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ))} </div> ); } ``` ### Sizes ```tsx "use client"; import {Rocket} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function Sizes() { const sizes = ["xs", "sm", "md", "lg", "cover", "full"] as const; return ( <div className="flex flex-wrap gap-4"> {sizes.map((size) => ( <Modal key={size}> <Button variant="secondary">{size.charAt(0).toUpperCase() + size.slice(1)}</Button> <Modal.Backdrop> <Modal.Container size={size}> <Modal.Dialog> <Modal.CloseTrigger /> <Modal.Header> <Modal.Icon className="bg-default text-foreground"> <Rocket className="size-5" /> </Modal.Icon> <Modal.Heading> Size: {size.charAt(0).toUpperCase() + size.slice(1)} </Modal.Heading> </Modal.Header> <Modal.Body> <p> {size === "cover" ? ( <> This modal uses the <code>cover</code> size variant. It spans the full screen with margins: 16px on mobile and 40px on desktop. Maintains rounded corners and standard padding. Perfect for cover-style content that needs maximum width while preserving modal aesthetics. </> ) : size === "full" ? ( <> This modal uses the <code>full</code> size variant. It occupies the entire viewport without any margins, rounded corners, or shadows, creating a true fullscreen experience. Ideal for immersive content or full-page interactions. </> ) : ( <> This modal uses the <code>{size}</code> size variant. On mobile devices, all sizes adapt to near full-width for optimal viewing. On desktop, each size provides a different maximum width to suit various content needs. </> )} </p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Confirm</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ))} </div> ); } ``` ### Custom Backdrop ```tsx "use client"; import {Sparkles} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function CustomBackdrop() { return ( <Modal> <Button variant="secondary">Custom Backdrop</Button> <Modal.Backdrop className="bg-linear-to-t from-black/80 via-black/40 to-transparent dark:from-zinc-800/80 dark:via-zinc-800/40" variant="blur" > <Modal.Container> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.Header className="items-center text-center"> <Modal.Icon className="bg-accent-soft text-accent-soft-foreground"> <Sparkles className="size-5" /> </Modal.Icon> <Modal.Heading>Premium Backdrop</Modal.Heading> </Modal.Header> <Modal.Body> <p> This backdrop features a sophisticated gradient that transitions from a dark color at the bottom to complete transparency at the top, combined with a smooth blur effect. The gradient automatically adapts its intensity for optimal contrast in both light and dark modes. </p> </Modal.Body> <Modal.Footer className="flex-col-reverse"> <Button className="w-full" slot="close"> Amazing! </Button> <Button className="w-full" slot="close" variant="secondary"> Close </Button> </Modal.Footer> <Modal.CloseTrigger /> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); } ``` ### Dismiss Behavior ```tsx "use client"; import {CircleInfo} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function DismissBehavior() { return ( <div className="flex max-w-sm flex-col gap-6"> <div className="flex flex-col gap-2"> <h3 className="text-lg font-semibold">isDismissable</h3> <p className="text-sm text-muted"> Controls whether the modal can be dismissed by clicking the overlay backdrop. Defaults to{" "} <code>true</code>. Set to <code>false</code> to require explicit close action. </p> <Modal> <Button variant="secondary">Open Modal</Button> <Modal.Backdrop isDismissable={false}> <Modal.Container> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Icon className="bg-default text-foreground"> <CircleInfo className="size-5" /> </Modal.Icon> <Modal.Heading>isDismissable = false</Modal.Heading> <p className="text-sm leading-5 text-muted"> Clicking the backdrop won't close this modal </p> </Modal.Header> <Modal.Body> <p> Try clicking outside this modal on the overlay - it won't close. You must use the close button or press ESC to dismiss it. </p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="close"> Close </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> </div> <div className="flex flex-col gap-2"> <h3 className="text-lg font-semibold">isKeyboardDismissDisabled</h3> <p className="text-sm text-muted"> Controls whether the ESC key can dismiss the modal. When set to <code>true</code>, the ESC key will be disabled and users must use explicit close actions. </p> <Modal> <Button variant="secondary">Open Modal</Button> <Modal.Backdrop isKeyboardDismissDisabled> <Modal.Container> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Icon className="bg-default text-foreground"> <CircleInfo className="size-5" /> </Modal.Icon> <Modal.Heading>isKeyboardDismissDisabled = true</Modal.Heading> <p className="text-sm leading-5 text-muted">ESC key is disabled</p> </Modal.Header> <Modal.Body> <p> Press ESC - nothing happens. You must use the close button or click the overlay backdrop to dismiss this modal. </p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="close"> Close </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> </div> </div> ); } ``` ### Close Methods ```tsx "use client"; import {CircleCheck, CircleInfo} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function CloseMethods() { return ( <div className="flex max-w-2xl flex-col gap-8"> <div className="flex flex-col gap-2"> <h3 className="text-lg font-semibold">Using slot="close"</h3> <p className="text-sm text-muted"> The simplest way to close a modal. Add <code>slot="close"</code> to any Button component within the modal. When clicked, it will automatically close the modal. </p> <Modal> <Button variant="secondary">Open Modal</Button> <Modal.Backdrop> <Modal.Container> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.Header> <Modal.Icon className="bg-accent-soft text-accent-soft-foreground"> <CircleInfo className="size-5" /> </Modal.Icon> <Modal.Heading>Using slot="close"</Modal.Heading> </Modal.Header> <Modal.Body> <p> Click either button below - both have <code>slot="close"</code> and will close the modal automatically. </p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Confirm</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> </div> <div className="flex flex-col gap-2"> <h3 className="text-lg font-semibold">Using Dialog render props</h3> <p className="text-sm text-muted"> Access the <code>close</code> method from the Dialog's render props. This gives you full control over when and how to close the modal, allowing you to add custom logic before closing. </p> <Modal> <Button variant="secondary">Open Modal</Button> <Modal.Backdrop> <Modal.Container> <Modal.Dialog className="sm:max-w-[360px]"> {(renderProps) => ( <> <Modal.Header> <Modal.Icon className="bg-success-soft text-success-soft-foreground"> <CircleCheck className="size-5" /> </Modal.Icon> <Modal.Heading>Using Dialog render props</Modal.Heading> </Modal.Header> <Modal.Body> <p> The buttons below use the <code>close</code> method from render props. You can add validation or other logic before calling{" "} <code>renderProps.close()</code>. </p> </Modal.Body> <Modal.Footer> <Button variant="secondary" onPress={() => renderProps.close()}> Cancel </Button> <Button onPress={() => renderProps.close()}>Confirm</Button> </Modal.Footer> </> )} </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> </div> </div> ); } ``` ### Scroll Behavior ```tsx "use client"; import {Button, Label, Modal, Radio, RadioGroup} from "@heroui/react"; import {useState} from "react"; export function ScrollComparison() { const [scroll, setScroll] = useState<"inside" | "outside">("inside"); return ( <div className="flex flex-col gap-4"> <RadioGroup orientation="horizontal" value={scroll} onChange={(value) => setScroll(value as "inside" | "outside")} > <Radio value="inside"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Label>Inside</Label> </Radio> <Radio value="outside"> <Radio.Control> <Radio.Indicator /> </Radio.Control> <Label>Outside</Label> </Radio> </RadioGroup> <Modal> <Button variant="secondary"> Open Modal ({scroll.charAt(0).toUpperCase() + scroll.slice(1)}) </Button> <Modal.Backdrop> <Modal.Container scroll={scroll}> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.Header> <Modal.Heading> Scroll: {scroll.charAt(0).toUpperCase() + scroll.slice(1)} </Modal.Heading> <p className="text-sm leading-5 text-muted"> Compare scroll behaviors - inside keeps content scrollable within the modal, outside allows page scrolling </p> </Modal.Header> <Modal.Body> {Array.from({length: 30}).map((_, i) => ( <p key={i} className="mb-3"> Paragraph {i + 1}: Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. </p> ))} </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Confirm</Button> </Modal.Footer> <Modal.CloseTrigger /> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> </div> ); } ``` ### Controlled State ```tsx "use client"; import {CircleCheck} from "@gravity-ui/icons"; import {Button, Modal, useOverlayState} from "@heroui/react"; import React from "react"; export function Controlled() { const [isOpen, setIsOpen] = React.useState(false); const state = useOverlayState(); return ( <div className="flex max-w-md flex-col gap-8"> <div className="flex flex-col gap-3"> <h3 className="text-lg font-semibold text-foreground">With React.useState()</h3> <p className="text-sm leading-relaxed text-pretty text-muted"> Control the modal using React's <code className="text-foreground">useState</code> hook for simple state management. Perfect for basic use cases. </p> <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm"> <div className="flex w-full items-center justify-between"> <p className="text-xs text-muted"> Status:{" "} <span className="font-mono font-medium text-foreground"> {isOpen ? "open" : "closed"} </span> </p> </div> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}> Open Modal </Button> <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}> Toggle </Button> </div> </div> <Modal.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}> <Modal.Container> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Icon className="bg-accent-soft text-accent-soft-foreground"> <CircleCheck className="size-5" /> </Modal.Icon> <Modal.Heading>Controlled with useState()</Modal.Heading> </Modal.Header> <Modal.Body> <p> This modal is controlled by React's <code>useState</code> hook. Pass{" "} <code>isOpen</code> and <code>onOpenChange</code> props to manage the modal state externally. </p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Confirm</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </div> <div className="flex flex-col gap-3"> <h3 className="text-lg font-semibold text-foreground">With useOverlayState()</h3> <p className="text-sm leading-relaxed text-pretty text-muted"> Use the <code className="text-foreground">useOverlayState</code> hook for a cleaner API with convenient methods like <code>open()</code>, <code>close()</code>, and{" "} <code>toggle()</code>. </p> <div className="flex flex-col items-start gap-3 rounded-2xl bg-surface p-4 shadow-sm"> <div className="flex w-full items-center justify-between"> <p className="text-xs text-muted"> Status:{" "} <span className="font-mono font-medium text-foreground"> {state.isOpen ? "open" : "closed"} </span> </p> </div> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={state.open}> Open Modal </Button> <Button size="sm" variant="tertiary" onPress={state.toggle}> Toggle </Button> </div> </div> <Modal.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}> <Modal.Container> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Icon className="bg-success-soft text-success-soft-foreground"> <CircleCheck className="size-5" /> </Modal.Icon> <Modal.Heading>Controlled with useOverlayState()</Modal.Heading> </Modal.Header> <Modal.Body> <p> The <code>useOverlayState</code> hook provides dedicated methods for common operations. No need to manually create callbacks—just use{" "} <code>state.open()</code>, <code>state.close()</code>, or{" "} <code>state.toggle()</code>. </p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Confirm</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </div> </div> ); } ``` ### With Form ```tsx "use client"; import {Envelope} from "@gravity-ui/icons"; import {Button, Input, Label, Modal, Surface, TextField} from "@heroui/react"; export function WithForm() { return ( <Modal> <Button variant="secondary">Open Contact Form</Button> <Modal.Backdrop> <Modal.Container placement="auto"> <Modal.Dialog className="sm:max-w-md"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Icon className="bg-accent-soft text-accent-soft-foreground"> <Envelope className="size-5" /> </Modal.Icon> <Modal.Heading>Contact Us</Modal.Heading> <p className="mt-1.5 text-sm leading-5 text-muted"> Fill out the form below and we'll get back to you. The modal adapts automatically when the keyboard appears on mobile. </p> </Modal.Header> <Modal.Body className="p-6"> <Surface variant="default"> <form className="flex flex-col gap-4"> <TextField className="w-full" name="name" type="text"> <Label>Name</Label> <Input placeholder="Enter your name" /> </TextField> <TextField className="w-full" name="email" type="email"> <Label>Email</Label> <Input placeholder="Enter your email" /> </TextField> <TextField className="w-full" name="phone" type="tel"> <Label>Phone</Label> <Input placeholder="Enter your phone number" /> </TextField> <TextField className="w-full" name="company"> <Label>Company</Label> <Input placeholder="Enter your company name" /> </TextField> <TextField className="w-full" name="message"> <Label>Message</Label> <Input placeholder="Enter your message" /> </TextField> </form> </Surface> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Send Message</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); } ``` ### Custom Trigger ```tsx "use client"; import {Gear} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function CustomTrigger() { return ( <Modal> <Modal.Trigger className="group flex items-center gap-3 rounded-2xl bg-surface p-4 shadow-xs select-none hover:bg-surface-secondary"> <div className="flex size-12 shrink-0 items-center justify-center rounded-xl bg-accent-soft text-accent-soft-foreground"> <Gear className="size-6" /> </div> <div className="flex flex-1 flex-col gap-0.5"> <p className="text-sm font-semibold">Settings</p> <p className="text-xs text-muted">Manage your preferences</p> </div> </Modal.Trigger> <Modal.Backdrop> <Modal.Container> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Icon className="bg-accent-soft text-accent-soft-foreground"> <Gear className="size-5" /> </Modal.Icon> <Modal.Heading>Settings</Modal.Heading> </Modal.Header> <Modal.Body> <p> Use <code>Modal.Trigger</code> to create custom trigger elements beyond standard buttons. This example shows a card-style trigger with icons and descriptive text. </p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Save</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); } ``` ### Custom Animations ```tsx "use client"; import {ArrowUpFromLine, Sparkles} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; import React from "react"; const iconMap: Record<string, React.ComponentType<{className?: string}>> = { "gravity-ui:arrow-up-from-line": ArrowUpFromLine, "gravity-ui:sparkles": Sparkles, }; export function CustomAnimations() { const animations = [ { classNames: { backdrop: [ "data-[entering]:duration-400", "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]", "data-[exiting]:duration-200", "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]", ].join(" "), container: [ "data-[entering]:animate-in", "data-[entering]:fade-in-0", "data-[entering]:zoom-in-95", "data-[entering]:duration-400", "data-[entering]:ease-[cubic-bezier(0.16,1,0.3,1)]", "data-[exiting]:animate-out", "data-[exiting]:fade-out-0", "data-[exiting]:zoom-out-95", "data-[exiting]:duration-200", "data-[exiting]:ease-[cubic-bezier(0.7,0,0.84,0)]", ].join(" "), }, description: "Physics-based elastic scaling. Simulates a high-damping spring system with fast transient response and prolonged settling time. Ideal for Modals and Popovers.", icon: "gravity-ui:sparkles", name: "Kinematic Scale", }, { classNames: { backdrop: [ "data-[entering]:duration-500", "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]", "data-[exiting]:duration-200", "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]", ].join(" "), container: [ "data-[entering]:animate-in", "data-[entering]:fade-in-0", "data-[entering]:slide-in-from-bottom-4", "data-[entering]:duration-500", "data-[entering]:ease-[cubic-bezier(0.25,1,0.5,1)]", "data-[exiting]:animate-out", "data-[exiting]:fade-out-0", "data-[exiting]:slide-out-to-bottom-2", "data-[exiting]:duration-200", "data-[exiting]:ease-[cubic-bezier(0.5,0,0.75,0)]", ].join(" "), }, description: "Simulates movement through a medium with fluid resistance. Eliminates mechanical linearity for a natural, grounded feel. Perfect for Bottom Sheets or Toasts.", icon: "gravity-ui:arrow-up-from-line", name: "Fluid Slide", }, ]; return ( <div className="flex flex-wrap gap-4"> {animations.map(({classNames, description, icon, name}) => { const IconComponent = iconMap[icon]; return ( <Modal key={name}> <Button variant="secondary">{name}</Button> <Modal.Backdrop className={classNames.backdrop}> <Modal.Container className={classNames.container}> <Modal.Dialog className="sm:max-w-[360px]"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Icon className="bg-default text-foreground"> {!!IconComponent && <IconComponent className="size-5" />} </Modal.Icon> <Modal.Heading>{name} Animation</Modal.Heading> </Modal.Header> <Modal.Body> <p className="mt-1">{description}</p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="tertiary"> Close </Button> <Button slot="close">Try Again</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); })} </div> ); } ``` ### Custom Portal ```tsx "use client"; import {Button, Modal} from "@heroui/react"; import {useCallback, useRef, useState} from "react"; export function CustomPortal() { const portalRef = useRef<HTMLDivElement>(null); const [portalContainer, setPortalContainer] = useState<HTMLElement | null>(null); const setPortalRef = useCallback((node: HTMLDivElement | null) => { portalRef.current = node; setPortalContainer(node); }, []); return ( <div className="flex flex-col gap-4"> <div> <p className="text-sm"> Render modals inside a custom container instead of <code>document.body</code> </p> <p className="text-sm text-muted"> Apply <code className="rounded px-1 py-0.5 text-xs">transform: translateZ(0)</code> to the container to create a new stacking context. </p> </div> <div ref={setPortalRef} className="relative flex h-[380px] items-center justify-center overflow-hidden rounded bg-muted/20" // new stacking context style={{transform: "translate(0)"}} > {!!portalContainer && ( <Modal> <Button>Open Modal</Button> <Modal.Backdrop className="h-full" UNSTABLE_portalContainer={portalContainer}> <Modal.Container className="h-full max-h-full"> <Modal.Dialog className="h-full max-h-full sm:max-w-md"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Heading>Custom Portal</Modal.Heading> </Modal.Header> <Modal.Body> <p className="text-sm text-muted"> 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 nisi ut aliquip ex ea commodo consequat. </p> <p className="text-sm text-muted"> 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 nisi ut aliquip ex ea commodo consequat. </p> <p className="text-sm text-muted"> 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 nisi ut aliquip ex ea commodo consequat. </p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> Close </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> )} </div> </div> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import {Modal, Button} from "@heroui/react"; function CustomModal() { return ( <Modal> <Button>Open Modal</Button> <Modal.Backdrop className="bg-black/80"> <Modal.Container className="items-start pt-20"> <Modal.Dialog className="bg-linear-to-br from-purple-500 to-pink-500 text-white"> <Modal.CloseTrigger /> <Modal.Header> <Modal.Heading>Custom Styled Modal</Modal.Heading> </Modal.Header> <Modal.Body> <p>This modal has custom styling applied via Tailwind classes</p> </Modal.Body> <Modal.Footer> <Button slot="close">Close</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); } ``` ### Customizing the component classes To customize the Modal component classes, you can use the `@layer components` directive. <br /> [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .modal__backdrop { @apply bg-gradient-to-br from-black/50 to-black/70; } .modal__dialog { @apply rounded-2xl border border-white/10 shadow-2xl; } .modal__header { @apply text-center; } .modal__close-trigger { @apply rounded-full bg-white/10 hover:bg-white/20; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Modal component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/modal.css)): #### Base Classes * `.modal__trigger` - Trigger element that opens the modal * `.modal__backdrop` - Overlay backdrop behind the modal * `.modal__container` - Positioning wrapper with placement support * `.modal__dialog` - Modal content container * `.modal__header` - Header section for titles and icons * `.modal__body` - Main content area * `.modal__footer` - Footer section for actions * `.modal__close-trigger` - Close button element #### Backdrop Variants * `.modal__backdrop--opaque` - Opaque colored backdrop (default) * `.modal__backdrop--blur` - Blurred backdrop with glass effect * `.modal__backdrop--transparent` - Transparent backdrop (no overlay) #### Scroll Variants * `.modal__container--scroll-outside` - Enables scrolling the entire modal * `.modal__dialog--scroll-inside` - Constrains modal height for body scrolling * `.modal__body--scroll-inside` - Makes only the body scrollable * `.modal__body--scroll-outside` - Allows full-page scrolling ### Interactive States The component supports these interactive states: * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` - Applied to trigger, dialog, and close button * **Hover**: `:hover` or `[data-hovered="true"]` - Applied to close button on hover * **Active**: `:active` or `[data-pressed="true"]` - Applied to close button when pressed * **Entering**: `[data-entering]` - Applied during modal opening animation * **Exiting**: `[data-exiting]` - Applied during modal closing animation * **Placement**: `[data-placement="*"]` - Applied based on modal position (auto, top, center, bottom) ## API Reference ### Modal | Prop | Type | Default | Description | | ---------- | ----------- | ------- | ------------------------------ | | `children` | `ReactNode` | - | Trigger and container elements | ### Modal.Trigger | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `children` | `ReactNode` | - | Custom trigger content | | `className` | `string` | - | CSS classes | ### Modal.Backdrop | Prop | Type | Default | Description | | --------------------------- | ------------------------------------- | ---------- | ------------------------- | | `variant` | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | Backdrop overlay style | | `isDismissable` | `boolean` | `true` | Close on backdrop click | | `isKeyboardDismissDisabled` | `boolean` | `false` | Disable ESC key to close | | `isOpen` | `boolean` | - | Controlled open state | | `onOpenChange` | `(isOpen: boolean) => void` | - | Open state change handler | | `className` | `string \| (values) => string` | - | Backdrop CSS classes | | `UNSTABLE_portalContainer` | `HTMLElement` | - | Custom portal container | ### Modal.Container | Prop | Type | Default | Description | | ----------- | --------------------------------------------------- | ---------- | ------------------------ | | `placement` | `"auto" \| "center" \| "top" \| "bottom"` | `"auto"` | Modal position on screen | | `scroll` | `"inside" \| "outside"` | `"inside"` | Scroll behavior | | `size` | `"xs" \| "sm" \| "md" \| "lg" \| "cover" \| "full"` | `"md"` | Modal size variant | | `className` | `string \| (values) => string` | - | Container CSS classes | ### Modal.Dialog | Prop | Type | Default | Description | | ------------------ | ------------------------------------- | ---------- | -------------------------- | | `children` | `ReactNode \| ({close}) => ReactNode` | - | Content or render function | | `className` | `string \| (values) => string` | - | CSS classes | | `role` | `string` | `"dialog"` | ARIA role | | `aria-label` | `string` | - | Accessibility label | | `aria-labelledby` | `string` | - | ID of label element | | `aria-describedby` | `string` | - | ID of description element | ### Modal.Header | Prop | Type | Default | Description | | ----------- | ----------- | ------- | -------------- | | `children` | `ReactNode` | - | Header content | | `className` | `string` | - | CSS classes | ### Modal.Body | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------ | | `children` | `ReactNode` | - | Body content | | `className` | `string` | - | CSS classes | ### Modal.Footer | Prop | Type | Default | Description | | ----------- | ----------- | ------- | -------------- | | `children` | `ReactNode` | - | Footer content | | `className` | `string` | - | CSS classes | ### Modal.CloseTrigger | Prop | Type | Default | Description | | ----------- | ------------------------------ | ------- | ------------------- | | `children` | `ReactNode` | - | Custom close button | | `className` | `string \| (values) => string` | - | CSS classes | ### useOverlayState Hook ```tsx import {useOverlayState} from "@heroui/react"; const state = useOverlayState({ defaultOpen: false, onOpenChange: (isOpen) => console.log(isOpen), }); state.isOpen; // Current state state.open(); // Open modal state.close(); // Close modal state.toggle(); // Toggle state state.setOpen(); // Set state directly ``` ## Accessibility Implements [WAI-ARIA Dialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/): * **Focus trap**: Focus locked within modal * **Keyboard**: `ESC` closes (when enabled), `Tab` cycles elements * **Screen readers**: Proper ARIA attributes * **Scroll lock**: Body scroll disabled when open </page> <page url="/docs/react/components/popover"> # Popover **Category**: react **URL**: https://v3.heroui.com/docs/react/components/popover **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(overlays)/popover.mdx > Displays rich content in a portal triggered by a button or any custom element ## Import ```tsx import { Popover } from '@heroui/react'; ``` ### Usage ```tsx import {Button, Popover} from "@heroui/react"; export function PopoverBasic() { return ( <div className="flex items-center gap-4"> <Popover> <Button>Click me</Button> <Popover.Content className="max-w-64"> <Popover.Dialog> <Popover.Heading>Popover Title</Popover.Heading> <p className="mt-2 text-sm text-muted"> This is the popover content. You can put any content here. </p> </Popover.Dialog> </Popover.Content> </Popover> </div> ); } ``` ### Anatomy Import the Popover component and access all parts using dot notation. ```tsx import { Popover } from '@heroui/react'; export default () => ( <Popover> <Popover.Trigger/> <Popover.Content> <Popover.Arrow /> <Popover.Dialog> <Popover.Heading/> {/* content goes here */} </Popover.Dialog> </Popover.Content> </Popover> ) ``` ### With Arrow ```tsx import {Ellipsis} from "@gravity-ui/icons"; import {Button, Popover} from "@heroui/react"; export function PopoverWithArrow() { return ( <div className="flex items-center gap-4"> <Popover> <Button variant="secondary">With Arrow</Button> <Popover.Content className="max-w-64"> <Popover.Dialog> <Popover.Arrow /> <Popover.Heading>Popover with Arrow</Popover.Heading> <p className="mt-2 text-sm text-muted"> The arrow shows which element triggered the popover. </p> </Popover.Dialog> </Popover.Content> </Popover> <Popover> <Button isIconOnly variant="tertiary"> <Ellipsis /> </Button> <Popover.Content className="max-w-64" offset={10}> <Popover.Dialog> <Popover.Arrow /> <Popover.Heading>Popover with Arrow</Popover.Heading> <p className="mt-2 text-sm text-muted"> The arrow shows which element triggered the popover. </p> </Popover.Dialog> </Popover.Content> </Popover> </div> ); } ``` ### Placement ```tsx import {Button, Popover} from "@heroui/react"; export function PopoverPlacement() { return ( <div className="grid grid-cols-3 gap-4"> <div /> <Popover> <Button className="w-full" variant="tertiary"> Top </Button> <Popover.Content placement="top"> <Popover.Dialog> <Popover.Arrow /> <p className="text-sm">Top placement</p> </Popover.Dialog> </Popover.Content> </Popover> <div /> <Popover> <Button className="w-full" variant="tertiary"> Left </Button> <Popover.Content placement="left"> <Popover.Dialog> <Popover.Arrow /> <p className="text-sm">Left placement</p> </Popover.Dialog> </Popover.Content> </Popover> <div className="flex items-center justify-center"> <span className="text-sm text-muted">Click buttons</span> </div> <Popover> <Button className="w-full" variant="tertiary"> Right </Button> <Popover.Content placement="right"> <Popover.Dialog> <Popover.Arrow /> <p className="text-sm">Right placement</p> </Popover.Dialog> </Popover.Content> </Popover> <div /> <Popover> <Button className="w-full" variant="tertiary"> Bottom </Button> <Popover.Content placement="bottom"> <Popover.Dialog> <Popover.Arrow /> <p className="text-sm">Bottom placement</p> </Popover.Dialog> </Popover.Content> </Popover> <div /> </div> ); } ``` ### Interactive Content ```tsx "use client"; import {Avatar, Button, Popover} from "@heroui/react"; import {useState} from "react"; export function PopoverInteractive() { const [isFollowing, setIsFollowing] = useState(false); return ( <div className="flex items-center gap-6"> <Popover> <Popover.Trigger aria-label="User profile"> <div className="flex items-center gap-2"> <Avatar size="sm"> <Avatar.Image alt="Sarah Johnson" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=1" /> <Avatar.Fallback>SJ</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <p className="text-sm font-medium">Sarah Johnson</p> <p className="text-xs text-muted">@sarahj</p> </div> </div> </Popover.Trigger> <Popover.Content className="w-[320px]"> <Popover.Dialog> <Popover.Heading> <div className="flex items-center justify-between"> <div className="flex items-center gap-3"> <Avatar size="md"> <Avatar.Image alt="Sarah Johnson" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=1" /> <Avatar.Fallback>SJ</Avatar.Fallback> </Avatar> <div> <p className="font-semibold">Sarah Johnson</p> <p className="text-sm text-muted">@sarahj</p> </div> </div> <Button className="rounded-full" size="sm" variant={isFollowing ? "tertiary" : "primary"} onPress={() => setIsFollowing(!isFollowing)} > {isFollowing ? "Following" : "Follow"} </Button> </div> </Popover.Heading> <p className="mt-3 text-sm text-muted"> Product designer and creative director. Building beautiful experiences that matter. </p> <div className="mt-3 flex gap-4"> <div> <span className="font-semibold">892</span> <span className="ml-1 text-sm text-muted">Following</span> </div> <div> <span className="font-semibold">12.5K</span> <span className="ml-1 text-sm text-muted">Followers</span> </div> </div> </Popover.Dialog> </Popover.Content> </Popover> </div> ); } ``` ## Related Components * **Button**: Allows a user to perform an action * **Tooltip**: Contextual information on hover or focus * **Select**: Dropdown select control ### Custom Render Function ```tsx "use client"; import {Button, Popover} from "@heroui/react"; export function CustomRenderFunction() { return ( <div className="flex items-center gap-4"> <Popover> <Button>Click me</Button> <Popover.Content className="max-w-64" render={(props) => <div {...props} data-custom="foo" />} > <Popover.Dialog> <Popover.Heading>Popover Title</Popover.Heading> <p className="mt-2 text-sm text-muted"> This is the popover content. You can put any content here. </p> </Popover.Dialog> </Popover.Content> </Popover> </div> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import { Popover, Button } from '@heroui/react'; function CustomPopover() { return ( <Popover> <Popover.Trigger> <Button>Open</Button> </Popover.Trigger> <Popover.Content className="bg-accent text-accent-foreground"> <Popover.Dialog> <h3>Custom Styled</h3> <p>This popover has custom styling</p> </Popover.Dialog> </Popover.Content> </Popover> ); } ``` ### Customizing the component classes To customize the Popover component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .popover { @apply rounded-xl shadow-2xl; } .popover__dialog { @apply p-4; } .popover__heading { @apply text-lg font-bold; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Popover component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/popover.css)): #### Base Classes * `.popover` - Base popover container styles * `.popover__dialog` - Dialog content wrapper * `.popover__heading` - Heading text styles * `.popover__trigger` - Trigger element styles ### Interactive States The component supports animation states: * **Entering**: `[data-entering]` - Applied during popover appearance * **Exiting**: `[data-exiting]` - Applied during popover disappearance * **Placement**: `[data-placement="*"]` - Applied based on popover position * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` ## API Reference ### Popover Props | Prop | Type | Default | Description | | -------------- | --------------------------- | ------- | ---------------------------------------- | | `children` | `React.ReactNode` | - | Trigger and content elements | | `isOpen` | `boolean` | - | Controls popover visibility (controlled) | | `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) | | `onOpenChange` | `(isOpen: boolean) => void` | - | Called when open state changes | ### Popover.Content Props | Prop | Type | Default | Description | | ------------ | -------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Content to display in the popover | | `placement` | `"top" \| "bottom" \| "left" \| "right"` (and variants) | `"bottom"` | Placement of the popover | | `offset` | `number` | `8` | Distance from the trigger element | | `shouldFlip` | `boolean` | `true` | Whether popover can change orientation to fit | | `className` | `string` | - | Additional CSS classes | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, PopoverRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Popover.Dialog Props | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ---------------------- | | `children` | `React.ReactNode` | - | Dialog content | | `className` | `string` | - | Additional CSS classes | ### Popover.Trigger Props | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | --------------------------------- | | `children` | `React.ReactNode` | - | Element that triggers the popover | | `className` | `string` | - | Additional CSS classes | ### Popover.Arrow Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Custom arrow element | | `className` | `string` | - | Additional CSS classes | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, OverlayArrowRenderProps>` | - | Overrides the default DOM element with a custom render function. | </page> <page url="/docs/react/components/toast"> # Toast **Category**: react **URL**: https://v3.heroui.com/docs/react/components/toast **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(overlays)/toast.mdx > Display temporary notifications and messages to users with automatic dismissal and customizable placement ## Import ```tsx import { Toast, toast } from '@heroui/react'; ``` ## Setup Render the provider in the root of your app. ```tsx import { Toast, Button, toast } from '@heroui/react'; function App() { return ( <div> <Toast.Provider /> <Button onPress={() => toast("Simple message")}> Show toast </Button> </div> ); } ``` ### Usage ```tsx "use client"; import {Persons} from "@gravity-ui/icons"; import {Button, toast} from "@heroui/react"; export function Default() { return ( <div className="flex h-full max-w-xl flex-col items-center justify-center"> <Button size="sm" variant="secondary" onPress={() => { toast("You have been invited to join a team", { actionProps: { children: "Dismiss", onPress: () => toast.clear(), variant: "tertiary", }, description: "Bob sent you an invitation to join HeroUI team", indicator: <Persons />, variant: "default", }); }} > Show toast </Button> </div> ); } ``` ### Simple Toasts ```tsx "use client"; import {Button, toast} from "@heroui/react"; export function Simple() { return ( <div className="flex h-full max-w-xl flex-col items-center justify-center"> <div className="flex w-full flex-wrap items-center justify-center gap-4"> <Button size="sm" variant="secondary" onPress={() => toast("Simple message")}> Default </Button> <Button size="sm" variant="secondary" onPress={() => toast.success("Operation completed")}> Success </Button> <Button size="sm" variant="secondary" onPress={() => toast.info("New update available")}> Info </Button> <Button size="sm" variant="secondary" onPress={() => toast.warning("Please check your settings")} > Warning </Button> <Button size="sm" variant="secondary" onPress={() => toast.danger("Something went wrong")}> Error </Button> </div> </div> ); } ``` ### Variants ```tsx "use client"; import {HardDrive, Persons} from "@gravity-ui/icons"; import {Button, toast} from "@heroui/react"; const noop = () => {}; export function Variants() { return ( <div className="flex h-full max-w-xl flex-col items-center justify-center"> <div className="flex w-full flex-wrap items-center justify-center gap-4"> <Button size="sm" variant="tertiary" onPress={() => { toast("You have been invited to join a team", { actionProps: { children: "Dismiss", onPress: () => toast.clear(), variant: "tertiary", }, description: "Bob sent you an invitation to join HeroUI team", indicator: <Persons />, variant: "default", }); }} > Default toast </Button> <Button size="sm" variant="secondary" onPress={() => toast.info("You have 2 credits left", { actionProps: {children: "Upgrade", onPress: noop}, description: "Get a paid plan for more credits", }) } > Accent toast </Button> <Button className="text-success" size="sm" variant="tertiary" onPress={() => toast.success("You have upgraded your plan", { actionProps: { children: "Billing", className: "bg-success text-success-foreground", onPress: noop, }, description: "You can continue using HeroUI Chat", }) } > Success toast </Button> <Button className="text-warning" size="sm" variant="tertiary" onPress={() => toast.warning("You have no credits left", { actionProps: { children: "Upgrade", className: "bg-warning text-warning-foreground", onPress: noop, }, description: "Upgrade to a paid plan to continue", }) } > Warning toast </Button> <Button size="sm" variant="danger-soft" onPress={() => toast.danger("Storage is full", { actionProps: {children: "Remove", onPress: noop, variant: "danger"}, description: "Remove files to release space. Adding more text to demonstrate longer content display", indicator: <HardDrive />, }) } > Danger toast </Button> </div> </div> ); } ``` ### Custom Indicators ```tsx "use client"; import {Star} from "@gravity-ui/icons"; import {Button, toast} from "@heroui/react"; export function CustomIndicator() { return ( <div className="flex h-full max-w-xl flex-col items-center justify-center"> <Button size="sm" variant="secondary" onPress={() => toast("Custom icon indicator", { indicator: <Star />, }) } > Custom indicator </Button> </div> ); } ``` ### Promise & Loading ```tsx "use client"; import {Button, toast} from "@heroui/react"; const uploadFile = (): Promise<{filename: string; size: number}> => { return new Promise<{filename: string; size: number}>((resolve) => { setTimeout(() => resolve({filename: "document.pdf", size: 1024}), 2000); }); }; const createEvent = (): Promise<never> => { return new Promise<never>((_, reject) => { setTimeout(() => reject(new Error("Network error. Please try again.")), 2000); }); }; const saveData = (): Promise<{count: number}> => { return new Promise<{count: number}>((resolve, reject) => { setTimeout(() => { if (Math.random() > 0.5) { resolve({count: 42}); } else { reject(new Error("Failed to save data")); } }, 2000); }); }; const fetchUser = (): Promise<{name: string; email: string}> => { return new Promise<{name: string; email: string}>((resolve) => { setTimeout(() => resolve({email: "john@example.com", name: "John Doe"}), 2000); }); }; export function PromiseDemo() { return ( <div className="flex h-full max-w-2xl flex-col items-center justify-center gap-8"> {/* Promise API Section */} <div className="w-full space-y-3"> <div className="text-center"> <h3 className="text-sm font-medium">Using toast.promise()</h3> <p className="text-xs text-muted"> Automatically handles loading, success, and error states </p> </div> <div className="flex w-full flex-wrap items-center justify-center gap-4"> <Button size="sm" variant="secondary" onPress={() => { toast.promise(uploadFile(), { error: "Failed to upload file", loading: "Uploading file...", success: (data) => `File ${data.filename} uploaded (${data.size}KB)`, }); }} > Upload file </Button> <Button size="sm" variant="secondary" onPress={() => { toast.promise(createEvent(), { error: (err) => err.message, loading: "Creating event...", success: "Event created", }); }} > Create event (error) </Button> <Button size="sm" variant="secondary" onPress={() => { toast.promise(saveData(), { error: (err) => err.message, loading: "Saving changes...", success: (data) => `Saved ${data.count} items`, }); }} > Save data (random) </Button> <Button size="sm" variant="secondary" onPress={() => { toast.promise(fetchUser(), { error: "Failed to fetch user", loading: "Loading user...", success: (data) => `Welcome back, ${data.name}!`, }); }} > Fetch user </Button> </div> </div> {/* Manual Loading Section */} <div className="w-full space-y-3"> <div className="text-center"> <h3 className="text-sm font-medium">Manual Loading State</h3> <p className="text-xs text-muted">Manually control loading state with isLoading prop</p> </div> <div className="flex w-full flex-wrap items-center justify-center gap-4"> <Button size="sm" variant="secondary" onPress={() => { const loadingId = toast("Uploading file...", { description: "Please wait while we upload your file", isLoading: true, timeout: 0, }); setTimeout(() => { toast.close(loadingId); toast.success("File uploaded", { description: "Your file has been uploaded successfully", }); }, 3000); }} > Upload with loading </Button> <Button size="sm" variant="secondary" onPress={() => { const loadingId = toast("Processing payment...", { isLoading: true, timeout: 0, }); setTimeout(() => { toast.close(loadingId); toast.success("Payment processed", { description: "Your payment has been processed successfully", }); }, 2500); }} > Payment processing </Button> <Button size="sm" variant="secondary" onPress={() => { const loadingId = toast("Saving changes...", { isLoading: true, timeout: 0, }); setTimeout(() => { toast.close(loadingId); toast.danger("Failed to save", { description: "Please try again", }); }, 2000); }} > Loading to error </Button> </div> </div> </div> ); } ``` ### Callbacks ```tsx "use client"; import {Button, toast} from "@heroui/react"; import React from "react"; export function Callbacks() { const [closedHistory, setClosedHistory] = React.useState<Array<{message: string; time: string}>>( [], ); const addToHistory = (message: string) => { const time = new Date().toLocaleTimeString(); setClosedHistory((prev) => [{message, time}, ...prev].slice(0, 5)); }; return ( <div className="flex h-full max-w-2xl flex-col items-center justify-center gap-6"> {/* Toast Buttons */} <div className="flex w-full flex-wrap items-center justify-center gap-4"> <Button size="sm" variant="secondary" onPress={() => toast("File saved", { onClose: () => { addToHistory("File saved (closed after 3 seconds)"); }, timeout: 3000, }) } > Custom timeout (3s) </Button> <Button size="sm" variant="secondary" onPress={() => toast("Changes saved", { onClose: () => { addToHistory("Changes saved (closed after 10 seconds)"); }, timeout: 10000, }) } > Custom timeout (10s) </Button> <Button size="sm" variant="secondary" onPress={() => toast.success("Event created", { onClose: () => { addToHistory("Event created (closed after default timeout)"); }, }) } > With onClose callback </Button> <Button size="sm" variant="secondary" onPress={() => toast("Important notification", { description: "This toast will stay until dismissed", onClose: () => { addToHistory("Important notification (manually closed)"); }, timeout: 0, }) } > Persistent toast </Button> </div> {/* Closed History Panel */} <div className="w-full space-y-2"> <div className="flex items-center justify-between"> <h3 className="text-sm font-medium">Closed History</h3> {closedHistory.length > 0 && ( <Button className="h-6 text-xs" size="sm" variant="tertiary" onPress={() => setClosedHistory([])} > Clear </Button> )} </div> <div className="min-h-[120px] space-y-2 rounded-lg border border-border bg-surface p-4"> {closedHistory.length === 0 ? ( <p className="text-sm text-muted">No toasts closed yet. Try closing one above!</p> ) : ( closedHistory.map((item, index) => ( <div key={`${item.time}-${index}`} className="flex animate-in items-start justify-between gap-3 rounded-md border border-border bg-default px-3 py-2 text-sm duration-200 fade-in slide-in-from-top-2" style={{ animationDelay: `${index * 50}ms`, }} > <div className="flex-1"> <span className="font-medium">{item.message}</span> <span className="ml-2 text-xs text-muted">({item.time})</span> </div> <div className="flex h-5 w-5 shrink-0 items-center justify-center rounded-full bg-success/10 text-success"> <svg className="size-3" fill="none" stroke="currentColor" strokeWidth="2" viewBox="0 0 24 24" > <path d="M5 13l4 4L19 7" strokeLinecap="round" strokeLinejoin="round" /> </svg> </div> </div> )) )} </div> </div> </div> ); } ``` ### Placements ```tsx "use client"; import type {ToastVariants} from "@heroui/react"; import {Button, Toast, ToastQueue} from "@heroui/react"; type Placement = NonNullable<ToastVariants["placement"]>; const placements = ["top start", "top", "top end", "bottom start", "bottom", "bottom end"] as const; // Create a separate queue for each placement const placementQueues = Object.fromEntries( placements.map((p) => [p, new ToastQueue({maxVisibleToasts: 3})]), ) as Record<Placement, ToastQueue>; export function Placements() { const showToast = (placement: Placement) => { placementQueues[placement].add({ description: "Event has been created", title: "Event created", variant: "default", }); }; return ( <div className="flex h-full flex-col items-center justify-center gap-6"> {/* Render a ToastProvider for each placement */} {placements.map((p) => ( <Toast.Provider key={p} placement={p} queue={placementQueues[p]} /> ))} <div className="flex max-w-xs flex-wrap justify-center gap-2"> {placements.map((p) => ( <Button key={p} size="sm" variant="secondary" onPress={() => showToast(p)}> {p} </Button> ))} </div> </div> ); } ``` ### Custom Toast Rendering ```tsx "use client"; import type {ToastContentValue} from "@heroui/react"; import { Button, Toast, ToastContent, ToastDescription, ToastIndicator, ToastQueue, ToastTitle, } from "@heroui/react"; export function CustomToast() { const customQueue = new ToastQueue(); return ( <div className="flex h-full max-w-xl flex-col items-center justify-center"> <Toast.Provider placement="bottom" queue={customQueue}> {({toast: toastItem}) => { const content = toastItem.content as ToastContentValue; return ( <Toast className="rounded-xl border border-border" toast={toastItem} variant={content.variant} > <ToastContent> <div className="flex items-center gap-2"> <ToastIndicator className="text-accent" variant={content.variant} /> <div className="flex flex-col pr-6"> {content.title ? ( <ToastTitle className="text-accent">{content.title}</ToastTitle> ) : null} {content.description ? ( <ToastDescription>{content.description}</ToastDescription> ) : null} </div> </div> </ToastContent> <Toast.CloseButton className="absolute top-1/2 right-2 -translate-y-1/2 border-none bg-transparent opacity-100 [&>svg]:size-4" /> </Toast> ); }} </Toast.Provider> <Button size="sm" variant="secondary" onPress={() => { customQueue.add({ description: "This uses a custom render function", title: "Custom layout toast", variant: "default", }); }} > Custom toast </Button> </div> ); } ``` ### Custom Queues ```tsx "use client"; import {Button, Toast, ToastQueue} from "@heroui/react"; export function CustomQueue() { const notificationQueue = new ToastQueue({maxVisibleToasts: 2}); const errorQueue = new ToastQueue({maxVisibleToasts: 3}); const successQueue = new ToastQueue({maxVisibleToasts: 1}); return ( <div className="flex h-full max-w-4xl items-center justify-center gap-4"> {/* Notification Queue */} <Toast.Provider placement="bottom" queue={notificationQueue} /> <div className="flex justify-center gap-2"> <Button size="sm" variant="secondary" onPress={() => { notificationQueue.add({ description: "You have a new message", title: "New notification", variant: "default", }); }} > Add notification (max 2) </Button> </div> {/* Error Queue */} <Toast.Provider placement="bottom start" queue={errorQueue} /> <div className="flex justify-center gap-2"> <Button size="sm" variant="danger-soft" onPress={() => { errorQueue.add({ description: "Failed to save changes", title: "Error occurred", variant: "danger", }); }} > Add error (max 3) </Button> </div> {/* Success Queue */} <Toast.Provider placement="bottom end" queue={successQueue} /> <div className="flex justify-center gap-2"> <Button className="text-success" size="sm" variant="secondary" onPress={() => { successQueue.add({ description: `Operation ${Date.now()}`, title: "Success!", variant: "success", }); }} > Add success (max 1) </Button> </div> </div> ); } ``` ### Anatomy ```tsx <Toast.Provider> <Toast> <Toast.Indicator /> <Toast.Content> <Toast.Title /> <Toast.Description /> </Toast.Content> <Toast.ActionButton /> <Toast.CloseButton /> </Toast> </Toast.Provider> ``` ## Related Components * **Button**: Allows a user to perform an action * **Alert**: Display important messages and notifications * **CloseButton**: Button for dismissing overlays ## Styling ### Passing Tailwind CSS classes ```tsx <Toast.Provider className="bottom-8 right-8" placement="bottom end" /> ``` ### Customizing the component classes To customize the Toast component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .toast { @apply rounded-xl shadow-lg; } .toast__content { @apply 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 Toast component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toast.css)): #### Base Classes * `.toast` - Base toast container * `.toast__region` - Toast region container * `.toast__content` - Content wrapper for title and description * `.toast__indicator` - Icon/indicator container * `.toast__title` - Toast title text * `.toast__description` - Toast description text * `.toast__action` - Action button container * `.toast__close` - Close button container #### Variant Classes * `.toast--default` - Default gray variant * `.toast--accent` - Accent blue variant * `.toast--success` - Success green variant * `.toast--warning` - Warning yellow/orange variant * `.toast--danger` - Danger red variant ### Interactive States The component supports various states: * **Frontmost**: `[data-frontmost]` - Applied to the topmost visible toast * **Index**: `[data-index]` - Applied based on toast position in stack * **Placement**: `[data-placement="*"]` - Applied based on toast region placement ## API Reference ### Toast.Provider Props | Prop | Type | Default | Description | | ------------------ | --------------------------------------------------------------------------------- | ---------- | ------------------------------------------- | | `placement` | `"top start" \| "top" \| "top end" \| "bottom start" \| "bottom" \| "bottom end"` | `"bottom"` | Placement of the toast region | | `gap` | `number` | `12` | The gap between toasts in pixels | | `maxVisibleToasts` | `number` | `3` | Maximum number of toasts to display at once | | `scaleFactor` | `number` | `0.05` | Scale factor for stacked toasts (0-1) | | `width` | `number \| string` | `460` | Width of the toast in pixels or CSS value | | `queue` | `ToastQueue<T>` | - | Custom toast queue instance | | `children` | `ReactNode \| ((props: {toast: QueuedToast<T>}) => ReactNode)` | - | Custom render function or children | | `className` | `string` | - | Additional CSS classes | ### Toast Props | Prop | Type | Default | Description | | ------------- | ------------------------------------------------------------- | ----------- | -------------------------------------------------- | | `toast` | `QueuedToast<T>` | - | Toast data from queue (required) | | `variant` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Visual variant of the toast | | `placement` | `ToastVariants["placement"]` | - | Placement (inherited from Provider) | | `scaleFactor` | `number` | - | Scale factor (inherited from Provider) | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Toast content (ToastContent, ToastIndicator, etc.) | ### Toast.Content Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | --------------------------------------------------- | | `children` | `ReactNode` | - | Content (typically ToastTitle and ToastDescription) | | `className` | `string` | - | Additional CSS classes | ### Toast.Indicator Props | Prop | Type | Default | Description | | ----------- | -------------------------- | ------- | ------------------------------------------------ | | `variant` | `ToastVariants["variant"]` | - | Variant for default icon | | `children` | `ReactNode` | - | Custom indicator icon (defaults to variant icon) | | `className` | `string` | - | Additional CSS classes | ### Toast.Title Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `children` | `ReactNode` | - | Title text | | `className` | `string` | - | Additional CSS classes | ### Toast.Description Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `children` | `ReactNode` | - | Description text | | `className` | `string` | - | Additional CSS classes | ### Toast.ActionButton Props | Prop | Type | Default | Description | | ------------------ | ----------- | ------- | ---------------------------------- | | `children` | `ReactNode` | - | Action button content | | `className` | `string` | - | Additional CSS classes | | All `Button` props | - | - | Accepts all Button component props | ### Toast.CloseButton Props | Prop | Type | Default | Description | | ----------------------- | -------- | ------- | --------------------------------------- | | `className` | `string` | - | Additional CSS classes | | All `CloseButton` props | - | - | Accepts all CloseButton component props | ### ToastQueue A `ToastQueue` manages the state for a `<Toast.Provider>`. The state is stored outside React so you can trigger toasts from anywhere in your application. #### Constructor Options | Option | Type | Default | Description | | ------------------ | -------------------------- | ------- | ----------------------------------------------------------- | | `maxVisibleToasts` | `number` | `3` | Maximum number of toasts to display at once (visual only) | | `wrapUpdate` | `(fn: () => void) => void` | - | Function to wrap state updates (e.g., for view transitions) | #### Methods | Method | Parameters | Returns | Description | | ----------- | -------------------------------------- | ------------ | -------------------------------------------------------- | | `add` | `(content: T, options?: ToastOptions)` | `string` | Add a toast to the queue, returns toast key | | `close` | `(key: string)` | `void` | Close a toast by its key | | `pauseAll` | `()` | `void` | Pause all toast timers | | `resumeAll` | `()` | `void` | Resume all toast timers | | `clear` | `()` | `void` | Close all toasts | | `subscribe` | `(fn: () => void)` | `() => void` | Subscribe to queue changes, returns unsubscribe function | ### toast Function The default `toast` function provides convenient methods for showing toasts: ```tsx import { toast } from '@heroui/react'; // Basic toast (auto-dismisses after 4 seconds by default) toast("Event has been created"); // Variant methods (also auto-dismiss after 4 seconds by default) toast.success("File saved"); toast.info("New update available"); toast.warning("Please check your settings"); toast.danger("Something went wrong"); // With options toast("Event has been created", { description: "Your event has been scheduled for tomorrow", variant: "default", timeout: 5000, // Custom timeout: 5 seconds onClose: () => console.log("Closed"), actionProps: { children: "View", onPress: () => {}, }, indicator: <CustomIcon />, }); // Promise support (automatically shows loading spinner) toast.promise( uploadFile(), { loading: "Uploading file...", success: (data) => `File ${data.filename} uploaded`, error: "Failed to upload file", } ); // Manual loading state (persistent toast - no auto-dismiss) const loadingId = toast("Creating event...", { isLoading: true, timeout: 0, // Persistent toast that doesn't auto-dismiss }); // Later, close and show result toast.close(loadingId); toast.success("Event created"); // Queue methods toast.close(key); toast.clear(); toast.pauseAll(); toast.resumeAll(); ``` #### toast Options | Option | Type | Default | Description | | ------------- | ------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------ | | `title` | `ReactNode` | - | Toast title (first parameter for variant methods) | | `description` | `ReactNode` | - | Optional description text | | `variant` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Visual variant | | `indicator` | `ReactNode` | - | Custom indicator icon (null to hide) | | `actionProps` | `ButtonProps` | - | Props for action button | | `isLoading` | `boolean` | `false` | Show loading spinner instead of indicator | | `timeout` | `number` | `4000` | Auto-dismiss timeout in milliseconds. Defaults to 4000ms (4 seconds). Set to `0` for persistent toasts that don't auto-dismiss | | `onClose` | `() => void` | - | Callback when toast is closed | #### toast.promise Options | Option | Type | Default | Description | | --------- | -------------------------------------------- | ------- | ------------------------------------------ | | `loading` | `ReactNode` | - | Message shown while promise is pending | | `success` | `ReactNode \| ((data: T) => ReactNode)` | - | Message shown on success (can be function) | | `error` | `ReactNode \| ((error: Error) => ReactNode)` | - | Message shown on error (can be function) | </page> <page url="/docs/react/components/tooltip"> # Tooltip **Category**: react **URL**: https://v3.heroui.com/docs/react/components/tooltip **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(overlays)/tooltip.mdx > Displays informative text when users hover over or focus on an element ## Import ```tsx import { Tooltip } from '@heroui/react'; ``` ### Usage ```tsx import {CircleInfo} from "@gravity-ui/icons"; import {Button, Tooltip} from "@heroui/react"; export function TooltipBasic() { return ( <div className="flex items-center gap-4"> <Tooltip delay={0}> <Button variant="secondary">Hover me</Button> <Tooltip.Content> <p>This is a tooltip</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Button isIconOnly variant="tertiary"> <CircleInfo /> </Button> <Tooltip.Content> <p>More information</p> </Tooltip.Content> </Tooltip> </div> ); } ``` ### Anatomy Import the Tooltip component and access all parts using dot notation. ```tsx import { Tooltip, Button } from '@heroui/react'; export default () => ( <Tooltip> <Tooltip.Trigger> <Button>Hover for tooltip</Button> </Tooltip.Trigger> <Tooltip.Content> <Tooltip.Arrow /> Helpful information about this element </Tooltip.Content> </Tooltip> ) ``` ### With Arrow ```tsx import {Button, Tooltip} from "@heroui/react"; export function TooltipWithArrow() { return ( <div className="flex items-center gap-4"> <Tooltip delay={0}> <Button variant="secondary">With Arrow</Button> <Tooltip.Content showArrow> <Tooltip.Arrow /> <p>Tooltip with arrow indicator</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Button variant="primary">Custom Offset</Button> <Tooltip.Content showArrow offset={12}> <Tooltip.Arrow /> <p>Custom offset from trigger</p> </Tooltip.Content> </Tooltip> </div> ); } ``` ### Placement ```tsx import {Button, Tooltip} from "@heroui/react"; export function TooltipPlacement() { return ( <div className="grid grid-cols-3 gap-4"> <div /> <Tooltip delay={0}> <Button className="w-full" variant="tertiary"> Top </Button> <Tooltip.Content showArrow placement="top"> <Tooltip.Arrow /> <p>Top placement</p> </Tooltip.Content> </Tooltip> <div /> <Tooltip delay={0}> <Button className="w-full" variant="tertiary"> Left </Button> <Tooltip.Content showArrow placement="left"> <Tooltip.Arrow /> <p>Left placement</p> </Tooltip.Content> </Tooltip> <div className="flex items-center justify-center"> <span className="text-sm text-muted">Hover buttons</span> </div> <Tooltip delay={0}> <Button className="w-full" variant="tertiary"> Right </Button> <Tooltip.Content showArrow placement="right"> <Tooltip.Arrow /> <p>Right placement</p> </Tooltip.Content> </Tooltip> <div /> <Tooltip delay={0}> <Button className="w-full" variant="tertiary"> Bottom </Button> <Tooltip.Content showArrow placement="bottom"> <Tooltip.Arrow /> <p>Bottom placement</p> </Tooltip.Content> </Tooltip> <div /> </div> ); } ``` ### Custom Triggers ```tsx import {CircleCheckFill, CircleQuestion} from "@gravity-ui/icons"; import {Avatar, Chip, Tooltip} from "@heroui/react"; export function TooltipCustomTrigger() { return ( <div className="flex items-center gap-6"> <Tooltip delay={0}> <Tooltip.Trigger aria-label="User avatar"> <Avatar size="sm"> <Avatar.Image alt="Jane Doe" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=4" /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> </Tooltip.Trigger> <Tooltip.Content showArrow> <Tooltip.Arrow /> <div className="flex flex-col gap-0 py-1"> <p className="font-semibold">Jane Doe</p> <p className="text-xs text-muted">jane@example.com</p> </div> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Tooltip.Trigger aria-label="Status chip"> <Chip color="success"> <CircleCheckFill width={12} /> <Chip.Label>Active</Chip.Label> </Chip> </Tooltip.Trigger> <Tooltip.Content className="flex items-center gap-1.5"> <span className="relative flex size-2"> <span className="absolute inline-flex h-full w-full animate-ping rounded-full bg-success opacity-75" /> <span className="relative inline-flex size-2 rounded-full bg-success" /> </span> <p>Jane is currently online</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Tooltip.Trigger aria-label="Info icon"> <div className="rounded-full bg-accent-soft p-2"> <CircleQuestion className="text-accent" /> </div> </Tooltip.Trigger> <Tooltip.Content showArrow> <Tooltip.Arrow /> <div className="max-w-xs px-1 py-1.5"> <p className="mb-1 font-semibold">Help Information</p> <p className="text-sm text-muted"> This is a helpful tooltip with more detailed information about this feature. </p> </div> </Tooltip.Content> </Tooltip> </div> ); } ``` ## Related Components * **Button**: Allows a user to perform an action * **Popover**: Displays content in context with a trigger ### Custom Render Function ```tsx "use client"; import {CircleInfo} from "@gravity-ui/icons"; import {Button, Tooltip} from "@heroui/react"; export function CustomRenderFunction() { return ( <div className="flex items-center gap-4"> <Tooltip delay={0}> <Button variant="secondary">Hover me</Button> <Tooltip.Content render={(props) => <div {...props} data-custom="foo" />}> <p>This is a tooltip</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Button isIconOnly variant="tertiary"> <CircleInfo /> </Button> <Tooltip.Content render={(props) => <div {...props} data-custom="foo" />}> <p>More information</p> </Tooltip.Content> </Tooltip> </div> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import { Tooltip, Button } from '@heroui/react'; function CustomTooltip() { return ( <Tooltip> <Tooltip.Trigger> <Button>Hover me</Button> </Tooltip.Trigger> <Tooltip.Content className="bg-accent text-accent-foreground"> <p>Custom styled tooltip</p> </Tooltip.Content> </Tooltip> ); } ``` ### Customizing the component classes To customize the Tooltip component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .tooltip { @apply rounded-xl shadow-lg; } .tooltip__trigger { @apply cursor-help; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Tooltip component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tooltip.css)): #### Base Classes * `.tooltip` - Base tooltip styles with animations * `.tooltip__trigger` - Trigger element styles ### Interactive States The component supports animation states: * **Entering**: `[data-entering]` - Applied during tooltip appearance * **Exiting**: `[data-exiting]` - Applied during tooltip disappearance * **Placement**: `[data-placement="*"]` - Applied based on tooltip position ## API Reference ### Tooltip Props | Prop | Type | Default | Description | | ------------ | -------------------- | --------- | -------------------------------------------- | | `children` | `React.ReactNode` | - | Trigger element and content | | `delay` | `number` | `700` | Delay in milliseconds before showing tooltip | | `closeDelay` | `number` | `0` | Delay in milliseconds before hiding tooltip | | `trigger` | `"hover" \| "focus"` | `"hover"` | How the tooltip is triggered | | `isDisabled` | `boolean` | `false` | Whether the tooltip is disabled | ### Tooltip.Content Props | Prop | Type | Default | Description | | ----------- | -------------------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Content to display in the tooltip | | `showArrow` | `boolean` | `false` | Whether to show the arrow indicator | | `offset` | `number` | `3` (7 with arrow) | Distance from the trigger element | | `placement` | `"top" \| "bottom" \| "left" \| "right"` (and variants) | `"top"` | Placement of the tooltip | | `className` | `string` | - | Additional CSS classes | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TooltipRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Tooltip.Trigger Props | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | --------------------------------- | | `children` | `React.ReactNode` | - | Element that triggers the tooltip | | `className` | `string` | - | Additional CSS classes | ### Tooltip.Arrow Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Custom arrow element | | `className` | `string` | - | Additional CSS classes | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, OverlayArrowRenderProps>` | - | Overrides the default DOM element with a custom render function. | </page> <page url="/docs/react/components/autocomplete"> # Autocomplete **Category**: react **URL**: https://v3.heroui.com/docs/react/components/autocomplete **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(pickers)/autocomplete.mdx > An autocomplete combines a select with filtering, allowing users to search and select from a list of options ## Import ```tsx import { Autocomplete, useFilter } from "@heroui/react"; ``` ### Usage ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, EmptyState, Label, ListBox, SearchField, Tag, TagGroup, useFilter, } from "@heroui/react"; import {useState} from "react"; export default function Default() { const {contains} = useFilter({sensitivity: "base"}); const [selectedKeys, setSelectedKeys] = useState<Key[]>([]); const items = [ {id: "florida", name: "Florida"}, {id: "delaware", name: "Delaware"}, {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "new-york", name: "New York"}, {id: "washington", name: "Washington"}, ]; const onRemoveTags = (keys: Set<Key>) => { setSelectedKeys((prev) => prev.filter((key) => !keys.has(key))); }; return ( <Autocomplete className="w-[256px]" placeholder="Select states" selectionMode="multiple" value={selectedKeys} onChange={(keys: Key | Key[] | null) => setSelectedKeys(keys as Key[])} > <Label>States to Visit</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}: any) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItemsKeys = state.selectedItems.map((item: any) => item.key); return ( <TagGroup size="sm" onRemove={onRemoveTags}> <TagGroup.List> {selectedItemsKeys.map((selectedItemKey: Key) => { const item = items.find((s) => s.id === selectedItemKey); if (!item) return null; return ( <Tag key={item.id} id={item.id}> {item.name} </Tag> ); })} </TagGroup.List> </TagGroup> ); }} </Autocomplete.Value> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### Anatomy Import the Autocomplete component and access all parts using dot notation. ```tsx import {Autocomplete, Label, Description, SearchField, ListBox} from "@heroui/react"; export default () => ( <Autocomplete> <Label /> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Description /> <Autocomplete.Popover> <Autocomplete.Filter> <SearchField> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input /> </SearchField.Group> </SearchField> <ListBox> <ListBox.Item> <Label /> <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); ``` ### With Description ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, Description, EmptyState, Label, ListBox, SearchField, useFilter, } from "@heroui/react"; import {useState} from "react"; export function WithDescription() { const [selectedKey, setSelectedKey] = useState<Key | null>(null); const {contains} = useFilter({sensitivity: "base"}); const items = [ {id: "florida", name: "Florida"}, {id: "delaware", name: "Delaware"}, {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "new-york", name: "New York"}, {id: "washington", name: "Washington"}, ]; return ( <Autocomplete className="w-[256px]" placeholder="Select one" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>State</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search states..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> <Description>Select your state of residence</Description> </Autocomplete> ); } ``` ### Multiple Select ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, EmptyState, Label, ListBox, SearchField, Tag, TagGroup, useFilter, } from "@heroui/react"; import {useState} from "react"; export function MultipleSelect() { const [selectedKeys, setSelectedKeys] = useState<Key[]>([]); const {contains} = useFilter({sensitivity: "base"}); const items = [ {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "florida", name: "Florida"}, {id: "new-york", name: "New York"}, {id: "illinois", name: "Illinois"}, {id: "pennsylvania", name: "Pennsylvania"}, ]; const onRemoveTags = (keys: Set<Key>) => { setSelectedKeys((prev) => prev.filter((key) => !keys.has(key))); }; return ( <Autocomplete className="w-[256px]" placeholder="Select states" selectionMode="multiple" value={selectedKeys} onChange={(keys) => setSelectedKeys(keys as Key[])} > <Label>States</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItemsKeys = state.selectedItems.map((item) => item.key); return ( <TagGroup size="sm" onRemove={onRemoveTags}> <TagGroup.List> {selectedItemsKeys.map((selectedItemKey) => { const item = items.find((s) => s.id === selectedItemKey); if (!item) return null; return ( <Tag key={item.id} id={item.id}> {item.name} </Tag> ); })} </TagGroup.List> </TagGroup> ); }} </Autocomplete.Value> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### With Sections ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, EmptyState, Header, Label, ListBox, SearchField, Separator, useFilter, } from "@heroui/react"; import {useState} from "react"; export function WithSections() { const [selectedKey, setSelectedKey] = useState<Key | null>(null); const {contains} = useFilter({sensitivity: "base"}); return ( <Autocomplete className="w-[256px]" placeholder="Select a country" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>Country</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search countries..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> <ListBox.Section> <Header>North America</Header> <ListBox.Item id="usa" textValue="United States"> United States <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="canada" textValue="Canada"> Canada <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="mexico" textValue="Mexico"> Mexico <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>Europe</Header> <ListBox.Item id="uk" textValue="United Kingdom"> United Kingdom <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="France"> France <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="germany" textValue="Germany"> Germany <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="spain" textValue="Spain"> Spain <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="italy" textValue="Italy"> Italy <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>Asia</Header> <ListBox.Item id="japan" textValue="Japan"> Japan <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="china" textValue="China"> China <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="india" textValue="India"> India <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="south-korea" textValue="South Korea"> South Korea <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### With Disabled Options ```tsx "use client"; import type {Key} from "@heroui/react"; import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react"; import {useState} from "react"; export function WithDisabledOptions() { const [selectedKey, setSelectedKey] = useState<Key | null>(null); const {contains} = useFilter({sensitivity: "base"}); return ( <Autocomplete className="w-[256px]" disabledKeys={["cat", "kangaroo"]} placeholder="Select an animal" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>Animal</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search animals..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="bird" textValue="Bird"> Bird <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="elephant" textValue="Elephant"> Elephant <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="tiger" textValue="Tiger"> Tiger <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### Allows Empty Collection The `allowsEmptyCollection` prop enables the autocomplete to function even when there are no items in the collection. This is useful for scenarios where the list might be empty initially or when all items are filtered out. ```tsx "use client"; import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react"; export function AllowsEmptyCollection() { const {contains} = useFilter({sensitivity: "base"}); return ( <Autocomplete allowsEmptyCollection className="w-[256px]" placeholder="Select one" selectionMode="single" > <Label>State</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search states..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>} /> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### Custom Indicator ```tsx "use client"; import type {Key} from "@heroui/react"; import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react"; import {Icon} from "@iconify/react"; import {useState} from "react"; export function CustomIndicator() { const [selectedKey, setSelectedKey] = useState<Key | null>(null); const {contains} = useFilter({sensitivity: "base"}); const items = [ {id: "florida", name: "Florida"}, {id: "delaware", name: "Delaware"}, {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "new-york", name: "New York"}, {id: "washington", name: "Washington"}, ]; return ( <Autocomplete className="w-[256px]" placeholder="Select one" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>State</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator className="size-3"> <Icon icon="gravity-ui:chevrons-expand-vertical" /> </Autocomplete.Indicator> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search states..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### Required ```tsx "use client"; import { Autocomplete, Button, EmptyState, FieldError, Form, Label, ListBox, SearchField, useFilter, } from "@heroui/react"; export function Required() { const onSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record<string, string> = {}; // Convert FormData to plain object formData.forEach((value, key) => { data[key] = value.toString(); }); alert("Form submitted successfully!"); }; const {contains} = useFilter({sensitivity: "base"}); const states = [ {id: "florida", name: "Florida"}, {id: "delaware", name: "Delaware"}, {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "new-york", name: "New York"}, {id: "washington", name: "Washington"}, ]; const countries = [ {id: "usa", name: "United States"}, {id: "canada", name: "Canada"}, {id: "mexico", name: "Mexico"}, {id: "uk", name: "United Kingdom"}, {id: "france", name: "France"}, {id: "germany", name: "Germany"}, ]; return ( <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}> <Autocomplete isRequired className="w-full" name="state" placeholder="Select one" selectionMode="single" > <Label>State</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search states..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {states.map((state) => ( <ListBox.Item key={state.id} id={state.id} textValue={state.name}> {state.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> <FieldError /> </Autocomplete> <Autocomplete isRequired className="w-full" name="country" placeholder="Select a country" selectionMode="single" > <Label>Country</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search countries..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {countries.map((country) => ( <ListBox.Item key={country.id} id={country.id} textValue={country.name}> {country.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> <FieldError /> </Autocomplete> <Button type="submit">Submit</Button> </Form> ); } ``` ### Full Width ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, EmptyState, Label, ListBox, SearchField, Surface, useFilter, } from "@heroui/react"; import {useState} from "react"; export function FullWidth() { const [selectedKey, setSelectedKey] = useState<Key | null>(null); const {contains} = useFilter({sensitivity: "base"}); const items = [ {id: "florida", name: "Florida"}, {id: "delaware", name: "Delaware"}, {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "new-york", name: "New York"}, {id: "washington", name: "Washington"}, ]; return ( <Surface className="w-[380px] space-y-4 rounded-3xl p-6"> <Autocomplete fullWidth placeholder="Select one" selectionMode="single" value={selectedKey} variant="secondary" onChange={setSelectedKey} > <Label>State</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search states..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> </Surface> ); } ``` ### Variants The Autocomplete component supports two visual variants: * **`primary`** (default) - Standard styling with shadow, suitable for most use cases * **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, EmptyState, Label, ListBox, SearchField, Tag, TagGroup, useFilter, } from "@heroui/react"; import {useState} from "react"; export function Variants() { const [selectedKey1, setSelectedKey1] = useState<Key | null>(null); const [selectedKey2, setSelectedKey2] = useState<Key | null>(null); const [selectedKeys1, setSelectedKeys1] = useState<Key[]>([]); const [selectedKeys2, setSelectedKeys2] = useState<Key[]>([]); const {contains} = useFilter({sensitivity: "base"}); const items = [ {id: "option1", name: "Option 1"}, {id: "option2", name: "Option 2"}, {id: "option3", name: "Option 3"}, {id: "option4", name: "Option 4"}, ]; const onRemoveTags1 = (keys: Set<Key>) => { setSelectedKeys1((prev) => prev.filter((key) => !keys.has(key))); }; const onRemoveTags2 = (keys: Set<Key>) => { setSelectedKeys2((prev) => prev.filter((key) => !keys.has(key))); }; return ( <div className="flex flex-col gap-8"> <div className="flex flex-col gap-4"> <h3 className="text-lg font-semibold">Single Select Variants</h3> <div className="flex flex-col gap-4"> <Autocomplete className="w-[256px]" placeholder="Select one" selectionMode="single" value={selectedKey1} variant="primary" onChange={setSelectedKey1} > <Label>Primary variant</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> <Autocomplete className="w-[256px]" placeholder="Select one" selectionMode="single" value={selectedKey2} variant="secondary" onChange={setSelectedKey2} > <Label>Secondary variant</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> </div> </div> <div className="flex flex-col gap-4"> <h3 className="text-lg font-semibold">Multiple Select Variants</h3> <div className="flex flex-col gap-4"> <Autocomplete className="w-[256px]" placeholder="Select multiple" selectionMode="multiple" value={selectedKeys1} variant="primary" onChange={(keys) => setSelectedKeys1(keys as Key[])} > <Label>Primary variant</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItemsKeys = state.selectedItems.map((item) => item.key); return ( <TagGroup size="sm" onRemove={onRemoveTags1}> <TagGroup.List> {selectedItemsKeys.map((selectedItemKey) => { const item = items.find((s) => s.id === selectedItemKey); if (!item) return null; return ( <Tag key={item.id} id={item.id}> {item.name} </Tag> ); })} </TagGroup.List> </TagGroup> ); }} </Autocomplete.Value> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> <Autocomplete className="w-[256px]" placeholder="Select multiple" selectionMode="multiple" value={selectedKeys2} variant="secondary" onChange={(keys) => setSelectedKeys2(keys as Key[])} > <Label>Secondary variant</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItemsKeys = state.selectedItems.map((item) => item.key); return ( <TagGroup size="sm" variant="surface" onRemove={onRemoveTags2}> <TagGroup.List> {selectedItemsKeys.map((selectedItemKey) => { const item = items.find((s) => s.id === selectedItemKey); if (!item) return null; return ( <Tag key={item.id} id={item.id}> {item.name} </Tag> ); })} </TagGroup.List> </TagGroup> ); }} </Autocomplete.Value> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> </div> </div> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, EmptyState, Label, ListBox, SearchField, Surface, useFilter, } from "@heroui/react"; import {useState} from "react"; export function FullWidth() { const [selectedKey, setSelectedKey] = useState<Key | null>(null); const {contains} = useFilter({sensitivity: "base"}); const items = [ {id: "florida", name: "Florida"}, {id: "delaware", name: "Delaware"}, {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "new-york", name: "New York"}, {id: "washington", name: "Washington"}, ]; return ( <Surface className="w-[380px] space-y-4 rounded-3xl p-6"> <Autocomplete fullWidth placeholder="Select one" selectionMode="single" value={selectedKey} variant="secondary" onChange={setSelectedKey} > <Label>State</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search states..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> </Surface> ); } ``` ### Custom Value You can customize the displayed value using render props: ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, Avatar, AvatarFallback, AvatarImage, Description, EmptyState, Label, ListBox, SearchField, useFilter, } from "@heroui/react"; import {useState} from "react"; export function UserSelection() { const users = [ { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", email: "bob@heroui.com", fallback: "B", id: "1", name: "Bob", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", email: "fred@heroui.com", fallback: "F", id: "2", name: "Fred", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", email: "martha@heroui.com", fallback: "M", id: "3", name: "Martha", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", email: "john@heroui.com", fallback: "J", id: "4", name: "John", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", email: "jane@heroui.com", fallback: "J", id: "5", name: "Jane", }, ]; const [selectedKey, setSelectedKey] = useState<Key | null>(null); const {contains} = useFilter({sensitivity: "base"}); return ( <Autocomplete className="w-[256px]" placeholder="Select a user" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>User</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItems = state.selectedItems; if (selectedItems.length > 1) { return `${selectedItems.length} users selected`; } const selectedItem = users.find((user) => user.id === selectedItems[0]?.key); if (!selectedItem) { return defaultChildren; } return ( <div className="flex items-center gap-2"> <Avatar className="size-4" size="sm"> <AvatarImage src={selectedItem.avatarUrl} /> <AvatarFallback>{selectedItem.fallback}</AvatarFallback> </Avatar> <span>{selectedItem.name}</span> </div> ); }} </Autocomplete.Value> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search users..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {users.map((user) => ( <ListBox.Item key={user.id} id={user.id} textValue={user.name}> <Avatar size="sm"> <AvatarImage src={user.avatarUrl} /> <AvatarFallback>{user.fallback}</AvatarFallback> </Avatar> <div className="flex flex-col"> <Label>{user.name}</Label> <Description>{user.email}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### Controlled ```tsx "use client"; import type {Key} from "@heroui/react"; import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const states = [ {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "florida", name: "Florida"}, {id: "new-york", name: "New York"}, {id: "illinois", name: "Illinois"}, {id: "pennsylvania", name: "Pennsylvania"}, ]; const [state, setState] = useState<Key | null>("california"); const {contains} = useFilter({sensitivity: "base"}); const selectedState = states.find((s) => s.id === state); return ( <div className="space-y-2"> <Autocomplete className="w-[256px]" placeholder="Select a state" selectionMode="single" value={state} onChange={setState} > <Label>State (controlled)</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search states..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {states.map((state) => ( <ListBox.Item key={state.id} id={state.id} textValue={state.name}> {state.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> <p className="text-sm text-muted">Selected: {selectedState?.name || "None"}</p> </div> ); } ``` ### Controlled Multiple ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, EmptyState, Label, ListBox, SearchField, Tag, TagGroup, useFilter, } from "@heroui/react"; import {useState} from "react"; export function MultipleSelect() { const [selectedKeys, setSelectedKeys] = useState<Key[]>([]); const {contains} = useFilter({sensitivity: "base"}); const items = [ {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "florida", name: "Florida"}, {id: "new-york", name: "New York"}, {id: "illinois", name: "Illinois"}, {id: "pennsylvania", name: "Pennsylvania"}, ]; const onRemoveTags = (keys: Set<Key>) => { setSelectedKeys((prev) => prev.filter((key) => !keys.has(key))); }; return ( <Autocomplete className="w-[256px]" placeholder="Select states" selectionMode="multiple" value={selectedKeys} onChange={(keys) => setSelectedKeys(keys as Key[])} > <Label>States</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItemsKeys = state.selectedItems.map((item) => item.key); return ( <TagGroup size="sm" onRemove={onRemoveTags}> <TagGroup.List> {selectedItemsKeys.map((selectedItemKey) => { const item = items.find((s) => s.id === selectedItemKey); if (!item) return null; return ( <Tag key={item.id} id={item.id}> {item.name} </Tag> ); })} </TagGroup.List> </TagGroup> ); }} </Autocomplete.Value> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### Controlled Open State ```tsx "use client"; import { Autocomplete, Button, EmptyState, Label, ListBox, SearchField, useFilter, } from "@heroui/react"; import {useState} from "react"; export function ControlledOpenState() { const [isOpen, setIsOpen] = useState(false); const {contains} = useFilter({sensitivity: "base"}); const items = [ {id: "florida", name: "Florida"}, {id: "delaware", name: "Delaware"}, {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "new-york", name: "New York"}, {id: "washington", name: "Washington"}, ]; return ( <div className="space-y-4"> <Autocomplete className="w-[256px]" isOpen={isOpen} placeholder="Select one" selectionMode="single" onOpenChange={setIsOpen} > <Label>State</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search states..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> <Button onPress={() => setIsOpen(!isOpen)}>{isOpen ? "Close" : "Open"} Autocomplete</Button> <p className="text-sm text-muted">Autocomplete is {isOpen ? "open" : "closed"}</p> </div> ); } ``` ### Asynchronous Filtering ```tsx "use client"; import {Autocomplete, EmptyState, Label, ListBox, SearchField, Spinner} from "@heroui/react"; import {useAsyncList} from "@react-stately/data"; import {cn} from "tailwind-variants"; interface Character { name: string; } export function AsynchronousFiltering() { const list = useAsyncList<Character>({ async load({filterText, signal}) { const res = await fetch(`https://swapi.py4e.com/api/people/?search=${filterText}`, { signal, }); const json = await res.json(); return { items: json.results, }; }, }); return ( <Autocomplete className="w-[256px]" placeholder="Search..." selectionMode="single"> <Label>Search a Star Wars characters</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter inputValue={list.filterText} onInputChange={list.setFilterText}> <SearchField autoFocus className="sticky top-0 z-10" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search characters..." /> <Spinner size="sm" className={cn("absolute top-1/2 right-2 -translate-y-1/2", { "pointer-events-none opacity-0": !list.isLoading, })} /> <SearchField.ClearButton className={cn({"pointer-events-none opacity-0": !!list.isLoading})} /> </SearchField.Group> </SearchField> <ListBox className="max-h-[420px] overflow-y-auto" items={list.items} renderEmptyState={() => <EmptyState>No results found</EmptyState>} > {(item: Character) => ( <ListBox.Item id={item.name} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> )} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### Disabled ```tsx "use client"; import {Autocomplete, EmptyState, Label, ListBox, SearchField, useFilter} from "@heroui/react"; export function Disabled() { const {contains} = useFilter({sensitivity: "base"}); const items = [ {id: "florida", name: "Florida"}, {id: "delaware", name: "Delaware"}, {id: "california", name: "California"}, {id: "texas", name: "Texas"}, {id: "new-york", name: "New York"}, {id: "washington", name: "Washington"}, ]; const countries = [ {id: "argentina", name: "Argentina"}, {id: "venezuela", name: "Venezuela"}, {id: "japan", name: "Japan"}, {id: "france", name: "France"}, {id: "italy", name: "Italy"}, {id: "spain", name: "Spain"}, ]; return ( <div className="flex flex-col gap-4"> <Autocomplete isDisabled className="w-[256px]" defaultValue="california" placeholder="Select one" selectionMode="single" > <Label>State</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search states..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {items.map((item) => ( <ListBox.Item key={item.id} id={item.id} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> <Autocomplete isDisabled className="w-[256px]" defaultValue={["argentina", "japan", "france"]} placeholder="Select countries" selectionMode="multiple" > <Label>Countries to Visit</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search countries..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {countries.map((country) => ( <ListBox.Item key={country.id} id={country.id} textValue={country.name}> {country.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> </div> ); } ``` ### Advanced Examples #### User Selection ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, Avatar, AvatarFallback, AvatarImage, Description, EmptyState, Label, ListBox, SearchField, useFilter, } from "@heroui/react"; import {useState} from "react"; export function UserSelection() { const users = [ { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", email: "bob@heroui.com", fallback: "B", id: "1", name: "Bob", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", email: "fred@heroui.com", fallback: "F", id: "2", name: "Fred", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", email: "martha@heroui.com", fallback: "M", id: "3", name: "Martha", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", email: "john@heroui.com", fallback: "J", id: "4", name: "John", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", email: "jane@heroui.com", fallback: "J", id: "5", name: "Jane", }, ]; const [selectedKey, setSelectedKey] = useState<Key | null>(null); const {contains} = useFilter({sensitivity: "base"}); return ( <Autocomplete className="w-[256px]" placeholder="Select a user" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>User</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItems = state.selectedItems; if (selectedItems.length > 1) { return `${selectedItems.length} users selected`; } const selectedItem = users.find((user) => user.id === selectedItems[0]?.key); if (!selectedItem) { return defaultChildren; } return ( <div className="flex items-center gap-2"> <Avatar className="size-4" size="sm"> <AvatarImage src={selectedItem.avatarUrl} /> <AvatarFallback>{selectedItem.fallback}</AvatarFallback> </Avatar> <span>{selectedItem.name}</span> </div> ); }} </Autocomplete.Value> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search users..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {users.map((user) => ( <ListBox.Item key={user.id} id={user.id} textValue={user.name}> <Avatar size="sm"> <AvatarImage src={user.avatarUrl} /> <AvatarFallback>{user.fallback}</AvatarFallback> </Avatar> <div className="flex flex-col"> <Label>{user.name}</Label> <Description>{user.email}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` #### User Selection Multiple ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, Avatar, AvatarFallback, AvatarImage, Description, EmptyState, Label, ListBox, SearchField, Tag, TagGroup, useFilter, } from "@heroui/react"; import {useState} from "react"; export function UserSelectionMultiple() { const users = [ { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", email: "bob@heroui.com", fallback: "B", id: "1", name: "Bob", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", email: "fred@heroui.com", fallback: "F", id: "2", name: "Fred", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", email: "martha@heroui.com", fallback: "M", id: "3", name: "Martha", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", email: "john@heroui.com", fallback: "J", id: "4", name: "John", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", email: "jane@heroui.com", fallback: "J", id: "5", name: "Jane", }, ]; const [selectedKeys, setSelectedKeys] = useState<Key[]>([]); const {contains} = useFilter({sensitivity: "base"}); const onRemoveTags = (keys: Set<Key>) => { setSelectedKeys((prev) => prev.filter((key) => !keys.has(key))); }; return ( <Autocomplete className="w-[256px]" defaultValue={["1", "2"]} placeholder="Select your teammates" selectionMode="multiple" value={selectedKeys} onChange={(keys) => setSelectedKeys(keys as Key[])} > <Label>Users</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItemsKeys = state.selectedItems.map((item) => item.key); return ( <TagGroup size="sm" onRemove={onRemoveTags}> <TagGroup.List> {selectedItemsKeys.map((selectedItemKey) => { const selectedItem = users.find((user) => user.id === selectedItemKey); if (!selectedItem) { return null; } return ( <Tag key={selectedItem.id} id={selectedItem.id}> <Avatar className="size-4" size="sm"> <AvatarImage src={selectedItem.avatarUrl} /> <AvatarFallback>{selectedItem.fallback}</AvatarFallback> </Avatar> <span>{selectedItem.name}</span> </Tag> ); })} </TagGroup.List> </TagGroup> ); }} </Autocomplete.Value> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search users..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {users.map((user) => ( <ListBox.Item key={user.id} id={user.id} textValue={user.name}> <Avatar size="sm"> <AvatarImage src={user.avatarUrl} /> <AvatarFallback>{user.fallback}</AvatarFallback> </Avatar> <div className="flex flex-col"> <Label>{user.name}</Label> <Description>{user.email}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` #### Location Search ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, Description, EmptyState, Label, ListBox, SearchField, useFilter, } from "@heroui/react"; import {useState} from "react"; interface City { name: string; country: string; } export function LocationSearch() { const allCities: City[] = [ {country: "USA", name: "New York"}, {country: "USA", name: "Los Angeles"}, {country: "USA", name: "Chicago"}, {country: "UK", name: "London"}, {country: "France", name: "Paris"}, {country: "Japan", name: "Tokyo"}, {country: "Australia", name: "Sydney"}, {country: "Canada", name: "Toronto"}, {country: "Germany", name: "Berlin"}, {country: "Spain", name: "Madrid"}, ]; const [selectedKey, setSelectedKey] = useState<Key | null>(null); const [isLoading, setIsLoading] = useState(false); const {contains} = useFilter({sensitivity: "base"}); // Simulate async filtering const customFilter = (text: string, inputValue: string) => { if (!inputValue) return true; setIsLoading(true); setTimeout(() => setIsLoading(false), 300); return contains(text, inputValue); }; return ( <Autocomplete className="w-[256px]" placeholder="Search for a city" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>City</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={customFilter}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search cities..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => ( <EmptyState>{isLoading ? "Searching..." : "No cities found"}</EmptyState> )} > {allCities.map((city) => ( <ListBox.Item key={city.name} id={city.name} textValue={city.name}> <div className="flex flex-col"> <Label>{city.name}</Label> <Description>{city.country}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` #### Tag Group Selection ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, EmptyState, Label, ListBox, SearchField, Tag, TagGroup, useFilter, } from "@heroui/react"; import {useState} from "react"; export function TagGroupSelection() { const tags = [ {id: "react", name: "React"}, {id: "typescript", name: "TypeScript"}, {id: "javascript", name: "JavaScript"}, {id: "nodejs", name: "Node.js"}, {id: "python", name: "Python"}, {id: "vue", name: "Vue"}, {id: "angular", name: "Angular"}, {id: "nextjs", name: "Next.js"}, ]; const [selectedKeys, setSelectedKeys] = useState<Key[]>([]); const {contains} = useFilter({sensitivity: "base"}); const onRemoveTags = (keys: Set<Key>) => { setSelectedKeys((prev) => prev.filter((key) => !keys.has(key))); }; return ( <Autocomplete className="w-[256px]" placeholder="Select tags" selectionMode="multiple" value={selectedKeys} onChange={(keys) => setSelectedKeys(keys as Key[])} > <Label>Tags</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItemsKeys = state.selectedItems.map((item) => item.key); return ( <TagGroup size="sm" onRemove={onRemoveTags}> <TagGroup.List> {selectedItemsKeys.map((selectedItemKey) => { const tag = tags.find((t) => t.id === selectedItemKey); if (!tag) return null; return ( <Tag key={tag.id} id={tag.id}> {tag.name} </Tag> ); })} </TagGroup.List> </TagGroup> ); }} </Autocomplete.Value> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search tags..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No tags found</EmptyState>}> {tags.map((tag) => ( <ListBox.Item key={tag.id} id={tag.id} textValue={tag.name}> {tag.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` #### Email Recipients ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, Description, EmptyState, Label, ListBox, SearchField, Tag, TagGroup, useFilter, } from "@heroui/react"; import {useState} from "react"; export function EmailRecipients() { const emails = [ {email: "alice@example.com", id: "alice@example.com", name: "Alice Johnson"}, {email: "bob@example.com", id: "bob@example.com", name: "Bob Smith"}, {email: "charlie@example.com", id: "charlie@example.com", name: "Charlie Brown"}, {email: "diana@example.com", id: "diana@example.com", name: "Diana Prince"}, {email: "eve@example.com", id: "eve@example.com", name: "Eve Wilson"}, ]; const [selectedKeys, setSelectedKeys] = useState<Key[]>([]); const {contains} = useFilter({sensitivity: "base"}); const onRemoveTags = (keys: Set<Key>) => { setSelectedKeys((prev) => prev.filter((key) => !keys.has(key))); }; return ( <Autocomplete className="w-[256px]" placeholder="Add recipients" selectionMode="multiple" value={selectedKeys} onChange={(keys) => setSelectedKeys(keys as Key[])} > <Label>To</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItemsKeys = state.selectedItems.map((item) => item.key); return ( <TagGroup size="sm" onRemove={onRemoveTags}> <TagGroup.List> {selectedItemsKeys.map((selectedItemKey) => { const email = emails.find((e) => e.id === selectedItemKey); if (!email) return null; return ( <Tag key={email.id} id={email.id}> {email.email} </Tag> ); })} </TagGroup.List> </TagGroup> ); }} </Autocomplete.Value> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search emails..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No recipients found</EmptyState>}> {emails.map((email) => ( <ListBox.Item key={email.id} id={email.id} textValue={email.email}> <div className="flex flex-col"> <Label>{email.name}</Label> <Description>{email.email}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ## Related Components * **Listbox**: Scrollable list of selectable items * **Popover**: Displays content in context with a trigger * **Input**: Single-line text input built on React Aria ## Styling ### Passing Tailwind CSS classes ```tsx import {Autocomplete, SearchField, ListBox} from "@heroui/react"; function CustomAutocomplete() { return ( <Autocomplete className="w-full"> <Label>State</Label> <Autocomplete.Trigger className="rounded-lg border bg-surface p-2"> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter> <SearchField> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search..." /> </SearchField.Group> </SearchField> <ListBox> <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary"> Item 1 </ListBox.Item> </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### Customizing the component classes To customize the Autocomplete component classes, you can use the `@layer components` directive. <br /> [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .autocomplete { @apply flex flex-col gap-1; } .autocomplete__trigger { @apply rounded-lg border border-border bg-surface p-2; } .autocomplete__value { @apply text-current; } .autocomplete__clear-button { @apply text-muted hover:text-foreground; } .autocomplete__indicator { @apply text-muted; } .autocomplete__popover { @apply rounded-lg border border-border bg-surface p-2; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Autocomplete component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/autocomplete.css)): #### Base Classes * `.autocomplete` - Base autocomplete container * `.autocomplete__trigger` - The button that triggers the autocomplete * `.autocomplete__value` - The displayed value or placeholder * `.autocomplete__clear-button` - The clear button that removes the selected value * `.autocomplete__indicator` - The dropdown indicator icon * `.autocomplete__popover` - The popover container * `.autocomplete__filter` - The filter wrapper #### Variant Classes * `.autocomplete--primary` - Primary variant with shadow (default) * `.autocomplete--secondary` - Secondary variant without shadow, suitable for use in surfaces #### State Classes * `.autocomplete[data-invalid="true"]` - Invalid state * `.autocomplete__trigger[data-focus-visible="true"]` - Focused trigger state * `.autocomplete__trigger[data-disabled="true"]` - Disabled trigger state * `.autocomplete__value[data-placeholder="true"]` - Placeholder state * `.autocomplete__clear-button[data-empty="true"]` - Clear button hidden when no selection * `.autocomplete__indicator[data-open="true"]` - Open indicator state ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Hover**: `:hover` or `[data-hovered="true"]` on trigger * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger * **Disabled**: `:disabled` or `[data-disabled="true"]` on autocomplete * **Open**: `[data-open="true"]` on indicator ## API Reference ### Autocomplete Props | Prop | Type | Default | Description | | ----------------------- | --------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `placeholder` | `string` | `'Select an item'` | Temporary text that occupies the autocomplete when it is empty | | `selectionMode` | `"single" \| "multiple"` | `"single"` | Whether single or multiple selection is enabled | | `allowsEmptyCollection` | `boolean` | `false` | Whether the autocomplete allows an empty collection. When true, the autocomplete can function even with no items. | | `isOpen` | `boolean` | - | Sets the open state of the popover (controlled) | | `defaultOpen` | `boolean` | - | Sets the default open state of the popover (uncontrolled) | | `onOpenChange` | `(isOpen: boolean) => void` | - | Handler called when the open state changes | | `disabledKeys` | `Iterable<Key>` | - | Keys of disabled items | | `isDisabled` | `boolean` | - | Whether the autocomplete is disabled | | `value` | `Key \| Key[] \| null` | - | Current value (controlled) | | `defaultValue` | `Key \| Key[] \| null` | - | Default value (uncontrolled) | | `onChange` | `(value: Key \| Key[] \| null) => void` | - | Handler called when the value changes | | `isRequired` | `boolean` | - | Whether user input is required | | `isInvalid` | `boolean` | - | Whether the autocomplete value is invalid | | `name` | `string` | - | The name of the input, used when submitting an HTML form | | `fullWidth` | `boolean` | `false` | Whether the autocomplete should take full width of its container | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Autocomplete content or render function | ### Autocomplete.Trigger Props | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | ---------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Trigger content or render function | ### Autocomplete.Value Props | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | -------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Value content or render function | ### Autocomplete.Indicator Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom indicator content | ### Autocomplete.ClearButton Props | Prop | Type | Default | Description | | ----------- | ------------------------------ | ------- | ------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `onClick` | `(e: MouseEvent) => void` | - | Handler called when button is clicked | | `ref` | `RefObject<HTMLButtonElement>` | - | Ref to the clear button element | ### Autocomplete.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 | ### Autocomplete.Filter Props | Prop | Type | Default | Description | | --------------- | ------------------------------------------ | ------- | ---------------------------------------- | | `filter` | `(text: string, input: string) => boolean` | - | Custom filter function | | `inputValue` | `string` | - | Controlled input value | | `onInputChange` | `(value: string) => void` | - | Handler called when input value changes | | `children` | `ReactNode` | - | Filter content (SearchField and ListBox) | ### useFilter Hook The `useFilter` hook from React Aria provides filtering functions for autocomplete functionality. ```tsx import {useFilter} from "@heroui/react"; const {contains} = useFilter({sensitivity: "base"}); <Autocomplete.Filter filter={contains}> <SearchField>...</SearchField> <ListBox>...</ListBox> </Autocomplete.Filter> ``` **Options:** | Option | Type | Default | Description | | ------------- | ------------------------------------------- | -------- | ------------------------------- | | `sensitivity` | `"base" \| "accent" \| "case" \| "variant"` | `"base"` | Locale sensitivity for matching | **Returns:** | Function | Type | Description | | ------------ | ------------------------------------------------ | ------------------------------------------------------ | | `contains` | `(string: string, substring: string) => boolean` | Returns whether a string contains a given substring | | `startsWith` | `(string: string, substring: string) => boolean` | Returns whether a string starts with a given substring | | `endsWith` | `(string: string, substring: string) => boolean` | Returns whether a string ends with a given substring | ### RenderProps When using render functions with Autocomplete.Value, these values are provided: | Prop | Type | Description | | ----------------- | ------------- | ---------------------------------- | | `defaultChildren` | `ReactNode` | The default rendered value | | `isPlaceholder` | `boolean` | Whether the value is a placeholder | | `state` | `SelectState` | The state of the autocomplete | | `selectedItems` | `Node[]` | The currently selected items | ## Accessibility The Autocomplete component implements the ARIA select pattern with filtering and provides: * Full keyboard navigation support * Screen reader announcements for selection changes * Proper focus management * Support for disabled states * Search functionality with filtering * HTML form integration For more information, see the [React Aria Select documentation](https://react-spectrum.adobe.com/react-aria/Select.html). </page> <page url="/docs/react/components/combo-box"> # ComboBox **Category**: react **URL**: https://v3.heroui.com/docs/react/components/combo-box **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(pickers)/combo-box.mdx > A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query ## Import ```tsx import { ComboBox } from '@heroui/react'; ``` ### Usage ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function Default() { return ( <ComboBox className="w-[256px]"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Anatomy Import the ComboBox component and access all parts using dot notation. ```tsx import { ComboBox, Input, Label, Description, Header, ListBox, Separator } from '@heroui/react'; export default () => ( <ComboBox> <Label /> <ComboBox.InputGroup> <Input /> <ComboBox.Trigger /> </ComboBox.InputGroup> <Description /> <ComboBox.Popover> <ListBox> <ListBox.Item> <Label /> <Description /> <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Section> <Header /> <ListBox.Item> <Label /> </ListBox.Item> </ListBox.Section> </ListBox> </ComboBox.Popover> </ComboBox> ) ``` ### With Description ```tsx "use client"; import {ComboBox, Description, Input, Label, ListBox} from "@heroui/react"; export function WithDescription() { return ( <ComboBox className="w-[256px]"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>Search and select your favorite animal</Description> </ComboBox> ); } ``` ### With Sections ```tsx "use client"; import {ComboBox, Header, Input, Label, ListBox, Separator} from "@heroui/react"; export function WithSections() { return ( <ComboBox className="w-[256px]"> <Label>Country</Label> <ComboBox.InputGroup> <Input placeholder="Search countries..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Section> <Header>North America</Header> <ListBox.Item id="usa" textValue="United States"> United States <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="canada" textValue="Canada"> Canada <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="mexico" textValue="Mexico"> Mexico <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>Europe</Header> <ListBox.Item id="uk" textValue="United Kingdom"> United Kingdom <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="France"> France <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="germany" textValue="Germany"> Germany <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="spain" textValue="Spain"> Spain <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="italy" textValue="Italy"> Italy <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>Asia</Header> <ListBox.Item id="japan" textValue="Japan"> Japan <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="china" textValue="China"> China <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="india" textValue="India"> India <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="south-korea" textValue="South Korea"> South Korea <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### With Disabled Options ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function WithDisabledOptions() { return ( <ComboBox className="w-[256px]" disabledKeys={["cat", "kangaroo"]}> <Label>Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="bird" textValue="Bird"> Bird <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="elephant" textValue="Elephant"> Elephant <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="tiger" textValue="Tiger"> Tiger <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Custom Indicator ```tsx "use client"; import {ChevronsExpandVertical} from "@gravity-ui/icons"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function CustomIndicator() { return ( <ComboBox className="w-[256px]"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger className="size-3"> <ChevronsExpandVertical /> </ComboBox.Trigger> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Required ```tsx "use client"; import {Button, ComboBox, FieldError, Form, Input, Label, ListBox} from "@heroui/react"; export function Required() { const onSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record<string, string> = {}; formData.forEach((value, key) => { data[key] = value.toString(); }); alert("Form submitted successfully!"); }; return ( <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}> <ComboBox isRequired className="w-full" name="animal"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <FieldError /> </ComboBox> <Button type="submit">Submit</Button> </Form> ); } ``` ### Custom Value ```tsx "use client"; import { Avatar, AvatarFallback, AvatarImage, ComboBox, Description, Input, Label, ListBox, } from "@heroui/react"; export function CustomValue() { const users = [ { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", email: "bob@heroui.com", fallback: "B", id: "1", name: "Bob", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", email: "fred@heroui.com", fallback: "F", id: "2", name: "Fred", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", email: "martha@heroui.com", fallback: "M", id: "3", name: "Martha", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", email: "john@heroui.com", fallback: "J", id: "4", name: "John", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", email: "jane@heroui.com", fallback: "J", id: "5", name: "Jane", }, ]; return ( <ComboBox className="w-[256px]"> <Label>User</Label> <ComboBox.InputGroup> <Input placeholder="Search users..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> {users.map((user) => ( <ListBox.Item key={user.id} id={user.id} textValue={user.name}> <Avatar size="sm"> <AvatarImage src={user.avatarUrl} /> <AvatarFallback>{user.fallback}</AvatarFallback> </Avatar> <div className="flex flex-col"> <Label>{user.name}</Label> <Description>{user.email}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Controlled ```tsx "use client"; import type {Key} from "@heroui/react"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const animals = [ { id: "cat", name: "Cat", }, { id: "dog", name: "Dog", }, { id: "bird", name: "Bird", }, { id: "fish", name: "Fish", }, { id: "hamster", name: "Hamster", }, ]; const [selectedKey, setSelectedKey] = useState<Key | null>("cat"); const selectedAnimal = animals.find((a) => a.id === selectedKey); return ( <div className="space-y-2"> <ComboBox className="w-[256px]" selectedKey={selectedKey} onSelectionChange={(key) => setSelectedKey(key)} > <Label>Animal (controlled)</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> {animals.map((animal) => ( <ListBox.Item key={animal.id} id={animal.id} textValue={animal.name}> {animal.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </ComboBox.Popover> </ComboBox> <p className="text-sm text-muted">Selected: {selectedAnimal?.name || "None"}</p> </div> ); } ``` ### Controlled Input Value ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; import {useState} from "react"; export function ControlledInputValue() { const [inputValue, setInputValue] = useState(""); return ( <div className="space-y-2"> <ComboBox className="w-[256px]" inputValue={inputValue} onInputChange={setInputValue}> <Label>Search (controlled input)</Label> <ComboBox.InputGroup> <Input placeholder="Type to search..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> <p className="text-sm text-muted">Input value: {inputValue || "(empty)"}</p> </div> ); } ``` ### Asynchronous Loading ```tsx "use client"; import { Collection, ComboBox, EmptyState, Input, Label, ListBox, ListBoxLoadMoreItem, Spinner, } from "@heroui/react"; import {useAsyncList} from "@react-stately/data"; interface Character { name: string; } export function AsynchronousLoading() { const list = useAsyncList<Character>({ async load({cursor, filterText, signal}) { if (cursor) { cursor = cursor.replace(/^http:\/\//i, "https://"); } const res = await fetch(cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`, { signal, }); const json = await res.json(); return { cursor: json.next, items: json.results, }; }, }); return ( <ComboBox allowsEmptyCollection className="w-[256px]" inputValue={list.filterText} onInputChange={list.setFilterText} > <Label>Pick a Character</Label> <ComboBox.InputGroup> <Input placeholder="Star Wars characters..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox renderEmptyState={() => <EmptyState />}> <Collection items={list.items}> {(item) => ( <ListBox.Item id={item.name} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> )} </Collection> <ListBoxLoadMoreItem isLoading={list.loadingState === "loadingMore"} onLoadMore={list.loadMore} > <div className="flex items-center justify-center gap-2 py-2"> <Spinner size="sm" /> <span className="muted text-sm">Loading more...</span> </div> </ListBoxLoadMoreItem> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Custom Filtering ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function CustomFiltering() { const animals = [ {id: "cat", name: "Cat"}, {id: "dog", name: "Dog"}, {id: "bird", name: "Bird"}, {id: "fish", name: "Fish"}, {id: "hamster", name: "Hamster"}, ]; return ( <ComboBox className="w-[256px]" defaultFilter={(text, inputValue) => { if (!inputValue) return true; return text.toLowerCase().includes(inputValue.toLowerCase()); }} > <Label>Animal (custom filter)</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> {animals.map((animal) => ( <ListBox.Item key={animal.id} id={animal.id} textValue={animal.name}> {animal.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Allows Custom Value ```tsx "use client"; import {ComboBox, Description, Input, Label, ListBox} from "@heroui/react"; export function AllowsCustomValue() { return ( <ComboBox allowsCustomValue className="w-[256px]"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search or type an animal..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>You can type any animal name, even if it's not in the list</Description> </ComboBox> ); } ``` ### Disabled ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function Disabled() { return ( <ComboBox isDisabled className="w-[256px]" defaultSelectedKey="cat"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Default Selected Key ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function DefaultSelectedKey() { return ( <ComboBox className="w-[256px]" defaultSelectedKey="cat"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Full Width ```tsx import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <ComboBox fullWidth> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx "use client"; import {Button, ComboBox, FieldError, Form, Input, Label, ListBox, Surface} from "@heroui/react"; export function OnSurface() { const onSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record<string, string> = {}; formData.forEach((value, key) => { data[key] = value.toString(); }); alert("Form submitted successfully!"); }; return ( <Surface className="w-[320px] rounded-3xl p-6"> <Form className="flex w-full flex-col gap-4" onSubmit={onSubmit}> <ComboBox isRequired className="w-full" name="animal"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <FieldError /> </ComboBox> <Button type="submit">Submit</Button> </Form> </Surface> ); } ``` ### Menu Trigger Use the `menuTrigger` prop to control when the popover opens: * `focus` (default): popover opens when the user focuses the input * `input`: popover opens when the user edits the input text * `manual`: popover only opens when the user presses the trigger button or uses the arrow keys ```tsx "use client"; import {ComboBox, Description, Input, Label, ListBox} from "@heroui/react"; export function MenuTrigger() { return ( <div className="flex flex-col gap-8"> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Focus (default)</p> <ComboBox className="w-[256px]" menuTrigger="focus"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>Popover opens when the input is focused</Description> </ComboBox> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Input</p> <ComboBox className="w-[256px]" menuTrigger="input"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>Popover opens when the user edits the input text</Description> </ComboBox> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">Manual</p> <ComboBox className="w-[256px]" menuTrigger="manual"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description> Popover only opens when the trigger button is pressed or arrow keys are used </Description> </ComboBox> </div> </div> ); } ``` ### Custom Render Function ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function CustomRenderFunction() { return ( <ComboBox className="w-[256px]" render={(props) => <div {...props} data-custom="foo" />}> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="Aardvark"> Aardvark <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="Panda"> Panda <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ## Related Components * **Listbox**: Scrollable list of selectable items * **Popover**: Displays content in context with a trigger * **Input**: Single-line text input built on React Aria ## Styling ### Passing Tailwind CSS classes ```tsx import { ComboBox, Input } from '@heroui/react'; function CustomComboBox() { return ( <ComboBox className="w-full"> <Label>Favorite Animal</Label> <ComboBox.InputGroup className="border rounded-lg p-2 bg-surface"> <Input placeholder="Search animals..." /> <ComboBox.Trigger className="text-muted" /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary"> Item 1 </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Customizing the component classes To customize the ComboBox component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .combo-box { @apply flex flex-col gap-1; } .combo-box__input-group { @apply relative inline-flex items-center; } .combo-box__trigger { @apply absolute right-0 text-muted; } .combo-box__popover { @apply rounded-lg border border-border bg-surface p-2; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The ComboBox component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/combo-box.css)): #### Base Classes * `.combo-box` - Base ComboBox container * `.combo-box__input-group` - Container for the input and trigger button * `.combo-box__trigger` - The button that triggers the popover * `.combo-box__popover` - The popover container #### State Classes * `.combo-box[data-invalid="true"]` - Invalid state * `.combo-box[data-disabled="true"]` - Disabled ComboBox state * `.combo-box__trigger[data-focus-visible="true"]` - Focused trigger state * `.combo-box__trigger[data-disabled="true"]` - Disabled trigger state * `.combo-box__trigger[data-open="true"]` - Open trigger state ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Hover**: `:hover` or `[data-hovered="true"]` on trigger * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger * **Disabled**: `:disabled` or `[data-disabled="true"]` on ComboBox * **Open**: `[data-open="true"]` on trigger ## API Reference ### ComboBox Props | Prop | Type | Default | Description | | ----------------------- | ---------------------------------------------------------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `inputValue` | `string` | - | Current input value (controlled) | | `defaultInputValue` | `string` | - | Default input value (uncontrolled) | | `onInputChange` | `(value: string) => void` | - | Handler called when the input value changes | | `selectedKey` | `Key \| null` | - | Current selected key (controlled) | | `defaultSelectedKey` | `Key \| null` | - | Default selected key (uncontrolled) | | `onSelectionChange` | `(key: Key \| null) => void` | - | Handler called when the selection changes | | `isOpen` | `boolean` | - | Sets the open state of the popover (controlled) | | `defaultOpen` | `boolean` | - | Sets the default open state of the popover (uncontrolled) | | `onOpenChange` | `(isOpen: boolean) => void` | - | Handler called when the open state changes | | `items` | `Iterable<T>` | - | The items to display in the listbox | | `disabledKeys` | `Iterable<Key>` | - | Keys of disabled items | | `defaultFilter` | `(text: string, inputValue: string) => boolean` | - | Custom filter function for filtering items | | `isDisabled` | `boolean` | - | Whether the ComboBox is disabled | | `isReadOnly` | `boolean` | - | Whether the input can be selected but not changed by the user | | `isRequired` | `boolean` | - | Whether user input is required | | `isInvalid` | `boolean` | - | Whether the ComboBox value is invalid | | `validate` | `(value: ComboBoxValidationValue) => ValidationError \| true \| null \| undefined` | - | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead | | `validationBehavior` | `"native" \| "aria"` | `"native"` | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA | | `name` | `string` | - | The name of the input, used when submitting an HTML form | | `form` | `string` | - | The id of a `<form>` element to associate the input with | | `formValue` | `"text" \| "key"` | `"key"` | Whether the text or key of the selected item is submitted as part of an HTML form. When `allowsCustomValue` is `true`, this option does not apply and the text is always submitted | | `autoComplete` | `string` | - | Describes the type of autocomplete functionality | | `autoFocus` | `boolean` | - | Whether the element should receive focus on render | | `allowsCustomValue` | `boolean` | - | Whether the ComboBox allows custom values not in the list | | `allowsEmptyCollection` | `boolean` | - | Whether the ComboBox allows an empty collection | | `menuTrigger` | `"focus" \| "input" \| "manual"` | `"focus"` | The interaction required to display the ComboBox menu | | `shouldFocusWrap` | `boolean` | - | Whether keyboard navigation is circular | | `fullWidth` | `boolean` | `false` | Whether the ComboBox should take full width of its container | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | ComboBox content or render function | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ComboBoxRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### ComboBox.InputGroup Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | InputGroup content | ### ComboBox.Trigger Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom trigger content | ### ComboBox.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 | ### RenderProps When using render functions with ComboBox, these values are provided: | Prop | Type | Description | | -------------- | --------------- | --------------------------- | | `state` | `ComboBoxState` | The state of the ComboBox | | `inputValue` | `string` | The current input value | | `selectedKey` | `Key \| null` | The currently selected key | | `selectedItem` | `Node \| null` | The currently selected item | ## Examples ### Basic Usage ```tsx import { ComboBox, Input, Label, ListBox } from '@heroui/react'; <ComboBox className="w-[256px]"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ``` ### With Sections ```tsx import { ComboBox, Input, Label, ListBox, Header, Separator } from '@heroui/react'; <ComboBox className="w-[256px]"> <Label>Country</Label> <ComboBox.InputGroup> <Input placeholder="Search countries..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Section> <Header>North America</Header> <ListBox.Item id="usa" textValue="United States"> United States <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>Europe</Header> <ListBox.Item id="uk" textValue="United Kingdom"> United Kingdom <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> </ListBox> </ComboBox.Popover> </ComboBox> ``` ### Controlled Selection ```tsx import type { Key } from '@heroui/react'; import { ComboBox, Input, Label, ListBox } from '@heroui/react'; import { useState } from 'react'; function ControlledComboBox() { const [selectedKey, setSelectedKey] = useState<Key | null>('cat'); return ( <ComboBox className="w-[256px]" selectedKey={selectedKey} onSelectionChange={setSelectedKey} > <Label>Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Controlled Input Value ```tsx import { ComboBox, Input, Label, ListBox } from '@heroui/react'; import { useState } from 'react'; function ControlledInputComboBox() { const [inputValue, setInputValue] = useState(''); return ( <ComboBox className="w-[256px]" inputValue={inputValue} onInputChange={setInputValue} > <Label>Search</Label> <ComboBox.InputGroup> <Input placeholder="Type to search..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Asynchronous Loading ```tsx import { Collection, ComboBox, EmptyState, Input, Label, ListBox, ListBoxLoadMoreItem, Spinner } from '@heroui/react'; import { useAsyncList } from '@react-stately/data'; interface Character { name: string; } function AsyncComboBox() { const list = useAsyncList<Character>({ async load({cursor, filterText, signal}) { const res = await fetch( cursor || `https://swapi.py4e.com/api/people/?search=${filterText}`, { signal } ); const json = await res.json(); return { items: json.results, cursor: json.next, }; }, }); return ( <ComboBox allowsEmptyCollection className="w-[256px]" inputValue={list.filterText} onInputChange={list.setFilterText} > <Label>Pick a Character</Label> <ComboBox.InputGroup> <Input placeholder="Star Wars characters..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox renderEmptyState={() => <EmptyState />}> <Collection items={list.items}> {(item) => ( <ListBox.Item id={item.name} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> )} </Collection> <ListBoxLoadMoreItem isLoading={list.loadingState === "loadingMore"} onLoadMore={list.loadMore} > <div className="flex items-center justify-center gap-2 py-2"> <Spinner size="sm" /> <span className="text-sm text-muted">Loading more...</span> </div> </ListBoxLoadMoreItem> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Custom Filtering ```tsx import { ComboBox, Input, Label, ListBox } from '@heroui/react'; <ComboBox className="w-[256px]" defaultFilter={(text, inputValue) => { if (!inputValue) return true; return text.toLowerCase().includes(inputValue.toLowerCase()); }} > <Label>Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ``` ### Menu Trigger Control when the popover opens using the `menuTrigger` prop: ```tsx import { ComboBox, Description, Input, Label, ListBox } from '@heroui/react'; // Opens on focus (default) <ComboBox className="w-[256px]" menuTrigger="focus"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>Popover opens when the input is focused</Description> </ComboBox> // Opens when typing <ComboBox className="w-[256px]" menuTrigger="input"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>Popover opens when the user edits the input text</Description> </ComboBox> // Opens only manually <ComboBox className="w-[256px]" menuTrigger="manual"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>Popover only opens when the trigger button is pressed or arrow keys are used</Description> </ComboBox> ``` ### Form Value Use the `formValue` prop to control whether the selected item's key or text is submitted in forms: ```tsx import { Button, ComboBox, FieldError, Form, Input, Label, ListBox } from '@heroui/react'; function FormValueExample() { const onSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); console.log('Submitted value:', formData.get('animal')); // Will be "cat" (the key) }; return ( <Form onSubmit={onSubmit}> {/* Submits the key (default) */} <ComboBox name="animal" formValue="key" isRequired> <Label>Animal</Label> <ComboBox.InputGroup> <Input placeholder="Select an animal..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <FieldError /> </ComboBox> {/* Submits the text */} <ComboBox name="animal-text" formValue="text" isRequired> <Label>Animal (text)</Label> <ComboBox.InputGroup> <Input placeholder="Select an animal..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <FieldError /> </ComboBox> <Button type="submit">Submit</Button> </Form> ); } ``` ### Validation Behavior Control how validation is displayed using the `validationBehavior` prop: ```tsx import { Button, ComboBox, FieldError, Form, Input, Label, ListBox } from '@heroui/react'; function ValidationExample() { return ( <div className="space-y-8"> {/* Native validation (default) - blocks form submission */} <Form> <ComboBox name="animal" isRequired validationBehavior="native"> <Label>Animal (native validation)</Label> <ComboBox.InputGroup> <Input placeholder="Select an animal..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <FieldError /> </ComboBox> <Button type="submit">Submit</Button> </Form> {/* ARIA validation - shows errors in realtime, doesn't block submission */} <Form> <ComboBox name="animal-aria" isRequired validationBehavior="aria"> <Label>Animal (ARIA validation)</Label> <ComboBox.InputGroup> <Input placeholder="Select an animal..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <FieldError /> </ComboBox> <Button type="submit">Submit</Button> </Form> </div> ); } ``` ### Custom Validation Use the `validate` prop to add custom validation logic: ```tsx import { ComboBox, FieldError, Input, Label, ListBox } from '@heroui/react'; function CustomValidationExample() { return ( <ComboBox className="w-[256px]" isRequired validate={(value) => { if (!value || value.selectedKey === null) { return 'Please select an animal'; } if (value.selectedKey === 'snake') { return 'Snakes are not allowed'; } return true; }} > <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="Snake"> Snake <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <FieldError /> </ComboBox> ); } ``` ### Read Only Use the `isReadOnly` prop to make the comboBox read-only: ```tsx import { ComboBox, Input, Label, ListBox } from '@heroui/react'; <ComboBox className="w-[256px]" isReadOnly defaultSelectedKey="cat"> <Label>Favorite Animal</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ``` ## Accessibility The ComboBox component implements the ARIA comboBox pattern and provides: * Full keyboard navigation support * Screen reader announcements for selection changes and input changes * Proper focus management * Support for disabled states * Typeahead search functionality * HTML form integration * Support for custom values For more information, see the [React Aria ComboBox documentation](https://react-spectrum.adobe.com/react-aria/ComboBox.html). </page> <page url="/docs/react/components/select"> # Select **Category**: react **URL**: https://v3.heroui.com/docs/react/components/select **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(pickers)/select.mdx > A select displays a collapsible list of options and allows a user to select one of them ## Import ```tsx import { Select } from "@heroui/react"; ``` ### Usage ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function Default() { return ( <Select className="w-[256px]" placeholder="Select one"> <Label>State</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="Florida"> Florida <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="Delaware"> Delaware <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="California"> California <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="Texas"> Texas <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="New York"> New York <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="Washington"> Washington <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ### Anatomy Import the Select component and access all parts using dot notation. ```tsx import {Select, Label, Description, Header, ListBox, Separator} from "@heroui/react"; export default () => ( <Select> <Label /> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Description /> <Select.Popover> <ListBox> <ListBox.Item> <Label /> <Description /> <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Section> <Header /> <ListBox.Item> <Label /> </ListBox.Item> </ListBox.Section> </ListBox> </Select.Popover> </Select> ); ``` ### With Description ```tsx import {Description, Label, ListBox, Select} from "@heroui/react"; export function WithDescription() { return ( <Select className="w-[256px]" placeholder="Select one"> <Label>State</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="Florida"> Florida <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="Delaware"> Delaware <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="California"> California <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="Texas"> Texas <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="New York"> New York <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="Washington"> Washington <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> <Description>Select your state of residence</Description> </Select> ); } ``` ### Multiple Select ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function MultipleSelect() { return ( <Select className="w-[256px]" placeholder="Select countries" selectionMode="multiple"> <Label>Countries to Visit</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox selectionMode="multiple"> <ListBox.Item id="argentina" textValue="Argentina"> Argentina <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="venezuela" textValue="Venezuela"> Venezuela <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="japan" textValue="Japan"> Japan <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="France"> France <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="italy" textValue="Italy"> Italy <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="spain" textValue="Spain"> Spain <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="thailand" textValue="Thailand"> Thailand <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-zealand" textValue="New Zealand"> New Zealand <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="iceland" textValue="Iceland"> Iceland <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ### With Sections ```tsx import {Header, Label, ListBox, Select, Separator} from "@heroui/react"; export function WithSections() { return ( <Select className="w-[256px]" placeholder="Select a country"> <Label>Country</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Section> <Header>North America</Header> <ListBox.Item id="usa" textValue="United States"> United States <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="canada" textValue="Canada"> Canada <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="mexico" textValue="Mexico"> Mexico <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>Europe</Header> <ListBox.Item id="uk" textValue="United Kingdom"> United Kingdom <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="France"> France <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="germany" textValue="Germany"> Germany <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="spain" textValue="Spain"> Spain <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="italy" textValue="Italy"> Italy <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>Asia</Header> <ListBox.Item id="japan" textValue="Japan"> Japan <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="china" textValue="China"> China <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="india" textValue="India"> India <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="south-korea" textValue="South Korea"> South Korea <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> </ListBox> </Select.Popover> </Select> ); } ``` ### With Disabled Options ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function WithDisabledOptions() { return ( <Select className="w-[256px]" disabledKeys={["cat", "kangaroo"]} placeholder="Select an animal"> <Label>Animal</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="bird" textValue="Bird"> Bird <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="Kangaroo"> Kangaroo <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="elephant" textValue="Elephant"> Elephant <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="tiger" textValue="Tiger"> Tiger <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ### Custom Indicator ```tsx import {ChevronsExpandVertical} from "@gravity-ui/icons"; import {Label, ListBox, Select} from "@heroui/react"; export function CustomIndicator() { return ( <Select className="w-[256px]" placeholder="Select one"> <Label>State</Label> <Select.Trigger> <Select.Value /> <Select.Indicator className="size-3"> <ChevronsExpandVertical /> </Select.Indicator> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="Florida"> Florida <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="Delaware"> Delaware <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="California"> California <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="Texas"> Texas <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="New York"> New York <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="Washington"> Washington <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ### Required ```tsx "use client"; import {Button, FieldError, Form, Label, ListBox, Select} from "@heroui/react"; export function Required() { const onSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record<string, string> = {}; // Convert FormData to plain object formData.forEach((value, key) => { data[key] = value.toString(); }); alert("Form submitted successfully!"); }; return ( <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}> <Select isRequired className="w-full" name="state" placeholder="Select one"> <Label>State</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="Florida"> Florida <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="Delaware"> Delaware <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="California"> California <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="Texas"> Texas <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="New York"> New York <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="Washington"> Washington <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> <FieldError /> </Select> <Select isRequired className="w-full" name="country" placeholder="Select a country"> <Label>Country</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="usa" textValue="United States"> United States <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="canada" textValue="Canada"> Canada <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="mexico" textValue="Mexico"> Mexico <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="uk" textValue="United Kingdom"> United Kingdom <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="France"> France <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="germany" textValue="Germany"> Germany <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> <FieldError /> </Select> <Button type="submit">Submit</Button> </Form> ); } ``` ### Full Width ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <Select fullWidth placeholder="Select one"> <Label>Favorite Animal</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="cat" textValue="Cat"> Cat <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="Dog"> Dog <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="bird" textValue="Bird"> Bird <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> </div> ); } ``` ### Variants The Select component supports two visual variants: * **`primary`** (default) - Standard styling with shadow, suitable for most use cases * **`secondary`** - Lower emphasis variant without shadow, suitable for use in Surface components ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-4"> <Select className="w-[256px]" placeholder="Select one" variant="primary"> <Label>Primary variant</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="option1" textValue="Option 1"> Option 1 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="option2" textValue="Option 2"> Option 2 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> <Select className="w-[256px]" placeholder="Select one" variant="secondary"> <Label>Secondary variant</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="option1" textValue="Option 1"> Option 1 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="option2" textValue="Option 2"> Option 2 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/components/surface) component, use `variant="secondary"` to apply the lower emphasis variant suitable for surface backgrounds. ```tsx "use client"; import {Button, FieldError, Form, Label, ListBox, Select, Surface} from "@heroui/react"; export function OnSurface() { const onSubmit = (e: React.FormEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record<string, string> = {}; // Convert FormData to plain object formData.forEach((value, key) => { data[key] = value.toString(); }); alert("Form submitted successfully!"); }; return ( <Surface className="w-[320px] rounded-3xl p-6"> <Form className="flex w-full flex-col gap-4" onSubmit={onSubmit}> <Select isRequired className="w-full" name="state" placeholder="Select one" variant="secondary" > <Label>State</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="Florida"> Florida <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="Delaware"> Delaware <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="California"> California <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="Texas"> Texas <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="New York"> New York <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="Washington"> Washington <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> <FieldError /> </Select> <Select isRequired className="w-full" name="country" placeholder="Select a country" variant="secondary" > <Label>Country</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="usa" textValue="United States"> United States <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="canada" textValue="Canada"> Canada <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="mexico" textValue="Mexico"> Mexico <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="uk" textValue="United Kingdom"> United Kingdom <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="France"> France <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="germany" textValue="Germany"> Germany <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> <FieldError /> </Select> <Button type="submit">Submit</Button> </Form> </Surface> ); } ``` ### Custom Value ```tsx "use client"; import { Avatar, AvatarFallback, AvatarImage, Description, Label, ListBox, Select, } from "@heroui/react"; export function CustomValue() { const users = [ { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", email: "bob@heroui.com", fallback: "B", id: "1", name: "Bob", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", email: "fred@heroui.com", fallback: "F", id: "2", name: "Fred", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", email: "martha@heroui.com", fallback: "M", id: "3", name: "Martha", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", email: "john@heroui.com", fallback: "J", id: "4", name: "John", }, { avatarUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", email: "jane@heroui.com", fallback: "J", id: "5", name: "Jane", }, ]; return ( <Select className="w-[256px]" placeholder="Select a user"> <Label>User</Label> <Select.Trigger> <Select.Value> {({defaultChildren, isPlaceholder, state}) => { if (isPlaceholder || state.selectedItems.length === 0) { return defaultChildren; } const selectedItems = state.selectedItems; if (selectedItems.length > 1) { return `${selectedItems.length} users selected`; } const selectedItem = users.find((user) => user.id === selectedItems[0]?.key); if (!selectedItem) { return defaultChildren; } return ( <div className="flex items-center gap-2"> <Avatar className="size-4" size="sm"> <AvatarImage src={selectedItem.avatarUrl} /> <AvatarFallback>{selectedItem.fallback}</AvatarFallback> </Avatar> <span>{selectedItem.name}</span> </div> ); }} </Select.Value> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {users.map((user) => ( <ListBox.Item key={user.id} id={user.id} textValue={user.name}> <Avatar size="sm"> <AvatarImage src={user.avatarUrl} /> <AvatarFallback>{user.fallback}</AvatarFallback> </Avatar> <div className="flex flex-col"> <Label>{user.name}</Label> <Description>{user.email}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> ); } ``` ### Controlled ```tsx "use client"; import type {Key} from "react-aria-components"; import {Label, ListBox, Select} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const states = [ { id: "california", name: "California", }, { id: "texas", name: "Texas", }, { id: "florida", name: "Florida", }, { id: "new-york", name: "New York", }, { id: "illinois", name: "Illinois", }, { id: "pennsylvania", name: "Pennsylvania", }, ]; const [state, setState] = useState<Key | null>("california"); const selectedState = states.find((s) => s.id === state); return ( <div className="space-y-2"> <Select className="w-[256px]" placeholder="Select a state" value={state} onChange={(value) => setState(value)} > <Label>State (controlled)</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {states.map((state) => ( <ListBox.Item key={state.id} id={state.id} textValue={state.name}> {state.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> <p className="text-sm text-muted">Selected: {selectedState?.name || "None"}</p> </div> ); } ``` ### Controlled Multiple ```tsx "use client"; import type {Key} from "@heroui/react"; import {Label, ListBox, Select} from "@heroui/react"; import React from "react"; export function ControlledMultiple() { const [selected, setSelected] = React.useState<Key[]>(["california", "texas"]); return ( <div className="space-y-4"> <Select className="w-[256px]" placeholder="Select states" selectionMode="multiple" value={selected} onChange={(keys) => setSelected(keys as Key[])} > <Label>States (controlled multiple)</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox selectionMode="multiple"> <ListBox.Item id="california" textValue="California"> California <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="Texas"> Texas <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="florida" textValue="Florida"> Florida <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="New York"> New York <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="illinois" textValue="Illinois"> Illinois <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="pennsylvania" textValue="Pennsylvania"> Pennsylvania <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> <p className="text-sm text-muted"> Selected: {selected.length > 0 ? selected.join(", ") : "None"} </p> </div> ); } ``` ### Controlled Open State ```tsx "use client"; import {Button, Label, ListBox, Select} from "@heroui/react"; import {useState} from "react"; export function ControlledOpenState() { const [isOpen, setIsOpen] = useState(false); return ( <div className="space-y-4"> <Select className="w-[256px]" isOpen={isOpen} placeholder="Select one" onOpenChange={setIsOpen} > <Label>State</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="Florida"> Florida <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="Delaware"> Delaware <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="California"> California <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="Texas"> Texas <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="New York"> New York <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="Washington"> Washington <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> <Button onPress={() => setIsOpen(!isOpen)}>{isOpen ? "Close" : "Open"} Select</Button> <p className="text-sm text-muted">Select is {isOpen ? "open" : "closed"}</p> </div> ); } ``` ### Asynchronous Loading ```tsx "use client"; import {Label, ListBox, Select, Spinner} from "@heroui/react"; import {useAsyncList} from "@react-stately/data"; import {Collection, ListBoxLoadMoreItem} from "react-aria-components"; interface Pokemon { name: string; } export function AsynchronousLoading() { const list = useAsyncList<Pokemon>({ async load({cursor, signal}) { const res = await fetch(cursor || `https://pokeapi.co/api/v2/pokemon`, {signal}); const json = await res.json(); return { cursor: json.next, items: json.results, }; }, }); return ( <Select className="w-[256px]" placeholder="Select a Pokemon"> <Label>Pick a Pokemon</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <Collection items={list.items}> {(item: Pokemon) => ( <ListBox.Item id={item.name} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> )} </Collection> <ListBoxLoadMoreItem isLoading={list.loadingState === "loadingMore"} onLoadMore={list.loadMore} > <div className="flex items-center justify-center gap-2 py-2"> <Spinner size="sm" /> <span className="text-sm text-muted">Loading more...</span> </div> </ListBoxLoadMoreItem> </ListBox> </Select.Popover> </Select> ); } ``` ### Disabled ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function Disabled() { return ( <div className="flex flex-col gap-4"> <Select isDisabled className="w-[256px]" defaultValue="california" placeholder="Select one"> <Label>State</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="Florida"> Florida <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="Delaware"> Delaware <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="California"> California <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="Texas"> Texas <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="New York"> New York <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="Washington"> Washington <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> <Select isDisabled className="w-[256px]" defaultValue={["argentina", "japan", "france"]} placeholder="Select countries" selectionMode="multiple" > <Label>Countries to Visit</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="argentina" textValue="Argentina"> Argentina <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="venezuela" textValue="Venezuela"> Venezuela <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="japan" textValue="Japan"> Japan <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="France"> France <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="italy" textValue="Italy"> Italy <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="spain" textValue="Spain"> Spain <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> </div> ); } ``` ## Related Components * **Listbox**: Scrollable list of selectable items * **Popover**: Displays content in context with a trigger * **Label**: Accessible label for form controls ### Custom Render Function ```tsx "use client"; import {Label, ListBox, Select} from "@heroui/react"; export function CustomRenderFunction() { return ( <Select className="w-[256px]" placeholder="Select one" render={(props) => <div {...props} data-custom="foo" />} > <Label>State</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="Florida"> Florida <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="Delaware"> Delaware <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="California"> California <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="Texas"> Texas <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="New York"> New York <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="Washington"> Washington <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import {Select} from "@heroui/react"; function CustomSelect() { return ( <Select className="w-full"> <Label>State</Label> <Select.Trigger className="rounded-lg border bg-surface p-2"> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="1" textValue="Item 1" className="hover:bg-surface-secondary"> Item 1 </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ### Customizing the component classes To customize the Select component classes, you can use the `@layer components` directive. <br /> [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .select { @apply flex flex-col gap-1; } .select__trigger { @apply rounded-lg border border-border bg-surface p-2; } .select__value { @apply text-current; } .select__indicator { @apply text-muted; } .select__popover { @apply rounded-lg border border-border bg-surface p-2; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Select component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/select.css)): #### Base Classes * `.select` - Base select container * `.select__trigger` - The button that triggers the select * `.select__value` - The displayed value or placeholder * `.select__indicator` - The dropdown indicator icon * `.select__popover` - The popover container #### Variant Classes * `.select--primary` - Primary variant with shadow (default) * `.select--secondary` - Secondary variant without shadow, suitable for use in surfaces #### State Classes * `.select[data-invalid="true"]` - Invalid state * `.select__trigger[data-focus-visible="true"]` - Focused trigger state * `.select__trigger[data-disabled="true"]` - Disabled trigger state * `.select__value[data-placeholder="true"]` - Placeholder state * `.select__indicator[data-open="true"]` - Open indicator state ### Interactive States The component supports both CSS pseudo-classes and data attributes for flexibility: * **Hover**: `:hover` or `[data-hovered="true"]` on trigger * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on trigger * **Disabled**: `:disabled` or `[data-disabled="true"]` on select * **Open**: `[data-open="true"]` on indicator ## API Reference ### Select Props | Prop | Type | Default | Description | | --------------- | ------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `placeholder` | `string` | `'Select an item'` | Temporary text that occupies the select when it is empty | | `selectionMode` | `"single" \| "multiple"` | `"single"` | Whether single or multiple selection is enabled | | `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 | | `disabledKeys` | `Iterable<Key>` | - | Keys of disabled items | | `isDisabled` | `boolean` | - | Whether the select is disabled | | `value` | `Key \| Key[] \| null` | - | Current value (controlled) | | `defaultValue` | `Key \| Key[] \| null` | - | Default value (uncontrolled) | | `onChange` | `(value: Key \| Key[] \| null) => void` | - | Handler called when the value changes | | `isRequired` | `boolean` | - | Whether user input is required | | `isInvalid` | `boolean` | - | Whether the select value is invalid | | `name` | `string` | - | The name of the input, used when submitting an HTML form | | `autoComplete` | `string` | - | Describes the type of autocomplete functionality | | `fullWidth` | `boolean` | `false` | Whether the select should take full width of its container | | `variant` | `"primary" \| "secondary"` | `"primary"` | Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces. | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Select content or render function | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SelectRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Select.Trigger Props | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | ---------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Trigger content or render function | ### Select.Value Props | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------------------------ | ------- | ---------------------------------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Value content or render function | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SelectValueRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Select.Indicator Props | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom indicator content | ### Select.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 | ### RenderProps When using render functions with Select.Value, these values are provided: | Prop | Type | Description | | ----------------- | ------------- | ---------------------------------- | | `defaultChildren` | `ReactNode` | The default rendered value | | `isPlaceholder` | `boolean` | Whether the value is a placeholder | | `state` | `SelectState` | The state of the select | | `selectedItems` | `Node[]` | The currently selected items | ## Accessibility The Select 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 * HTML form integration For more information, see the [React Aria Select documentation](https://react-spectrum.adobe.com/react-aria/Select.html). </page> <page url="/docs/react/components/kbd"> # Kbd **Category**: react **URL**: https://v3.heroui.com/docs/react/components/kbd **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(typography)/kbd.mdx > Display keyboard shortcuts and key combinations ## Import ```tsx import { Kbd } from "@heroui/react"; ``` ### Usage ```tsx import {Kbd} from "@heroui/react"; export function Basic() { return ( <div className="flex items-center gap-4"> <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>K</Kbd.Content> </Kbd> <Kbd> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>P</Kbd.Content> </Kbd> <Kbd> <Kbd.Abbr keyValue="ctrl" /> <Kbd.Content>C</Kbd.Content> </Kbd> <Kbd> <Kbd.Abbr keyValue="option" /> <Kbd.Content>D</Kbd.Content> </Kbd> </div> ); } ``` ### Anatomy Import the Kbd component and access all parts using dot notation. ```tsx import { Kbd } from "@heroui/react"; export default () => ( <Kbd> <Kbd.Abbr title="Command">⌘</Kbd.Abbr> <Kbd.Content>K</Kbd.Content> </Kbd> ); ``` ### Navigation Keys ```tsx import {Kbd} from "@heroui/react"; export function NavigationKeys() { return ( <div className="flex flex-col gap-4"> <div className="flex items-center gap-2"> <span className="text-sm text-muted">Arrow Keys:</span> <div className="flex items-center gap-2"> <Kbd> <Kbd.Abbr keyValue="up" /> </Kbd> <Kbd> <Kbd.Abbr keyValue="down" /> </Kbd> <Kbd> <Kbd.Abbr keyValue="left" /> </Kbd> <Kbd> <Kbd.Abbr keyValue="right" /> </Kbd> </div> </div> <div className="flex items-center gap-2"> <span className="text-sm text-muted">Page Navigation:</span> <div className="flex items-center gap-2"> <Kbd> <Kbd.Abbr keyValue="pageup" /> </Kbd> <Kbd> <Kbd.Abbr keyValue="pagedown" /> </Kbd> <Kbd> <Kbd.Abbr keyValue="home" /> </Kbd> <Kbd> <Kbd.Abbr keyValue="end" /> </Kbd> </div> </div> </div> ); } ``` ### Inline Usage ```tsx import {Kbd} from "@heroui/react"; export function InlineUsage() { return ( <div className="space-y-4"> <p className="text-sm"> Press{" "} <Kbd> <Kbd.Content>Esc</Kbd.Content> </Kbd>{" "} to close the dialog. </p> <p className="text-sm"> Use{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>K</Kbd.Content> </Kbd>{" "} to open the command palette. </p> <p className="text-sm"> Navigate with{" "} <Kbd> <Kbd.Abbr keyValue="up" /> </Kbd>{" "} and{" "} <Kbd> <Kbd.Abbr keyValue="down" /> </Kbd>{" "} arrow keys. </p> <p className="text-sm"> Save your work with{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>S</Kbd.Content> </Kbd>{" "} regularly. </p> </div> ); } ``` ### Instructional Text ```tsx import {Kbd} from "@heroui/react"; export function InstructionalText() { return ( <div className="space-y-3"> <div className="rounded-lg bg-surface p-4"> <h4 className="mb-2 text-sm font-semibold">Quick Actions</h4> <ul className="space-y-2 text-sm"> <li> • Open search:{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>K</Kbd.Content> </Kbd> </li> <li> • Toggle sidebar:{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>B</Kbd.Content> </Kbd> </li> <li> • New file:{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>N</Kbd.Content> </Kbd> </li> <li> • Quick save:{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>S</Kbd.Content> </Kbd> </li> </ul> </div> </div> ); } ``` ### Special Keys ```tsx import {Kbd} from "@heroui/react"; export function SpecialKeys() { return ( <div className="space-y-3"> <p className="text-sm"> Press{" "} <Kbd> <Kbd.Abbr keyValue="enter" /> </Kbd>{" "} to confirm or{" "} <Kbd> <Kbd.Abbr keyValue="escape" /> </Kbd>{" "} to cancel. </p> <p className="text-sm"> Use{" "} <Kbd> <Kbd.Abbr keyValue="tab" /> </Kbd>{" "} to navigate between form fields and{" "} <Kbd> <Kbd.Abbr keyValue="shift" /> <Kbd.Abbr keyValue="tab" /> </Kbd>{" "} to go back. </p> <p className="text-sm"> Hold{" "} <Kbd> <Kbd.Abbr keyValue="space" /> </Kbd>{" "} to temporarily enable panning mode. </p> </div> ); } ``` ### Variants ```tsx import {Kbd} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-4"> <div className="flex items-center gap-2"> <span>Copy:</span> <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>C</Kbd.Content> </Kbd> <Kbd variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>C</Kbd.Content> </Kbd> </div> <div className="flex items-center gap-2"> <span>Paste:</span> <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>V</Kbd.Content> </Kbd> <Kbd variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>V</Kbd.Content> </Kbd> </div> <div className="flex items-center gap-2"> <span>Cut:</span> <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>X</Kbd.Content> </Kbd> <Kbd variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>X</Kbd.Content> </Kbd> </div> <div className="flex items-center gap-2"> <span>Undo:</span> <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>Z</Kbd.Content> </Kbd> <Kbd variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>Z</Kbd.Content> </Kbd> </div> <div className="flex items-center gap-2"> <span>Redo:</span> <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>Z</Kbd.Content> </Kbd> <Kbd variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>Z</Kbd.Content> </Kbd> </div> </div> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import { Kbd } from "@heroui/react"; function CustomKbd() { return ( <Kbd className="bg-gray-100 dark:bg-gray-800"> <Kbd.Content>K</Kbd.Content> </Kbd> ); } ``` ### Customizing the component classes To customize the Kbd component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .kbd { @apply bg-gray-100 dark:bg-gray-800 border-gray-300; } .kbd__abbr { @apply font-bold; } .kbd__content { @apply text-sm; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Kbd component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/kbd.css)): #### Base Classes * `.kbd` - Base keyboard key styles with background, border, and spacing * `.kbd__abbr` - Abbreviation element for modifier keys * `.kbd__content` - Content wrapper for key text ## API Reference ### Kbd Props | Prop | Type | Default | Description | | | ----------- | ----------------- | --------- | ------------------ | --------------------------- | | `children` | `React.ReactNode` | - | Content of the key | | | `variant` | \`"default" | "light"\` | `default` | Variant of the keyboard key | | `className` | `string` | - | Custom CSS classes | | ### Kbd.Abbr Props | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | --------------------------------------------------------- | | `title` | `string` | - | Title attribute for accessibility (e.g., "Command" for ⌘) | | `children` | `React.ReactNode` | - | The symbol or text to display (e.g., ⌘, ⌥, ⇧) | | `className` | `string` | - | Custom CSS classes | ### Kbd.Key Props | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ----------------------- | | `children` | `React.ReactNode` | - | Text content of the key | | `className` | `string` | - | Custom CSS classes | ### Kbd.Content Type Available key values for the `keyValue` prop: | Modifier Keys | Special Keys | Navigation Keys | Function Keys | | ------------- | ------------ | --------------- | ------------- | | `command` | `enter` | `up` | `fn` | | `shift` | `delete` | `down` | | | `ctrl` | `escape` | `left` | | | `option` | `tab` | `right` | | | `alt` | `space` | `pageup` | | | `win` | `capslock` | `pagedown` | | | | `help` | `home` | | | | | `end` | | </page> <page url="/docs/react/components/scroll-shadow"> # ScrollShadow **Category**: react **URL**: https://v3.heroui.com/docs/react/components/scroll-shadow **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/react/components/(utilities)/scroll-shadow.mdx > Apply visual shadows to indicate scrollable content overflow with automatic detection of scroll position. ## Import ```tsx import { ScrollShadow } from "@heroui/react"; ``` ## Usage ```tsx import {ScrollShadow} from "@heroui/react"; export default function Default() { return ( <div className="w-full p-0 sm:max-w-sm"> <ScrollShadow className="max-h-[240px] p-4"> <div className="space-y-4"> {Array.from({length: 10}).map((_, idx) => ( <p key={`scroll-shadow-lorem-content-${idx}`}> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien. </p> ))} </div> </ScrollShadow> </div> ); } ``` ## Orientation ```tsx import {Card, ScrollShadow} from "@heroui/react"; const images = [ "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg", "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg", "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg", ]; export default function Orientation() { const getRandomImage = (idx: number) => { return images[idx % images.length]; }; return ( <div className="w-full sm:max-w-sm"> <div className="mb-8 w-full"> <h4 className="mb-2 text-sm font-semibold">Vertical</h4> <Card className="w-full p-0"> <ScrollShadow className="max-h-[240px] p-4" orientation="vertical"> <div className="space-y-4"> {Array.from({length: 10}).map((_, idx) => ( <p key={`scroll-shadow-lorem-content-${idx}`}> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien. </p> ))} </div> </ScrollShadow> </Card> </div> <div className="w-full"> <h4 className="mb-2 text-sm font-semibold">Horizontal</h4> <Card className="w-full p-0"> <ScrollShadow className="p-4" orientation="horizontal"> <div className="flex flex-row gap-4"> {Array.from({length: 10}).map((_, idx) => ( <Card key={`scroll-shadow-lorem-cards-${idx}`} className="flex min-w-[200px] flex-row gap-3 p-1" variant="transparent" > <img alt="Lorem Card" className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20" loading="lazy" src={getRandomImage(idx)} /> <div className="flex flex-1 flex-col justify-center gap-1"> <Card.Title className="text-sm">Bridging the Future</Card.Title> <Card.Description className="text-xs">Today, 6:30 PM</Card.Description> </div> </Card> ))} </div> </ScrollShadow> </Card> </div> </div> ); } ``` ## Hide Scroll Bar ```tsx import {ScrollShadow} from "@heroui/react"; export default function HideScrollBar() { return ( <div className="w-full p-0 sm:max-w-sm"> <ScrollShadow hideScrollBar className="max-h-[240px] p-4"> <div className="space-y-4"> {Array.from({length: 10}).map((_, idx) => ( <p key={`scroll-shadow-lorem-content-${idx}`}> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien. </p> ))} </div> </ScrollShadow> </div> ); } ``` ## Custom Shadow Size ```tsx import {ScrollShadow} from "@heroui/react"; export default function CustomSize() { return ( <div className="w-full p-0 sm:max-w-sm"> <ScrollShadow className="max-h-[240px] p-4" size={80}> <div className="space-y-4"> {Array.from({length: 10}).map((_, idx) => ( <p key={`scroll-shadow-lorem-content-${idx}`}> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien. </p> ))} </div> </ScrollShadow> </div> ); } ``` ## Visibility Change ```tsx "use client"; import type {ScrollShadowVisibility} from "@heroui/react"; import {Card, ScrollShadow} from "@heroui/react"; import {useState} from "react"; const images = [ "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/robot1.jpeg", "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/avocado.jpeg", "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/oranges.jpeg", ]; export default function VisibilityChange() { const [verticalState, setVerticalState] = useState<ScrollShadowVisibility>("none"); const [horizontalState, setHorizontalState] = useState<ScrollShadowVisibility>("none"); const getRandomImage = (idx: number) => { return images[idx % images.length]; }; return ( <div className="w-full sm:max-w-sm"> <div className="mb-8 flex flex-col gap-2"> <div className="rounded bg-default p-4"> <p className="text-sm font-semibold">Vertical Shadow State: {verticalState}</p> </div> <div className="w-full"> <ScrollShadow className="max-h-[240px] p-4" orientation="vertical" onVisibilityChange={(visibility) => setVerticalState(visibility)} > <div className="space-y-4"> {Array.from({length: 10}).map((_, idx) => ( <p key={`scroll-shadow-lorem-content-${idx}`}> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien. </p> ))} </div> </ScrollShadow> </div> </div> <div className="flex flex-col gap-2"> <div className="rounded bg-default p-4"> <p className="text-sm font-semibold">Horizontal Shadow State: {horizontalState}</p> </div> <div className="w-full"> <ScrollShadow className="p-4" orientation="horizontal" onVisibilityChange={(visibility) => setHorizontalState(visibility)} > <div className="flex flex-row gap-4"> {Array.from({length: 10}).map((_, idx) => ( <Card key={`scroll-shadow-lorem-cards-${idx}`} className="flex min-w-[200px] flex-row gap-3 p-1" variant="transparent" > <img alt="Lorem Card" className="aspect-square h-16 w-16 shrink-0 rounded-xl object-cover select-none sm:h-20 sm:w-20" loading="lazy" src={getRandomImage(idx)} /> <div className="flex flex-1 flex-col justify-center gap-1"> <Card.Title className="text-sm">Bridging the Future</Card.Title> <Card.Description className="text-xs">Today, 6:30 PM</Card.Description> </div> </Card> ))} </div> </ScrollShadow> </div> </div> </div> ); } ``` ## With Card ```tsx import {Button, Card, ScrollShadow} from "@heroui/react"; export default function WithCard() { return ( <Card className="max-w-[400px]"> <Card.Header> <Card.Title>Terms and Conditions</Card.Title> <Card.Description>Please review before proceeding</Card.Description> </Card.Header> <Card.Content className="p-0"> <ScrollShadow className="h-[300px] px-4" size={80}> <div className="space-y-4"> {Array.from({length: 10}).map((_, idx) => ( <p key={`scroll-shadow-lorem-content-${idx}`}> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. Pellentesque sit amet hendrerit risus, sed porttitor quam. Morbi accumsan cursus enim, sed ultricies sapien. </p> ))} </div> </ScrollShadow> </Card.Content> <Card.Footer className="mt-4 flex flex-row gap-2"> <Button className="w-full" variant="secondary"> Cancel </Button> <Button className="w-full">Accept</Button> </Card.Footer> </Card> ); } ``` ## Styling ### Passing Tailwind CSS classes ```tsx import {ScrollShadow, Card} from "@heroui/react"; function CustomScrollShadow() { return ( <Card className="w-full p-0 sm:max-w-md"> <ScrollShadow className="max-h-[300px] p-6 bg-gradient-to-b from-purple-50 to-pink-50"> <div className="space-y-4"> {Array.from({length: 10}).map((_, idx) => ( <p key={idx}> Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam pulvinar risus non risus hendrerit venenatis. </p> ))} </div> </ScrollShadow> </Card> ); } ``` ### Customizing the component classes To customize the ScrollShadow component classes, you can use the `@layer components` directive. <br />[Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .scroll-shadow { @apply rounded-xl border border-default-200; } .scroll-shadow--vertical { @apply pr-2; /* Add padding for custom scrollbar styling */ } .scroll-shadow--horizontal { @apply pb-2; } } ``` HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The ScrollShadow component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/scroll-shadow.css)): #### Base Classes * `.scroll-shadow` - Root container element #### Orientation Variants * `.scroll-shadow--vertical` - Vertical scrolling (default) * `.scroll-shadow--horizontal` - Horizontal scrolling #### State Modifiers * `.scroll-shadow--hide-scrollbar` - Hides native scrollbar ### Data Attributes The component uses data attributes to control shadow visibility: * **Scroll States**: `[data-top-scroll]`, `[data-bottom-scroll]`, `[data-left-scroll]`, `[data-right-scroll]` - Applied when content can be scrolled in that direction * **Combined States**: `[data-top-bottom-scroll]`, `[data-left-right-scroll]` - Applied when content can be scrolled in both directions * **Orientation**: `[data-orientation="vertical"]` or `[data-orientation="horizontal"]` - Indicates scroll direction * **Size**: `[data-scroll-shadow-size]` - Contains the shadow gradient size value ## API Reference ### ScrollShadow | Prop | Type | Default | Description | | -------------------- | ---------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------- | | `orientation` | `"vertical"` \| `"horizontal"` | `"vertical"` | The scroll direction | | `variant` | `"fade"` | `"fade"` | The visual shadow effect style | | `size` | `number` | `40` | The shadow gradient size in pixels | | `offset` | `number` | `0` | The scroll offset before showing shadows (in pixels) | | `hideScrollBar` | `boolean` | `false` | Whether to hide the native scrollbar | | `isEnabled` | `boolean` | `true` | Whether scroll shadow detection is enabled | | `visibility` | `"auto"` \| `"both"` \| `"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"none"` | `"auto"` | Controlled shadow visibility state | | `onVisibilityChange` | `(visibility: ScrollShadowVisibility) => void` | - | Callback invoked when shadow visibility changes | | `className` | `string` | - | Additional CSS classes to apply to the root element | | `children` | `ReactNode` | - | The scrollable content | </page>