}> Accept terms and conditions ); } ``` ### Custom Indicator ```tsx "use client"; import {Checkbox} from "@heroui/react"; export function CustomIndicator() { return ( ); } ``` ## Customization ### Tailwind CSS ```tsx import {Checkbox} from "@heroui/react"; export function CustomStyles() { return ( Custom styled checkbox ); } ``` ### Global CSS 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 items-center gap-3; } } ``` ## Styling Reference 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)): #### Base Classes \[!toc] * `.checkbox` - Base checkbox container (the field) * `.checkbox__content` - Clickable label wrapping the control and label text * `.checkbox__control` - Checkbox control box * `.checkbox__indicator` - Checkbox checkmark indicator ### 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"]` on `Checkbox.Control` (button) * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` on the button (shows focus ring on control) * **Disabled**: `[data-disabled="true"]` on the field (reduced opacity, including help text) * **Pressed**: `:active` or `[data-pressed="true"]` ## API Reference ### Checkbox Inherits from [React Aria CheckboxField](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 | | `isRequired` | `boolean` | `false` | Whether the checkbox must be selected | | `validate` | `(value: boolean) => ValidationError \| true \| null \| undefined` | - | Custom validation function | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | Whether to use native HTML form validation or ARIA | | `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: CheckboxFieldRenderProps) => React.ReactNode` | - | Checkbox content or field render prop | | `render` | `DOMRenderFunction` | - | Overrides the default DOM element with a custom render function. | ### Checkbox.Content The clickable `` that wraps the control and label text. Put `Checkbox.Control` and the `Label` inside it; keep `Description`/`FieldError` as siblings of `Checkbox.Content`. For a checkbox with no label, omit the `Label` and pass an `aria-label` on `Checkbox`. | Prop | Type | Default | Description | | ----------- | --------------------------------------------------------------------------- | ------- | --------------------------------------------------------- | | `children` | `React.ReactNode \| (values: CheckboxButtonRenderProps) => React.ReactNode` | - | Button content (control + label), or a button render prop | | `className` | `string \| (values: CheckboxButtonRenderProps) => string` | - | Classes applied to the clickable label | ### CheckboxFieldRenderProps When using a render prop on the root `Checkbox`, these field-level values are provided: | Prop | Type | Description | | ----------------- | --------- | ------------------------------------------------- | | `isSelected` | `boolean` | Whether the checkbox is currently checked | | `isIndeterminate` | `boolean` | Whether the checkbox is in an indeterminate state | | `isDisabled` | `boolean` | Whether the checkbox is disabled | | `isReadOnly` | `boolean` | Whether the checkbox is read only | | `isInvalid` | `boolean` | Whether the checkbox is invalid | | `isRequired` | `boolean` | Whether the checkbox is required | ### CheckboxButtonRenderProps `Checkbox.Control` and `Checkbox.Indicator` use button-level render props (`isHovered`, `isPressed`, `isFocusVisible`, etc.). Pass a function as `Checkbox.Control` children or to `Checkbox.Indicator` to access them. ## Related Components ## Related Components * **Label**: Accessible label for form controls * **CheckboxGroup**: Group of checkboxes with shared state * **Description**: Helper text for form fields # Description **Category**: react **URL**: https://heroui.com/en/docs/react/components/description **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/description.mdx > Provides supplementary text for form fields and other components ## Usage ```tsx import { Description } from '@heroui/react'; ``` ```tsx import {Description, Input, Label} from "@heroui/react"; export function Basic() { return (

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

); } ``` ## 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. ## Customization ### Tailwind CSS ```tsx import {Description, Input, Label} from "@heroui/react"; export function CustomStyles() { return (

Workspace URL Lowercase letters and hyphens only. Used in app.heroui.com/acme

); } ``` ### Global CSS To customize the Description component classes, you can use the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .description { @apply text-muted; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Description component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/description.css)): #### Base Classes \[!toc] * `.description` - Base description styles with `muted` text color ## API Reference ### Description | 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 ## Related Components ## 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 # ErrorMessage **Category**: react **URL**: https://heroui.com/en/docs/react/components/error-message **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/error-message.mdx > A low-level error message component for displaying errors ## Usage ```tsx import { ErrorMessage } from '@heroui/react'; ``` ```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} ); } ``` `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. ## Anatomy ```tsx import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react'; ``` ## 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/react/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/react/components/field-error) and the [Form guide](/docs/react/components/form) for examples and best practices. ## Customization ### Tailwind CSS ```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 CustomStyles() { const [selected, setSelected] = useState>(new Set()); const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]); return ( Topics API Design Docs Pick at least one topic {!!isInvalid && <>Choose at least one topic} ); } ``` ### Global CSS 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-sm font-medium text-danger; } } ``` ## Styling Reference 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 \[!toc] * `.error-message` - Base error message styles with danger color and text truncation #### Slot Classes \[!toc] * `[slot="errorMessage"]` - ErrorMessage slot styles for React Aria integration ## API Reference ### ErrorMessage | 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 ## Related Components ## Related Components * **TagGroup**: Focusable list of tags with selection and removal support # FieldError **Category**: react **URL**: https://heroui.com/en/docs/react/components/field-error **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/field-error.mdx > Displays validation error messages for form fields ## Usage ```tsx import { FieldError } from '@heroui/react'; ``` ```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 ); } ``` 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. ## 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}

))} ``` ## Customization ### Tailwind CSS ```tsx "use client"; import {FieldError, Input, Label, TextField} from "@heroui/react"; import {useState} from "react"; export function CustomStyles() { const [value, setValue] = useState("jr"); const isInvalid = value.length > 0 && value.length < 3; return ( Handle setValue(e.target.value)} /> Handle must be at least 3 characters ); } ``` ### Global CSS To customize the FieldError component classes, you can use the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .field-error { @apply font-medium text-danger; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The FieldError component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/field-error.css)): #### Base Classes \[!toc] * `.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 ## API Reference ### FieldError | 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 ## Related Components ## 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 # Fieldset **Category**: react **URL**: https://heroui.com/en/docs/react/components/fieldset **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/fieldset.mdx > Group related form controls with legends, descriptions, and actions ## Usage ```tsx import { Fieldset } from '@heroui/react'; ``` ```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.SyntheticEvent) => { 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> ); } ``` ## Anatomy ```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> ) ``` ## Examples ### In Surface When used inside a [Surface](/docs/react/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.SyntheticEvent<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> ); } ``` ## Customization ### Tailwind CSS ```tsx "use client"; import {FloppyDisk} from "@gravity-ui/icons"; import { Button, Description, FieldError, FieldGroup, Fieldset, Form, Input, Label, TextArea, TextField, } from "@heroui/react"; const shell = "rounded-xl border border-border/70 bg-linear-to-b from-neutral-50/90 to-white p-4 ring-1 ring-black/5 dark:from-neutral-900/80 dark:to-neutral-900 dark:ring-white/10"; const field = "rounded-xl border border-border/80 bg-surface shadow-sm ring-1 ring-black/5 transition-[box-shadow,border-color] focus-visible:ring-2 focus-visible:ring-neutral-400/25 dark:ring-white/10 dark:focus-visible:ring-neutral-500/30"; export function CustomStyles() { const onSubmit = (e: React.SyntheticEvent<HTMLFormElement>) => { e.preventDefault(); alert("Form submitted successfully!"); }; return ( <Form className="w-full max-w-96" onSubmit={onSubmit}> <Fieldset className={shell}> <Fieldset.Legend className="font-medium text-neutral-800 dark:text-neutral-100"> Profile Settings </Fieldset.Legend> <Description className="text-neutral-600 dark:text-neutral-400"> Update your profile information. </Description> <FieldGroup> <TextField isRequired name="name" validate={(value) => { if (value.length < 3) { return "Name must be at least 3 characters"; } return null; }} > <Label>Name</Label> <Input className={field} placeholder="John Doe" /> <FieldError /> </TextField> <TextField isRequired name="email" type="email"> <Label>Email</Label> <Input className={field} placeholder="john@example.com" /> <FieldError /> </TextField> <TextField isRequired name="bio" validate={(value) => { if (value.length < 10) { return "Bio must be at least 10 characters"; } return null; }} > <Label>Bio</Label> <TextArea className={field} placeholder="Tell us about yourself..." /> <Description>Minimum 10 characters</Description> <FieldError /> </TextField> </FieldGroup> <Fieldset.Actions> <Button type="submit"> <FloppyDisk /> Save changes </Button> <Button type="reset" variant="secondary"> Cancel </Button> </Fieldset.Actions> </Fieldset> </Form> ); } ``` ### Global CSS 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; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Fieldset compound component exposes these CSS selectors: #### Base Classes \[!toc] * `.fieldset` – Root container * `.fieldset__legend` – Legend element * `.fieldset__field-group` – Wrapper for grouped fields * `.fieldset__actions` – Action bar below the fields ## API Reference ### Fieldset | 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 | 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 | 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 | 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. | ## Related Showcases ## Related Components ## Related Components * **TextField**: Composition-friendly fields with labels and validation * **Label**: Accessible label for form controls * **CheckboxGroup**: Group of checkboxes with shared state </page> <page url="/en/docs/react/components/form"> # Form **Category**: react **URL**: https://heroui.com/en/docs/react/components/form **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/form.mdx > Wrapper component for form validation and submission handling ## Usage ```tsx import { Form } from '@heroui/react'; ``` ```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.SyntheticEvent<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 ```tsx import {Form, Button} from '@heroui/react'; export default () => ( <Form> {/* Form fields go here */} <Button type="submit"/> <Button type="reset"/> </Form> ) ``` ## Examples ### Render Function ```tsx "use client"; import {Check} from "@gravity-ui/icons"; import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react"; export function RenderFunction() { const onSubmit = (e: React.SyntheticEvent<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> ); } ``` ## Customization ### Tailwind CSS ```tsx "use client"; import {Button, Form, Input, Label, TextField} from "@heroui/react"; export function CustomStyles() { return ( <Form className="flex w-80 flex-col gap-3 rounded-xl border border-border/80 bg-surface p-4 shadow-sm" onSubmit={(e) => e.preventDefault()} > <TextField isRequired name="email" type="email"> <Label>Work email</Label> <Input className="bg-field" placeholder="you@company.com" /> </TextField> <Button className="w-full" type="submit"> Continue </Button> </Form> ); } ``` ### Global CSS To customize form layout and spacing, use the `className` prop on `<Form>` or add a project-level class with the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). `Form` renders a native `<form>` element and focuses on validation and submission. It does not include dedicated BEM classes in `@heroui/styles`—apply container styles from global CSS, and use field components for control-level customization. ```css @layer components { .form-layout { @apply flex flex-col gap-4 rounded-xl border border-border bg-surface p-4 shadow-sm; } } ``` ```tsx <Form className="form-layout" onSubmit={handleSubmit}> {/* TextField, Input, Button, etc. */} </Form> ``` For grouped fields with shared layout, use [Fieldset](./fieldset) and target `.fieldset`, `.fieldset__legend`, and related classes. For individual controls, see **Global CSS** on [TextField](./text-field), [Input](./input), [Label](./label), and [FieldError](./field-error). ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology for components that ship styles in `@heroui/styles`. `Form` renders a native `<form>` element without dedicated BEM classes. Apply layout, spacing, and surface styles through `className`. Field appearance and validation states come from child components such as `TextField`, `Input`, `Label`, `Description`, and `FieldError`. For structured multi-field layouts, compose with [Fieldset](./fieldset). ## API Reference ### Form 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: SyntheticEvent<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: SyntheticEvent<HTMLFormElement>) => void` | - | Handler called when the form is reset. | | `onSubmit` | `(event: SyntheticEvent<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 import type {SyntheticEvent} from "react"; function handleSubmit(e: SyntheticEvent<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. ### 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). ## 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"` ## Related Showcases ## Related Components ## 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 </page> <page url="/en/docs/react/components/input-group"> # InputGroup **Category**: react **URL**: https://heroui.com/en/docs/react/components/input-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/input-group.mdx > Group related input controls with prefix and suffix elements for enhanced form fields ## Usage ```tsx import { InputGroup } from '@heroui/react'; ``` ```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/react/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. ## Examples ### 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/react/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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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="pe-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="pe-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="pe-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> ); } ``` ### Keyboard Shortcut Display keyboard shortcuts using the [Kbd](/docs/react/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="pe-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="pe-2"> <Chip color="accent" size="md" variant="soft"> Pro </Chip> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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="ms-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> ); } ``` ### 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 aria-label="Confirm" 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> ); } ``` ## Customization ### Tailwind CSS ```tsx "use client"; import {Envelope} from "@gravity-ui/icons"; import {InputGroup, Label, TextField} from "@heroui/react"; export function CustomStyles() { return ( <TextField className="w-full max-w-xs" name="email"> <Label>Work email</Label> <InputGroup className="rounded-xl border border-border/80 bg-default shadow-sm"> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input placeholder="you@company.com" /> </InputGroup> </TextField> ); } ``` ### Global CSS 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); } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes #### Base Classes \[!toc] * `.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. #### Variant Classes \[!toc] * `.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 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. | ## Related Showcases ## Related Components ## 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 </page> <page url="/en/docs/react/components/input-otp"> # InputOTP **Category**: react **URL**: https://heroui.com/en/docs/react/components/input-otp **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/input-otp.mdx > A one-time password input component for verification codes and secure authentication ## Usage ```tsx import { InputOTP } from '@heroui/react'; ``` ```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 ```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. ## Examples ### 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/react/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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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.SyntheticEvent<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.SyntheticEvent<HTMLFormElement>) => { 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> ); } ``` ### 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> ); } ``` ### 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.SyntheticEvent<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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {InputOTP, Label, Link} from "@heroui/react"; const slotClass = "rounded-lg border-border/80 bg-default data-[active=true]:border-accent/40 data-[active=true]:bg-accent-soft"; export function CustomStyles() { return ( <div className="flex w-72 flex-col gap-2"> <Label>Verify account</Label> <InputOTP maxLength={6}> <InputOTP.Group> <InputOTP.Slot className={slotClass} index={0} /> <InputOTP.Slot className={slotClass} index={1} /> <InputOTP.Slot className={slotClass} index={2} /> </InputOTP.Group> <InputOTP.Separator className="bg-border" /> <InputOTP.Group> <InputOTP.Slot className={slotClass} index={3} /> <InputOTP.Slot className={slotClass} index={4} /> <InputOTP.Slot className={slotClass} index={5} /> </InputOTP.Group> </InputOTP> <Link className="text-sm text-link" href="#"> Resend code </Link> </div> ); } ``` ### Global CSS To customize the InputOTP component classes, you can use the `@layer components` directive. [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-accent-500 ring-2 ring-accent-200; } .input-otp__separator { @apply w-2 h-1 bg-border-strong rounded-full; } } ``` ## Styling Reference 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 \[!toc] * `.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 \[!toc] * `.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 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 | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ------------------------------------- | | `className` | `string` | - | Additional CSS classes for the group. | | `children` | `React.ReactNode` | - | InputOTP.Slot components. | ### InputOTP.Slot | Prop | Type | Default | Description | | ----------- | -------- | ------- | ------------------------------------------- | | `index` | `number` | - | **Required.** Zero-based index of the slot. | | `className` | `string` | - | Additional CSS classes for the slot. | ### InputOTP.Separator | 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) ## Related Components ## Related Components * **Input**: Single-line text input built on React Aria * **Form**: Form validation and submission handling * **Surface**: Base container surface </page> <page url="/en/docs/react/components/input"> # Input **Category**: react **URL**: https://heroui.com/en/docs/react/components/input **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/input.mdx > Primitive single-line text input component that accepts standard HTML attributes ## Usage ```tsx import { Input } from '@heroui/react'; ``` ```tsx import {Input} from "@heroui/react"; export function Basic() { return <Input aria-label="Name" className="w-64" placeholder="Enter your name" />; } ``` <Callout> For validation, labels, and error messages, see **[TextField](/docs/react/components/text-field)**. </Callout> ## Examples ### 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/react/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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Input} from "@heroui/react"; export function CustomStyles() { return ( <Input aria-label="Search projects" className="w-64 rounded-xl border border-border/80 bg-default text-foreground placeholder:text-muted" placeholder="Search projects..." /> ); } ``` ### Global CSS The base class `.input` powers every instance. Override it once with `@layer components`. ```css @layer components { .input { @apply rounded-lg border border-border bg-surface 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-accent ring-2 ring-accent/20; } &[data-invalid="true"] { @apply border-danger bg-danger-soft text-danger; } } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes #### Base Classes \[!toc] * `.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 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/react/components/text-field)** with Input as a child component. ## Related Components ## Related Components * **TextField**: Composition-friendly fields with labels and validation * **TextArea**: Multiline text input with focus management * **Label**: Accessible label for form controls </page> <page url="/en/docs/react/components/label"> # Label **Category**: react **URL**: https://heroui.com/en/docs/react/components/label **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/label.mdx > Renders an accessible label associated with form controls ## Usage ```tsx import { Label } from '@heroui/react'; ``` ```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> ); } ``` ## 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 /> ``` ## Customization ### Tailwind CSS ```tsx import {Input, Label} from "@heroui/react"; export function CustomStyles() { return ( <div className="flex flex-col gap-1.5"> <Label className="text-xs font-semibold tracking-wide text-accent uppercase" htmlFor="repo"> Repository </Label> <Input className="w-64 bg-field" id="repo" placeholder="heroui/react" /> </div> ); } ``` ### Global CSS To customize the Label component classes, you can use the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .label { @apply font-semibold text-foreground; } .label--required::after { @apply text-accent; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### 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 \[!toc] * `.label` - Base label styles with text styling #### State Modifier Classes \[!toc] * `.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. ## API Reference ### Label | 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 ## 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 </page> <page url="/en/docs/react/components/number-field"> # NumberField **Category**: react **URL**: https://heroui.com/en/docs/react/components/number-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/number-field.mdx > Number input fields with increment/decrement buttons, validation, and internationalized formatting ## Usage ```tsx import { NumberField } from '@heroui/react'; ``` ```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. ## Examples ### 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/react/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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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.SyntheticEvent<HTMLFormElement>) => { 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> ); } ``` ### 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> ); } ``` ### 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 className="flex"> <NumberField.Input className="flex-1" /> <div className="flex h-full flex-col border-s border-field-placeholder/15"> <NumberField.IncrementButton className="flex h-1/2 w-6 items-center justify-center rounded-none border-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="flex h-1/2 w-6 items-center justify-center rounded-none border-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> ); } ``` ### Render Function ```tsx "use client"; import {Label, NumberField} from "@heroui/react"; export function RenderFunction() { 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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Label, NumberField} from "@heroui/react"; export function CustomStyles() { return ( <NumberField className="w-full max-w-48" defaultValue={2} minValue={1} name="guests" variant="secondary" > <Label className="font-medium text-foreground">Guests</Label> <NumberField.Group className="rounded-xl bg-default"> <NumberField.DecrementButton className="text-muted hover:text-foreground" /> <NumberField.Input className="text-center tabular-nums" /> <NumberField.IncrementButton className="text-muted hover:text-foreground" /> </NumberField.Group> </NumberField> ); } ``` ### Global CSS 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; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes #### Base Classes \[!toc] * `.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 #### Variant Classes \[!toc] * `.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/react/components/label), [Description](/docs/react/components/description), [FieldError](/docs/react/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 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). | ### Render Props 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. | ## Related Showcases ## Related Components ## Related Components * **Label**: Accessible label for form controls * **Description**: Helper text for form fields * **FieldError**: Inline validation messages for form fields </page> <page url="/en/docs/react/components/radio-group"> # RadioGroup **Category**: react **URL**: https://heroui.com/en/docs/react/components/radio-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/radio-group.mdx > Radio group for selecting a single option from a list ## Usage ```tsx import { RadioGroup, Radio } from '@heroui/react'; ``` ```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.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Basic Plan </Radio.Content> <Description>Includes 100 messages per month</Description> </Radio> <Radio value="premium"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Premium Plan </Radio.Content> <Description>Includes 200 messages per month</Description> </Radio> <Radio value="business"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Business Plan </Radio.Content> <Description>Unlimited messages</Description> </Radio> </RadioGroup> ); } ``` ## Anatomy ```tsx import {RadioGroup, Radio, Label, Description, FieldError} from '@heroui/react'; export default () => ( <RadioGroup> <Label /> <Description /> <Radio value="option1"> <Radio.Content> {/* The clickable area: control + label */} <Radio.Control> <Radio.Indicator> <span>✓</span> {/* Custom indicator (optional) */} </Radio.Indicator> </Radio.Control> Label {/* plain text — the clickable label */} </Radio.Content> <Description /> {/* Sibling — stays outside the button (announced via aria-describedby) */} <FieldError /> {/* Optional — per-radio validation message */} </Radio> <FieldError /> {/* Optional — group-level validation */} </RadioGroup> ) ``` ## Examples ### 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.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Starter </Radio.Content> <Description>For side projects</Description> </Radio> <Radio value="pro"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Pro </Radio.Content> <Description>Advanced reporting</Description> </Radio> <Radio value="teams"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Teams </Radio.Content> <Description>Up to 10 teammates</Description> </Radio> </RadioGroup> </div> ); } ``` ### 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, 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.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Option 1 </Radio.Content> <Description>Standard styling with default background</Description> </Radio> <Radio value="option2"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Option 2 </Radio.Content> <Description>Another option with primary styling</Description> </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.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Option 1 </Radio.Content> <Description>Lower emphasis variant for use in surfaces</Description> </Radio> <Radio value="option2"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Option 2 </Radio.Content> <Description>Another option with secondary styling</Description> </Radio> </RadioGroup> </div> </div> ); } ``` ### In Surface When used inside a [Surface](/docs/react/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-on-surface" variant="secondary"> <Label>Plan selection</Label> <Description>Choose the plan that suits you best</Description> <Radio value="basic"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Basic Plan </Radio.Content> <Description>Includes 100 messages per month</Description> </Radio> <Radio value="premium"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Premium Plan </Radio.Content> <Description>Includes 200 messages per month</Description> </Radio> <Radio value="business"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Business Plan </Radio.Content> <Description>Unlimited messages</Description> </Radio> </RadioGroup> </Surface> ); } ``` ### 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.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Starter </Radio.Content> <Description>For side projects and small teams</Description> </Radio> <Radio value="pro"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Pro </Radio.Content> <Description>Advanced reporting and analytics</Description> </Radio> <Radio value="teams"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Teams </Radio.Content> <Description>Share access with up to 10 teammates</Description> </Radio> </RadioGroup> ); } ``` ### 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.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Starter </Radio.Content> <Description>For side projects and small teams</Description> </Radio> <Radio value="pro"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Pro </Radio.Content> <Description>Advanced reporting and analytics</Description> </Radio> <Radio value="teams"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Teams </Radio.Content> <Description>Share access with up to 10 teammates</Description> </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.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Starter </Radio.Content> <Description>For side projects and small teams</Description> </Radio> <Radio value="pro"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Pro </Radio.Content> <Description>Advanced reporting and analytics</Description> </Radio> <Radio value="teams"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Teams </Radio.Content> <Description>Share access with up to 10 teammates</Description> </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.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Starter </Radio.Content> <Description>For side projects and small teams</Description> </Radio> <Radio value="pro"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Pro </Radio.Content> <Description>Advanced reporting and analytics</Description> </Radio> <Radio value="teams"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Teams </Radio.Content> <Description>Share access with up to 10 teammates</Description> </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> ); } ``` ### Delivery & Payment ### 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.Content> <Radio.Control> <Radio.Indicator> {({isSelected}) => isSelected ? <span className="text-xs leading-none text-background">✓</span> : null } </Radio.Indicator> </Radio.Control> Basic Plan </Radio.Content> <Description>Includes 100 messages per month</Description> </Radio> <Radio value="premium"> <Radio.Content> <Radio.Control> <Radio.Indicator> {({isSelected}) => isSelected ? <span className="text-xs leading-none text-background">✓</span> : null } </Radio.Indicator> </Radio.Control> Premium Plan </Radio.Content> <Description>Includes 200 messages per month</Description> </Radio> <Radio value="business"> <Radio.Content> <Radio.Control> <Radio.Indicator> {({isSelected}) => isSelected ? <span className="text-xs leading-none text-background">✓</span> : null } </Radio.Indicator> </Radio.Control> Business Plan </Radio.Content> <Description>Unlimited messages</Description> </Radio> </RadioGroup> ); } ``` ### Render Function ```tsx "use client"; import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function RenderFunction() { return ( <RadioGroup defaultValue="premium" name="plan-custom-render" render={(props) => <div {...props} data-custom="foo" />} > <Label>Plan selection</Label> <Description>Choose the plan that suits you best</Description> <Radio value="basic"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Basic Plan </Radio.Content> <Description>Includes 100 messages per month</Description> </Radio> <Radio value="premium"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Premium Plan </Radio.Content> <Description>Includes 200 messages per month</Description> </Radio> <Radio value="business"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Business Plan </Radio.Content> <Description>Unlimited messages</Description> </Radio> </RadioGroup> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Description, Label, Radio, RadioGroup} from "@heroui/react"; const options = [ {description: "$12 billed every month", label: "Monthly", value: "monthly"}, {description: "$120 billed once a year", label: "Yearly", value: "yearly"}, ] as const; const contentClassName = "group flex w-full items-start gap-3 rounded-xl border border-success/10 bg-success-soft/30 px-4 py-3 transition-colors data-[focus-visible=true]:ring-2 data-[focus-visible=true]:ring-success/15 data-[hovered=true]:bg-success-soft-hover data-[selected=true]:border-success/30 data-[selected=true]:bg-success-soft data-[selected=true]:data-[hovered=true]:bg-success-soft-hover"; const controlClassName = "mt-0.5 size-5 shrink-0 rounded-full border border-border bg-default shadow-none group-data-[pressed=true]:scale-95 group-data-[selected=true]:border-transparent group-data-[selected=true]:bg-success group-data-[selected=true]:group-data-[pressed=true]:bg-success-hover"; const indicatorClassName = "before:rounded-full before:bg-default group-data-[selected=true]:before:scale-50 group-data-[selected=true]:before:bg-success-foreground group-data-[selected=true]:group-data-[pressed=true]:before:scale-[0.57]"; export function CustomStyles() { return ( <RadioGroup className="w-full max-w-sm gap-3 **:data-[slot=radio]:mt-0" defaultValue="yearly" name="billing" variant="secondary" > <Label className="font-medium text-foreground">Billing cycle</Label> <Description>Choose how often you are charged.</Description> {options.map(({description, label, value}) => ( <Radio key={value} value={value}> <Radio.Content className={contentClassName}> <Radio.Control className={controlClassName}> <Radio.Indicator className={indicatorClassName} /> </Radio.Control> <div className="flex flex-col gap-0.5"> <span className="font-medium text-foreground group-data-[selected=true]:text-success-soft-foreground"> {label} </span> <Description className="group-data-[selected=true]:text-success-soft-foreground/80"> {description} </Description> </div> </Radio.Content> </Radio> ))} </RadioGroup> ); } ``` ### Global CSS To customize the RadioGroup component classes, you can use the `@layer components` directive. [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-accent; } .radio__indicator { @apply bg-primary; } .radio__content { @apply gap-1; } } ``` ## Styling Reference 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 \[!toc] * `.radio-group` - Base radio group container * `.radio` - Individual radio item * `.radio__content` - Radio button (RAC label wrapper for control + label text) * `.radio__control` - Radio control (circular button) * `.radio__indicator` - Radio indicator (inner dot) #### Modifier Classes \[!toc] Disabled state is applied via `[data-disabled="true"]` / `[aria-disabled="true"]` (and `:disabled`) on `.radio` — there is no `.radio--disabled` modifier class. ### 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 | 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 | 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: RadioFieldRenderProps) => React.ReactNode` | - | Radio content or field render prop | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, RadioFieldRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### Radio.Control Extends `React.HTMLAttributes<HTMLSpanElement>`. | Prop | Type | Default | Description | | ---------- | ----------------- | ------- | ---------------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | The content to render inside the control wrapper (typically Radio.Indicator) | ### Radio.Indicator Extends `React.HTMLAttributes<HTMLSpanElement>`. | Prop | Type | Default | Description | | ---------- | ------------------------------------------------------------------------ | ------- | ----------------------------------------------------------------------------- | | `children` | `React.ReactNode \| (values: RadioButtonRenderProps) => React.ReactNode` | - | Optional content or render prop that receives the current radio button state. | ### Radio.Content The clickable area of the radio (the `<label>` wrapping the hidden input). Place `Radio.Control` and the `Label` inside it. `className` accepts a render function that receives `RadioButtonRenderProps`. | Prop | Type | Default | Description | | ---------- | ------------------------------------------------------------------------ | ------- | --------------------------------------------------------- | | `children` | `React.ReactNode \| (values: RadioButtonRenderProps) => React.ReactNode` | - | The clickable content (typically Radio.Control and Label) | ### RadioFieldRenderProps When using a render prop on the root `Radio`, these field-level values are provided: | Prop | Type | Description | | ------------ | --------- | ---------------------------------------- | | `isSelected` | `boolean` | Whether the radio is currently selected | | `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 | | `isRequired` | `boolean` | Whether the radio is required | ### RadioButtonRenderProps `Radio.Control` and `Radio.Indicator` use button-level render props (`isHovered`, `isPressed`, `isFocusVisible`, etc.). Pass a function as `Radio.Control` children or to `Radio.Indicator` to access them. ## Related Showcases ## Related Components ## Related Components * **Fieldset**: Group related form controls with legends * **Surface**: Base container surface * **Description**: Helper text for form fields </page> <page url="/en/docs/react/components/search-field"> # SearchField **Category**: react **URL**: https://heroui.com/en/docs/react/components/search-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/search-field.mdx > Search input field with clear button and search icon ## Usage ```tsx import { SearchField } from '@heroui/react'; ``` ```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. ## Examples ### 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/react/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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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.SyntheticEvent<HTMLFormElement>) => { 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 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> ); } ``` ### 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> ); } ``` ### Render Function ```tsx "use client"; import {Label, SearchField} from "@heroui/react"; export function RenderFunction() { 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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Label, SearchField} from "@heroui/react"; export function CustomStyles() { return ( <SearchField className="w-full max-w-64" name="docs" variant="secondary"> <Label className="font-medium text-foreground">Search docs</Label> <SearchField.Group className="rounded-xl bg-default"> <SearchField.SearchIcon className="text-muted" /> <SearchField.Input className="placeholder:text-muted" placeholder="Components, guides..." /> <SearchField.ClearButton className="text-muted" /> </SearchField.Group> </SearchField> ); } ``` ### Global CSS 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; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes #### Base Classes \[!toc] * `.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 #### Variant Classes \[!toc] * `.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/react/components/label), [Description](/docs/react/components/description), [FieldError](/docs/react/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 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). | ### Render Props 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. | ## Related Showcases ## Related Components ## Related Components * **Label**: Accessible label for form controls * **Description**: Helper text for form fields * **FieldError**: Inline validation messages for form fields </page> <page url="/en/docs/react/components/text-area"> # TextArea **Category**: react **URL**: https://heroui.com/en/docs/react/components/text-area **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/text-area.mdx > Primitive multiline text input component that accepts standard HTML attributes ## Usage ```tsx import { TextArea } from '@heroui/react'; ``` ```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..." /> ); } ``` <Callout> For validation, labels, and error messages, see **[TextField](/docs/react/components/text-field)**. </Callout> ## Examples ### 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/react/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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {TextArea} from "@heroui/react"; const fieldClass = "rounded-xl border border-border/80 bg-surface shadow-sm ring-1 ring-black/5 transition-[box-shadow,border-color] focus-visible:ring-2 focus-visible:ring-neutral-400/25 dark:ring-white/10 dark:focus-visible:ring-neutral-500/30"; export function CustomStyles() { return ( <TextArea aria-label="Notes" className={`h-28 w-full max-w-xs text-sm text-neutral-800 placeholder:text-neutral-400 dark:text-neutral-100 dark:placeholder:text-neutral-500 ${fieldClass}`} placeholder="Add a note..." /> ); } ``` ### Global CSS Override the shared `.textarea` class once with Tailwind's `@layer components`. ```css @layer components { .textarea { @apply rounded-xl border border-border bg-surface 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-accent ring-2 ring-accent/20; } &[data-invalid="true"] { @apply border-danger bg-danger-soft text-danger; } } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes #### Base Classes \[!toc] * `.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 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/react/components/text-field)** with TextArea as a child component. ## Related Showcases ## Related Components ## 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 </page> <page url="/en/docs/react/components/text-field"> # TextField **Category**: react **URL**: https://heroui.com/en/docs/react/components/text-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(forms)/text-field.mdx > Composition-friendly text fields with labels, descriptions, and inline validation ## Usage ```tsx import { TextField } from '@heroui/react'; ``` ```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/react/components/input)** or **[TextArea](/docs/react/components/text-area)**. ## Examples ### In Surface When used inside a [Surface](/docs/react/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> ); } ``` ### 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> ); } ``` ### 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" value="USR-12345"> <Label>Account ID</Label> <Input placeholder="Auto-generated" /> <Description>This field cannot be edited</Description> </TextField> ); } ``` ### 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> ); } ``` ### 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" value={username} onChange={setUsername} > <Label>Username</Label> <Input placeholder="jane_doe" /> {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" value={bio} onChange={setBio}> <Label>Bio</Label> <TextArea placeholder="Tell us about yourself..." /> {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" value={name} onChange={setName}> <Label>Display name</Label> <Input placeholder="Jane" /> <Description>Characters: {name.length}</Description> </TextField> <TextField name="bio" value={bio} onChange={setBio}> <Label>Bio</Label> <TextArea placeholder="Tell us about yourself..." /> <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> ); } ``` ### TextArea Use [TextArea](/docs/react/components/text-area) instead of [Input](/docs/react/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> ); } ``` ### Render Function ```tsx "use client"; import {Input, Label, TextField} from "@heroui/react"; export function RenderFunction() { 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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Input, Label, TextField} from "@heroui/react"; const fieldClass = "rounded-xl border border-border/80 bg-surface shadow-sm ring-1 ring-black/5 transition-[box-shadow,border-color] focus-visible:ring-2 focus-visible:ring-neutral-400/25 dark:ring-white/10 dark:focus-visible:ring-neutral-500/30"; export function CustomStyles() { return ( <TextField className="w-full max-w-64 gap-1.5" name="email" type="email"> <Label className="font-medium text-neutral-800 dark:text-neutral-100">Email</Label> <Input className={`text-sm text-neutral-800 placeholder:text-neutral-400 dark:text-neutral-100 dark:placeholder:text-neutral-500 ${fieldClass}`} placeholder="you@email.com" /> </TextField> ); } ``` ### Global CSS 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; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes * `.textfield` – Root container with minimal styling (`flex flex-col gap-1`) > **Note:** Child components ([Label](/docs/react/components/label), [Input](/docs/react/components/input), [TextArea](/docs/react/components/text-area), [Description](/docs/react/components/description), [FieldError](/docs/react/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 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> ``` ### Render Props 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). | ## Related Showcases ## Related Components ## 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 </page> <page url="/en/docs/react/components/card"> # Card **Category**: react **URL**: https://heroui.com/en/docs/react/components/card **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(layout)/card.mdx > Flexible container component for grouping related content and actions ## Usage ```tsx import { Card } from "@heroui/react"; ``` ```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 ```tsx import { Card } from "@heroui/react"; export default () => ( <Card> <Card.Header> <Card.Title /> <Card.Description /> </Card.Header> <Card.Content /> <Card.Footer /> </Card> ); ``` ## Examples ### 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="pe-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 end-3 top-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="pe-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 end-3 top-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 end-3 top-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="pe-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.SyntheticEvent<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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Check, Star} from "@gravity-ui/icons"; import {Button, Card} from "@heroui/react"; const PRO_FEATURES = [ "Unlimited projects and collaborators", "Priority support with 24h response", "Advanced analytics and exports", ] as const; export function CustomStyles() { return ( <Card className="relative w-full max-w-md overflow-hidden border border-accent/20 bg-linear-to-br from-accent/12 via-surface to-surface-secondary shadow-lg shadow-accent/10 dark:border-accent/30 dark:from-accent/20 dark:via-surface dark:to-accent/8 dark:shadow-accent/5"> <div aria-hidden="true" className="pointer-events-none absolute -top-12 -right-12 size-40 rounded-full bg-accent/20 blur-3xl dark:bg-accent/30" /> <div aria-hidden="true" className="pointer-events-none absolute -bottom-8 -left-8 size-28 rounded-full bg-accent/10 blur-2xl dark:bg-accent/20" /> <Card.Header className="relative gap-3"> <span className="w-fit rounded-full bg-accent/15 px-2.5 py-0.5 text-xs font-medium tracking-wide text-accent dark:bg-accent/25 dark:text-accent-soft-foreground"> Recommended </span> <div className="flex items-start gap-3"> <div className="flex size-10 shrink-0 items-center justify-center rounded-xl bg-accent/15 text-accent dark:bg-accent/20 dark:text-accent-soft-foreground"> <Star aria-hidden="true" className="size-5" /> </div> <div className="flex flex-col gap-1"> <Card.Title>Upgrade to Pro</Card.Title> <Card.Description> Unlock team workflows and insights built for growing products. </Card.Description> </div> </div> </Card.Header> <Card.Content className="relative"> <ul className="flex flex-col gap-2"> {PRO_FEATURES.map((feature) => ( <li key={feature} className="flex items-center gap-2 text-sm text-muted"> <Check aria-hidden="true" className="size-4 shrink-0 text-accent" /> {feature} </li> ))} </ul> </Card.Content> <Card.Footer className="relative flex-col gap-2 sm:flex-row"> <Button className="w-full shadow-md shadow-accent/20">Upgrade now</Button> <Button className="w-full" variant="secondary"> Compare plans </Button> </Card.Footer> </Card> ); } ``` ### Global CSS To customize the Card component classes, you can use the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .card--secondary { @apply bg-gradient-to-br from-blue-50 to-purple-50; } .card__title { @apply text-xl font-bold; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### 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 \[!toc] * `.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 \[!toc] * `.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 | ## 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 ## Related Components * **Surface**: Base container surface * **Avatar**: Display user profile images * **Form**: Form validation and submission handling </page> <page url="/en/docs/react/components/separator"> # Separator **Category**: react **URL**: https://heroui.com/en/docs/react/components/separator **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(layout)/separator.mdx > Visually divide content sections ## Usage ```tsx import { Separator } from '@heroui/react'; ``` ```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> ); } ``` ## Examples ### 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> ); } ``` ### 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> ); } ``` ### Decorative Use `isDecorative` when the divider is purely visual, such as between listbox sections. It renders an `aria-hidden` div by default with presentational semantics, while preserving its visual styles. Custom render functions receive the decorative props and ref. ```tsx <Separator isDecorative /> ``` ### Render Function ```tsx "use client"; import {Separator} from "@heroui/react"; export function RenderFunction() { 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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Separator} from "@heroui/react"; export function CustomStyles() { return ( <div className="max-w-xs space-y-4"> <p className="text-sm font-medium text-foreground">Account settings</p> <Separator className="bg-separator-secondary" /> <div className="flex items-center gap-3 text-sm text-muted"> <span>Profile</span> <Separator className="h-4 bg-separator" orientation="vertical" /> <span>Billing</span> <Separator className="h-4 bg-separator" orientation="vertical" /> <span>Security</span> </div> </div> ); } ``` ### Global CSS To customize the Separator component classes, you can use the `@layer components` directive. [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]; } } ``` ## Styling Reference 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 \[!toc] * `.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 \[!toc] * `.separator--default` - Default variant with standard contrast * `.separator--secondary` - Secondary variant with medium contrast * `.separator--tertiary` - Tertiary variant with subtle contrast ## API Reference ### Separator | Prop | Type | Default | Description | | -------------- | ----------------------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------- | | `isDecorative` | `boolean` | `false` | Hides a purely visual divider from assistive technology and removes separator semantics | | `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. | ## Related Components ## Related Components * **Card**: Content container with header, body, and footer * **Chip**: Compact elements for tags and filters * **Avatar**: Display user profile images </page> <page url="/en/docs/react/components/surface"> # Surface **Category**: react **URL**: https://heroui.com/en/docs/react/components/surface **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(layout)/surface.mdx > Container component that provides surface-level styling and context for child components ## Usage ```tsx import { Surface } from '@heroui/react'; ``` ```tsx import {Surface} from "@heroui/react"; export function Basic() { return ( <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> ); } ``` ## Examples ### 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) ```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> ); } ``` ### 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 "use client"; import {Input, Surface, TextArea} from "@heroui/react"; export function WithFormComponents() { return ( <Surface className="flex min-w-[320px] flex-col gap-4 rounded-3xl p-6" variant="default"> <Input placeholder="Input with secondary variant" variant="secondary" /> <TextArea placeholder="TextArea with secondary variant" variant="secondary" /> </Surface> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Surface} from "@heroui/react"; export function CustomStyles() { return ( <Surface className="w-full max-w-sm rounded-xl border border-accent/15 bg-linear-to-br from-accent/8 via-surface to-surface-secondary p-4" variant="default" > <h3 className="text-sm font-semibold text-foreground">Billing overview</h3> <p className="text-sm text-muted">View invoices and payment methods in one place.</p> </Surface> ); } ``` ### Global CSS To customize the Surface component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.surface` - Base surface container #### Variant Classes \[!toc] * `.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 | 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 } ``` ## Related Components ## Related Components * **CheckboxGroup**: Group of checkboxes with shared state * **Fieldset**: Group related form controls with legends * **InputOTP**: One-time password input </page> <page url="/en/docs/react/components/toolbar"> # Toolbar **Category**: react **URL**: https://heroui.com/en/docs/react/components/toolbar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(layout)/toolbar.mdx > A container for interactive controls with arrow key navigation. ## Usage ```tsx import { Toolbar } from '@heroui/react'; ``` ```tsx import {Bold, Copy, Italic, Scissors, Underline} from "@gravity-ui/icons"; import { Button, ButtonGroup, Separator, ToggleButton, ToggleButtonGroup, Toolbar, } from "@heroui/react"; export function Basic() { return ( <Toolbar aria-label="Text formatting"> <ToggleButtonGroup aria-label="Text style" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="Bold" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="Italic" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="Underline" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> <Separator /> <ButtonGroup variant="tertiary"> <Button isIconOnly aria-label="Copy"> <Copy /> </Button> <Button isIconOnly aria-label="Cut"> <ButtonGroup.Separator /> <Scissors /> </Button> </ButtonGroup> </Toolbar> ); } ``` ## Examples ### Vertical ```tsx import {ArrowUturnCcwLeft, ArrowUturnCwRight, Bold, Italic, Underline} from "@gravity-ui/icons"; import { Button, ButtonGroup, Separator, ToggleButton, ToggleButtonGroup, Toolbar, } from "@heroui/react"; export function Vertical() { return ( <Toolbar aria-label="Tools" orientation="vertical"> <ToggleButtonGroup aria-label="Text style" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="Bold" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="Italic" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="Underline" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> <Separator /> <ButtonGroup variant="tertiary"> <Button isIconOnly aria-label="Undo"> <ArrowUturnCcwLeft /> </Button> <Button isIconOnly aria-label="Redo"> <ButtonGroup.Separator /> <ArrowUturnCwRight /> </Button> </ButtonGroup> </Toolbar> ); } ``` ### Attached ```tsx import {Bold, Copy, Italic, Scissors, Underline} from "@gravity-ui/icons"; import { Button, ButtonGroup, Separator, ToggleButton, ToggleButtonGroup, Toolbar, } from "@heroui/react"; export function Attached() { return ( <Toolbar isAttached aria-label="Text formatting"> <ToggleButtonGroup aria-label="Text style" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="Bold" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="Italic" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="Underline" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> <Separator /> <ButtonGroup variant="tertiary"> <Button isIconOnly aria-label="Copy"> <Copy /> </Button> <Button isIconOnly aria-label="Cut"> <ButtonGroup.Separator /> <Scissors /> </Button> </ButtonGroup> </Toolbar> ); } ``` ### With ButtonGroup ```tsx import { ArrowUturnCcwLeft, ArrowUturnCwRight, Bold, Italic, TextAlignCenter, TextAlignLeft, TextAlignRight, Underline, } from "@gravity-ui/icons"; import { Button, ButtonGroup, Separator, ToggleButton, ToggleButtonGroup, Toolbar, } from "@heroui/react"; export function WithButtonGroup() { return ( <Toolbar aria-label="Editor toolbar"> <ButtonGroup variant="tertiary"> <Button> <ArrowUturnCcwLeft /> Undo </Button> <Button> <ButtonGroup.Separator /> <ArrowUturnCwRight /> Redo </Button> </ButtonGroup> <Separator /> <ToggleButtonGroup aria-label="Text style" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="Bold" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="Italic" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="Underline" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> <Separator /> <ButtonGroup variant="tertiary"> <Button isIconOnly aria-label="Align left"> <TextAlignLeft /> </Button> <Button isIconOnly aria-label="Align center"> <ButtonGroup.Separator /> <TextAlignCenter /> </Button> <Button isIconOnly aria-label="Align right"> <ButtonGroup.Separator /> <TextAlignRight /> </Button> </ButtonGroup> </Toolbar> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Bold, Italic, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup, Toolbar} from "@heroui/react"; const toggleClass = "rounded-lg data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground"; export function CustomStyles() { return ( <Toolbar aria-label="Formatting toolbar" className="gap-1 rounded-xl border border-border/80 bg-surface-secondary p-1.5" > <ToggleButtonGroup aria-label="Text style" className="gap-0.5" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="Bold" className={toggleClass} id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="Italic" className={toggleClass} id="italic"> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="Underline" className={toggleClass} id="underline"> <Underline /> </ToggleButton> </ToggleButtonGroup> </Toolbar> ); } ``` ### Global CSS To customize the Toolbar component classes, you can use the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .toolbar { @apply gap-4 rounded-lg bg-surface p-3; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Toolbar component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toolbar.css)): * `.toolbar` - Base container * `.toolbar--horizontal` - Horizontal orientation (default) * `.toolbar--vertical` - Vertical orientation * `.toolbar--attached` - Attached variant with surface background and full rounding ## API Reference ### Toolbar Inherits from [React Aria Toolbar](https://react-spectrum.adobe.com/react-aria/Toolbar.html). | Prop | Type | Default | Description | | ----------------- | -------------------------------------------------------------------- | -------------- | --------------------------------------------------------------- | | `isAttached` | `boolean` | `false` | Whether the toolbar has a surface background with full rounding | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | The orientation of the toolbar | | `aria-label` | `string` | - | An accessible label for the toolbar | | `aria-labelledby` | `string` | - | The id of an element that labels the toolbar | | `children` | `React.ReactNode \| (values: ToolbarRenderProps) => React.ReactNode` | - | Content or render prop | | `className` | `string \| (values: ToolbarRenderProps) => string` | - | Additional CSS classes | ### Render Props When using the render prop pattern, these values are provided: | Prop | Type | Description | | ------------- | ---------------------------- | -------------------------------------- | | `orientation` | `"horizontal" \| "vertical"` | The current orientation of the toolbar | ## Related Components ## Related Components * **ButtonGroup**: Group related buttons together * **ToggleButtonGroup**: Group multiple toggle buttons into a unified control * **Separator**: Visual divider between content </page> <page url="/en/docs/react/components/avatar-group"> # AvatarGroup **Category**: react **URL**: https://heroui.com/en/docs/react/components/avatar-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(media)/avatar-group.mdx > Display a stacked or grid group of avatars with overflow counting ## Usage ```tsx import { AvatarGroup, Avatar } from '@heroui/react'; ``` ```tsx import {Avatar, AvatarGroup} 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 Basic() { return ( <AvatarGroup> {users.slice(0, 4).map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={user.name} src={user.image} /> <Avatar.Fallback> {user.name .split(" ") .map((n) => n[0]) .join("")} </Avatar.Fallback> </Avatar> ))} </AvatarGroup> ); } ``` ## Anatomy ```tsx import { AvatarGroup, Avatar } from '@heroui/react'; export default () => ( <AvatarGroup> <Avatar> <Avatar.Image /> <Avatar.Fallback /> </Avatar> <AvatarGroup.Count /> {/* Optional explicit child */} </AvatarGroup> ); ``` ## Examples ### Max ```tsx import {Avatar, AvatarGroup} 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 Max() { return ( <AvatarGroup max={3}> {users.map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={user.name} src={user.image} /> <Avatar.Fallback> {user.name .split(" ") .map((n) => n[0]) .join("")} </Avatar.Fallback> </Avatar> ))} </AvatarGroup> ); } ``` ### With Count ```tsx import {Avatar, AvatarGroup} 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 Count() { const total = 12; return ( <AvatarGroup size="sm"> {users.slice(0, 3).map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={user.name} src={user.image} /> <Avatar.Fallback> {user.name .split(" ") .map((n) => n[0]) .join("")} </Avatar.Fallback> </Avatar> ))} <AvatarGroup.Count>+{total - 3}</AvatarGroup.Count> </AvatarGroup> ); } ``` ### Sizes ```tsx import {Avatar, AvatarGroup} 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 Sizes() { return ( <div className="flex flex-col items-center gap-6"> <div className="flex flex-col items-center gap-2"> <p className="text-sm text-muted">Small</p> <AvatarGroup size="sm"> {users.slice(0, 4).map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={user.name} src={user.image} /> <Avatar.Fallback> {user.name .split(" ") .map((n) => n[0]) .join("")} </Avatar.Fallback> </Avatar> ))} </AvatarGroup> </div> <div className="flex flex-col items-center gap-2"> <p className="text-sm text-muted">Medium (default)</p> <AvatarGroup size="md"> {users.slice(0, 4).map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={user.name} src={user.image} /> <Avatar.Fallback> {user.name .split(" ") .map((n) => n[0]) .join("")} </Avatar.Fallback> </Avatar> ))} </AvatarGroup> </div> <div className="flex flex-col items-center gap-2"> <p className="text-sm text-muted">Large</p> <AvatarGroup size="lg"> {users.slice(0, 4).map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={user.name} src={user.image} /> <Avatar.Fallback> {user.name .split(" ") .map((n) => n[0]) .join("")} </Avatar.Fallback> </Avatar> ))} </AvatarGroup> </div> </div> ); } ``` ### Grid ```tsx import {Avatar, AvatarGroup} 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 Grid() { return ( <AvatarGroup isGrid max={5}> {users.map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={user.name} src={user.image} /> <Avatar.Fallback> {user.name .split(" ") .map((n) => n[0]) .join("")} </Avatar.Fallback> </Avatar> ))} </AvatarGroup> ); } ``` ### Overlap ```tsx import type {ReactNode} from "react"; import {Avatar, AvatarGroup} from "@heroui/react"; const STRIPE_STYLES = ` @keyframes ag-stripes { to { background-position: 24px 24px; } } .ag-stripes { background-color: color-mix(in oklab, var(--danger) 6%, var(--surface)); background-image: repeating-linear-gradient( -45deg, transparent 0 10px, color-mix(in oklab, var(--danger) 12%, transparent) 10px 11px, transparent 11px 21px, color-mix(in oklab, var(--danger) 28%, transparent) 21px 22px ); background-size: 24px 24px; animation: ag-stripes 2.8s linear infinite; } `; function StripeBackdrop({children}: {children: ReactNode}) { return ( <div className="relative inline-flex rounded-xl p-6"> <div aria-hidden className="ag-stripes pointer-events-none absolute inset-0 rounded-xl" /> <div className="relative z-10">{children}</div> </div> ); } function DemoGroup({overlap}: {overlap: "clip" | "ring"}) { return ( <AvatarGroup overlap={overlap} size="lg"> <Avatar> <Avatar.Image alt="John" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Avatar> <Avatar.Fallback>AB</Avatar.Fallback> </Avatar> <Avatar> <Avatar.Image alt="Emily" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" /> <Avatar.Fallback>EC</Avatar.Fallback> </Avatar> <Avatar> <Avatar.Fallback>SM</Avatar.Fallback> </Avatar> <AvatarGroup.Count>+2</AvatarGroup.Count> </AvatarGroup> ); } export function Overlap() { return ( <div className="flex flex-col items-start gap-6"> <style>{STRIPE_STYLES}</style> <div className="flex flex-col gap-2"> <p className="text-sm text-muted">clip</p> <StripeBackdrop> <DemoGroup overlap="clip" /> </StripeBackdrop> </div> <div className="flex flex-col gap-2"> <p className="text-sm text-muted">ring</p> <StripeBackdrop> <DemoGroup overlap="ring" /> </StripeBackdrop> </div> </div> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Person} from "@gravity-ui/icons"; import {Avatar, AvatarGroup} from "@heroui/react"; const assignees = [ { 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", }, ] as const; export function CustomStyles() { return ( <div className="inline-flex items-center gap-2.5 rounded-full border border-border/70 bg-surface/95 py-1 pr-3 pl-1 shadow-sm ring-1 ring-black/[0.04] dark:border-border/80 dark:bg-surface/90 dark:ring-white/10"> <AvatarGroup aria-label="Assignees" className="[--avatar-group-overlap:0.7rem] [--avatar-group-seam:2px]" overlap="clip" role="group" size="sm" > {assignees.map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={user.name} src={user.image} /> <Avatar.Fallback> {user.name .split(" ") .map((part) => part[0]) .join("")} </Avatar.Fallback> </Avatar> ))} <Avatar> <Avatar.Fallback> <Person className="size-4 shrink-0" /> </Avatar.Fallback> </Avatar> <AvatarGroup.Count>+3</AvatarGroup.Count> </AvatarGroup> <span className="text-sm font-medium text-foreground">Assignees</span> </div> ); } ``` ### Global CSS To customize the AvatarGroup component classes, you can use the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .avatar-group { --avatar-group-overlap: 0.75rem; --avatar-group-seam: 2px; } .avatar-group__count { @apply font-semibold; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The AvatarGroup component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/avatar-group.css)): #### Base Classes \[!toc] * `.avatar-group` - Base avatar group container * `.avatar-group--grid` - Grid layout modifier (no overlap) * `.avatar-group--clip` - Transparent seam tracing the next avatar's outline (default stacked overlap) * `.avatar-group--ring` - Solid box-shadow outline via `--background` * `.avatar-group__count` - Overflow count avatar Stacked layout uses negative margin between siblings (`--avatar-group-overlap`, default `0.5rem`). Clip mode masks overlapped avatars (not the last child / Count) and optically nudges fallback glyphs; the seam follows the avatar's own `--avatar-radius`, so a themed `--radius` reshapes avatars and seams together. Ring mode uses a thin box-shadow outline via `--background`. ## API Reference ### AvatarGroup | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size applied to child Avatars (and the overflow count) when they omit `size` (synced with Avatar) | | `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | Color applied to child Avatars (and the overflow count) when they omit `color` | | `variant` | `'default' \| 'soft'` | - | Variant applied to child Avatars (and the overflow count) when they omit `variant` | | `max` | `number` | - | Maximum number of avatar children to render; omit to show all | | `isGrid` | `boolean` | `false` | Whether to use a wrapping grid layout without overlap | | `overlap` | `'clip' \| 'ring'` | `'clip'` | Stacked overlap style: transparent seam (default) or box-shadow ring; ignored when `isGrid` | | `className` | `string` | - | Additional CSS classes | | `children` | `React.ReactNode` | - | Avatar components (and optional `AvatarGroup.Count`) to group together | ### AvatarGroup.Count Composes `Avatar` + `Avatar.Fallback` for the overflow indicator. Not truncated by `max`. | Prop | Type | Default | Description | | ----------- | ------------------------------------------------------------- | ------- | ------------------------------- | | `children` | `React.ReactNode` | - | Count content (e.g. `+3`) | | `size` | `'sm' \| 'md' \| 'lg'` | - | Override size from the group | | `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | Override color from the group | | `variant` | `'default' \| 'soft'` | - | Override variant from the group | | `className` | `string` | - | Additional CSS classes | ## Note * AvatarGroup uses React Context to pass `size`, `color`, and `variant` to **direct Avatar children only** * `max` truncates visible avatars when set and auto-counts remaining children; omit to show all * For a known total (e.g. from the server), render an explicit `AvatarGroup.Count` — it is not truncated by `max` and suppresses the auto count. Prefer `Count` over the removed v2 `total` prop * `isGrid` disables overlap and uses a wrapping grid layout instead * `overlap` defaults to `"clip"` (transparent seam); use `"ring"` for the solid outline; no effect with `isGrid` * No default `role="group"` — when the stack is meaningful (assignees, viewers), pass `role="group"` with `aria-label` or `aria-labelledby` ## Related Components ## Related Components * **Avatar**: Display user profile images * **Badge**: Small indicator positioned relative to another element * **Chip**: Compact elements for tags and filters </page> <page url="/en/docs/react/components/avatar"> # Avatar **Category**: react **URL**: https://heroui.com/en/docs/react/components/avatar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(media)/avatar.mdx > Display user profile images with customizable fallback content ## Usage ```tsx import { Avatar } from '@heroui/react'; ``` ```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 ```tsx import { Avatar } from '@heroui/react'; export default () => ( <Avatar> <Avatar.Image/> <Avatar.Fallback/> </Avatar> ) ``` ## Examples ### 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> ); } ``` ## Customization ### Custom Image Component Use `asChild` on `Avatar.Image` to compose with a custom image component. This example uses Next.js `Image` for optimized loading. Pass `src` on `Avatar.Image` so it can track the loading state and show the fallback until the image is ready. ```tsx import {Avatar} from "@heroui/react"; import Image from "next/image"; const SRC = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"; export function CustomImageComponent() { return ( <Avatar> <Avatar.Image asChild height={40} src={SRC} width={40}> <Image alt="John Doe" src={SRC} /> </Avatar.Image> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> ); } ``` ### Tailwind CSS ```tsx import {Avatar} from "@heroui/react"; export function CustomStyles() { return ( <Avatar className="rounded-lg"> <Avatar.Image alt="John Doe" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3" /> <Avatar.Fallback className="rounded-lg">JD</Avatar.Fallback> </Avatar> ); } ``` ### Global CSS To customize the Avatar component classes, you can use the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .avatar { @apply size-16 border-2 border-accent; } .avatar__fallback { @apply bg-gradient-to-br from-purple-500 to-pink-500; } } ``` ## Styling Reference 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 \[!toc] * `.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 \[!toc] * `.avatar--sm` - Small avatar (size-8) * `.avatar--md` - Medium avatar (default, no additional styles) * `.avatar--lg` - Large avatar (size-12) #### Variant Modifiers \[!toc] * `.avatar--soft` - Soft variant with lighter background #### Color Modifiers \[!toc] * `.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 | 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 | 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 | | `asChild` | `boolean` | `false` | Merge props onto the child element (e.g. `next/image`) instead of rendering a native `img` | | `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 | 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 | ## Related Components ## Related Components * **AvatarGroup**: Display a stacked or grid group of avatars * **Separator**: Visual divider between content * **Badge**: Small indicator positioned relative to another element </page> <page url="/en/docs/react/components/accordion"> # Accordion **Category**: react **URL**: https://heroui.com/en/docs/react/components/accordion **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(navigation)/accordion.mdx > A collapsible content panel for organizing information in a compact space ## Usage ```tsx import { Accordion } from '@heroui/react'; ``` ```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="me-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 ```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> ) ``` ## Examples ### 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="me-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> ); } ``` ### 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="me-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> ); } ``` ### 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> ); } ``` ### Controlled ```tsx "use client"; import {ChevronDown, ChevronUp} from "@gravity-ui/icons"; import {Accordion, Button, useDisclosureGroupNavigation} from "@heroui/react"; import React from "react"; const items = [ { content: "Learn the basics of HeroUI and how to integrate it into your React project. This section covers installation, setup, and your first component.", id: "getting-started", title: "Getting Started", }, { content: "Understand the fundamental concepts behind HeroUI, including the compound component pattern, styling with Tailwind CSS, and accessibility features.", id: "core-concepts", title: "Core Concepts", }, { content: "Explore advanced features like custom variants, theme customization, and integration with other libraries in your React ecosystem.", id: "advanced-usage", title: "Advanced Usage", }, ]; export function Controlled() { const [expandedKeys, setExpandedKeys] = React.useState( new Set<string | number>(["getting-started"]), ); const itemIds = items.map((item) => item.id); const {isNextDisabled, isPrevDisabled, onNext, onPrevious} = useDisclosureGroupNavigation({ expandedKeys, itemIds, onExpandedChange: setExpandedKeys, }); return ( <div className="w-full max-w-md"> <div className="mb-4 flex items-center justify-between"> <p className="text-sm text-muted"> Expanded: <strong>{[...expandedKeys].join(", ") || "none"}</strong> </p> <div className="flex gap-2"> <Button aria-label="Previous item" isDisabled={isPrevDisabled} size="sm" variant="secondary" onPress={onPrevious} > <ChevronUp className="size-4" /> </Button> <Button aria-label="Next item" isDisabled={isNextDisabled} size="sm" variant="secondary" onPress={onNext} > <ChevronDown className="size-4" /> </Button> </div> </div> <Accordion expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}> {items.map((item) => ( <Accordion.Item key={item.id} id={item.id}> <Accordion.Heading> <Accordion.Trigger> {item.title} <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>{item.content}</Accordion.Body> </Accordion.Panel> </Accordion.Item> ))} </Accordion> </div> ); } ``` ### 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> ); } ``` ### 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 RenderFunction() { 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="me-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> ); } ``` ### 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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {ChevronDown} from "@gravity-ui/icons"; import {Accordion} 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 your 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="group/item first:**:data-[slot=accordion-trigger]:rounded-t-2xl last:[&:not(:has([data-slot=accordion-trigger][aria-expanded='true']))_[data-slot=accordion-trigger]]:rounded-b-2xl" > <Accordion.Heading> <Accordion.Trigger className="group flex items-center gap-2 transition-none hover:bg-surface"> {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> ); } ``` ### Global CSS To customize the Accordion component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.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 \[!toc] * `.accordion--outline` - Outline variant with border and background #### State Classes \[!toc] * `.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 | 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 | 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 | 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 | 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 | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom indicator icon | ### Accordion.Body | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Body content | ## Related Components ## Related Components * **DisclosureGroup**: Group of collapsible panels * **Disclosure**: Single collapsible content section </page> <page url="/en/docs/react/components/breadcrumbs"> # Breadcrumbs **Category**: react **URL**: https://heroui.com/en/docs/react/components/breadcrumbs **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(navigation)/breadcrumbs.mdx > Navigation breadcrumbs showing the current page's location within a hierarchy ## Usage ```tsx import { Breadcrumbs } from '@heroui/react'; ``` ```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 ```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> ) ``` ## Examples ### 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> ); } ``` ### 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 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> ); } ``` ### Render Function ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export function RenderFunction() { 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> ); } ``` ## Customization ### Tailwind CSS ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export function CustomStyles() { return ( <Breadcrumbs className="rounded-lg bg-default-soft px-3 py-2"> <Breadcrumbs.Item className="text-muted hover:text-accent" href="#"> Home </Breadcrumbs.Item> <Breadcrumbs.Item className="text-muted hover:text-accent" href="#"> Products </Breadcrumbs.Item> <Breadcrumbs.Item className="font-medium text-foreground">Laptop</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ### Global CSS To customize the Breadcrumbs component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.breadcrumbs` - Base breadcrumbs container * `.breadcrumbs__item` - Individual breadcrumb item wrapper * `.breadcrumbs__link` - Breadcrumb link element * `.breadcrumbs__separator` - Separator icon between items #### State Classes \[!toc] * `.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 | 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 | 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. ## Related Components ## Related Components * **Link**: Styled anchor links * **Separator**: Visual divider between content * **Tabs**: Organize content into tabbed views </page> <page url="/en/docs/react/components/disclosure-group"> # DisclosureGroup **Category**: react **URL**: https://heroui.com/en/docs/react/components/disclosure-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(navigation)/disclosure-group.mdx > Container that manages multiple Disclosure items with coordinated expanded states ## Usage ```tsx import { DisclosureGroup } from '@heroui/react'; ``` ```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 ```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> ) ``` ## Examples ### 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> ); } ``` ## Customization ### Tailwind CSS ```tsx "use client"; import {Button, Disclosure, DisclosureGroup, Separator} from "@heroui/react"; export function CustomStyles() { return ( <DisclosureGroup className="w-full max-w-sm rounded-xl bg-default-soft p-2"> <Disclosure id="billing"> <Disclosure.Heading> <Button className="w-full justify-between" slot="trigger" variant="ghost"> Billing <Disclosure.Indicator className="text-muted" /> </Button> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="text-sm text-muted"> Invoices are issued on the first of each month. </Disclosure.Body> </Disclosure.Content> </Disclosure> <Separator className="my-1" /> <Disclosure id="support"> <Disclosure.Heading> <Button className="w-full justify-between" slot="trigger" variant="ghost"> Support <Disclosure.Indicator className="text-muted" /> </Button> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="text-sm text-muted"> Reach us at help@heroui.com. Typical response time is under one business day. </Disclosure.Body> </Disclosure.Content> </Disclosure> </DisclosureGroup> ); } ``` ### Global CSS To customize the DisclosureGroup component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.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 | 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 | ### Render Props 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 | ## Related Showcases ## Related Components ## Related Components * **Accordion**: Collapsible content sections * **Disclosure**: Single collapsible content section * **Button**: Allows a user to perform an action </page> <page url="/en/docs/react/components/disclosure"> # Disclosure **Category**: react **URL**: https://heroui.com/en/docs/react/components/disclosure **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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. ## Usage ```tsx import { Disclosure } from '@heroui/react'; ``` ```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 ```tsx import { Disclosure } from '@heroui/react'; export default () => ( <Disclosure> <Disclosure.Heading> <Disclosure.Trigger> <Disclosure.Indicator /> </Disclosure.Trigger> </Disclosure.Heading> <Disclosure.Content/> </Disclosure> ) ``` ## Examples ### 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 RenderFunction() { 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> ); } ``` ## Customization ### Tailwind CSS ```tsx "use client"; import {ShoppingBag} from "@gravity-ui/icons"; import {Button, Disclosure} from "@heroui/react"; import {useState} from "react"; export function CustomStyles() { const [isExpanded, setIsExpanded] = useState(false); return ( <div className="w-full max-w-sm"> <Disclosure isExpanded={isExpanded} onExpandedChange={setIsExpanded}> <Disclosure.Heading> <Button className="w-full justify-between rounded-xl border border-border/70 bg-linear-to-b from-neutral-50/90 to-white px-4 py-3 font-medium text-foreground shadow-sm ring-1 ring-black/5 hover:bg-muted/30 dark:from-neutral-900/80 dark:to-neutral-900 dark:ring-white/10" slot="trigger" variant="ghost" > <span className="flex items-center gap-2"> <ShoppingBag className="size-4 text-muted" /> Shipping details </span> <Disclosure.Indicator className="text-muted" /> </Button> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="mt-2 rounded-xl border border-border/70 bg-surface/50 p-4 text-sm leading-relaxed text-muted dark:bg-neutral-900/50"> Orders ship within 2 business days. Standard delivery takes 3–5 days; express is available at checkout. </Disclosure.Body> </Disclosure.Content> </Disclosure> </div> ); } ``` ### Global CSS To customize the Disclosure component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.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 | 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 | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | ---------------------- | | `children` | `ReactNode \| RenderFunction` | - | Trigger content | | `className` | `string` | - | Additional CSS classes | ### DisclosureContent | 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. | ### Render Props When using the render prop pattern, these values are provided: | Prop | Type | Description | | ------------ | --------- | ------------------------------ | | `isExpanded` | `boolean` | Current expanded state | | `isDisabled` | `boolean` | Whether disclosure is disabled | ## Related Showcases ## Related Components ## Related Components * **Accordion**: Collapsible content sections * **DisclosureGroup**: Group of collapsible panels * **Button**: Allows a user to perform an action </page> <page url="/en/docs/react/components/link"> # Link **Category**: react **URL**: https://heroui.com/en/docs/react/components/link **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(navigation)/link.mdx > A styled anchor component for navigation with built-in icon support ## Usage ```tsx import { Link } from '@heroui/react'; ``` ```tsx import {Link} from "@heroui/react"; export function LinkBasic() { return ( <Link href="#"> Call to action <Link.Icon /> </Link> ); } ``` ## Anatomy ```tsx import { Link } from '@heroui/react'; export default () => ( <Link href="#"> Call to action <Link.Icon /> </Link> ); ``` ## Examples ### 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 Link is underlined on hover by default. Use Tailwind CSS text-decoration utilities to make the underline always visible, remove it entirely, or customize its color, style, thickness, and offset. ```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">Default hover underline</p> <Link 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">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">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" href="#"> Offset 1 (1px space) <Link.Icon /> </Link> <Link className="underline-offset-2" href="#"> Offset 2 (2px space) <Link.Icon /> </Link> <Link className="underline-offset-3" href="#"> Offset 3 (3px space) <Link.Icon /> </Link> <Link className="underline-offset-4" href="#"> Offset 4 (4px space) <Link.Icon /> </Link> </div> </div> </div> ); } ``` **Text Decoration Line:** * `underline` - Always visible underline * `no-underline` - Remove underline * default `Link` styles - Underline appears on hover **Text Decoration Color:** * `decoration-accent`, `decoration-muted`, 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` ### 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="ms-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> ); } ``` ### Render Function ```tsx "use client"; import {Link} from "@heroui/react"; export function RenderFunction() { return ( <Link href="#" render={(props) => <span {...props} data-custom="foo" />}> Call to action <Link.Icon /> </Link> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Link} from "@heroui/react"; export function CustomStyles() { return ( <Link className="font-medium text-neutral-700 underline decoration-neutral-300/80 underline-offset-4 transition-colors hover:text-neutral-900 dark:text-neutral-300 dark:decoration-neutral-600/80 dark:hover:text-neutral-100" href="#" > Call to action <Link.Icon /> </Link> ); } ``` ### Global CSS To customize the Link component classes, you can use the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .link { @apply font-semibold no-underline hover:underline; } } ``` ## Styling Reference 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 \[!toc] * `.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"]` * **Hover**: `:hover` or `[data-hovered="true"]` * **Pressed**: `:active` or `[data-pressed="true"]` * **Disabled**: `:disabled` or `[aria-disabled="true"]` ## API Reference ### Link | 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 | 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-accent underline-offset-4"> About Page <Link.Icon className="link__icon" /> </a> ); } ``` ## Related Components ## Related Components * **Breadcrumbs**: Display the user's current location within a hierarchy </page> <page url="/en/docs/react/components/pagination"> # Pagination **Category**: react **URL**: https://heroui.com/en/docs/react/components/pagination **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(navigation)/pagination.mdx > Page navigation with composable page links, previous/next buttons, and ellipsis indicators ## Usage ```tsx import { Pagination } from '@heroui/react'; ``` ```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 ```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> ); ``` ## Examples ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ## Customization ### Tailwind CSS ```tsx "use client"; import {Pagination} from "@heroui/react"; import {useState} from "react"; const linkClass = "text-muted hover:bg-surface hover:text-foreground"; const activeClass = "bg-accent text-accent-foreground hover:bg-accent-hover"; export function CustomStyles() { const [page, setPage] = useState(2); return ( <Pagination className="justify-center"> <Pagination.Content className="gap-1 rounded-xl bg-default p-1"> <Pagination.Item> <Pagination.Previous className={linkClass} isDisabled={page === 1} onPress={() => setPage((p) => p - 1)} > <Pagination.PreviousIcon /> </Pagination.Previous> </Pagination.Item> {[1, 2, 3].map((p) => ( <Pagination.Item key={p}> <Pagination.Link className={p === page ? activeClass : linkClass} isActive={p === page} onPress={() => setPage(p)} > {p} </Pagination.Link> </Pagination.Item> ))} <Pagination.Item> <Pagination.Next className={linkClass} isDisabled={page === 3} onPress={() => setPage((p) => p + 1)} > <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### Global CSS To customize the Pagination component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.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 \[!toc] * `.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 | 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 | Prop | Type | Default | Description | | ----------- | ----------- | ------- | --------------------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Summary content (e.g., "Showing 1-10 of 120") | ### Pagination.Content | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Pagination items | ### Pagination.Item | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Item content (Link, Previous, Next, or Ellipsis) | ### Pagination.Link | 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 | 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 | Prop | Type | Default | Description | | ----------- | ----------- | ------------------- | ------------------------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | Default chevron SVG | Custom icon to replace the default chevron | ### Pagination.Ellipsis | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | ## 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. ## 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` ## Related Components ## Related Components * **Button**: Allows a user to perform an action * **Link**: Styled anchor links </page> <page url="/en/docs/react/components/tabs"> # Tabs **Category**: react **URL**: https://heroui.com/en/docs/react/components/tabs **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(navigation)/tabs.mdx > Tabs organize content into multiple sections and allow users to navigate between them. ## Usage ```tsx import { Tabs } from '@heroui/react'; ``` ## Anatomy ```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> ) ``` ## Examples ### Vertical ### Overflow When the tab list exceeds the available space, `Tabs.ListContainer` automatically renders scroll chevrons and fading edges so users can navigate the hidden tabs. This works the same way for both horizontal and vertical orientations. ### Disabled Tab ### With Separator Add `<Tabs.Separator />` inside each `<Tabs.Tab>` (except the first) to display separator lines between tabs. ### Secondary Variant ### Secondary Variant Vertical ### Alignment Tab content is centered by default. Use `align` to align it to the `start` or `end` instead, which is especially useful for vertical, sidebar-style navigation. Individual tabs can still be overridden with `className` on `Tabs.Tab`. ### Render Function ```tsx "use client"; import {Tabs} from "@heroui/react"; import Link from "next/link"; export function RenderFunction() { 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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Tabs} from "@heroui/react"; const listClassName = [ "rounded-xl border border-accent/10 bg-accent-soft/30 p-1", "**:data-[slot=tabs-tab]:rounded-lg", "**:data-[slot=tabs-tab]:bg-transparent", "**:data-[slot=tabs-tab]:text-muted", "**:data-[slot=tabs-tab]:opacity-100", "**:data-[slot=tabs-tab]:transition-colors", "**:data-[slot=tabs-tab]:data-[hovered=true]:not-data-[selected=true]:bg-accent-soft", "**:data-[slot=tabs-tab]:data-[hovered=true]:not-data-[selected=true]:text-accent-soft-foreground", "**:data-[slot=tabs-tab]:data-[pressed=true]:not-data-[selected=true]:bg-accent-soft-hover", "**:data-[slot=tabs-tab]:data-[focus-visible=true]:ring-2", "**:data-[slot=tabs-tab]:data-[focus-visible=true]:ring-accent/15", "**:data-[slot=tabs-tab]:data-[selected=true]:font-medium", "**:data-[slot=tabs-tab]:data-[selected=true]:text-accent-foreground", "**:data-[slot=tabs-tab]:shadow-none", "**:data-[slot=tabs-indicator]:rounded-lg", "**:data-[slot=tabs-indicator]:bg-accent", "**:data-[slot=tabs-indicator]:shadow-none", ].join(" "); export function CustomStyles() { return ( <Tabs className="w-full max-w-sm"> <Tabs.ListContainer className="rounded-none bg-transparent"> <Tabs.List aria-label="Billing cycle" className={listClassName}> <Tabs.Tab id="monthly"> Monthly <Tabs.Indicator /> </Tabs.Tab> <Tabs.Tab id="yearly"> Yearly <Tabs.Indicator /> </Tabs.Tab> </Tabs.List> </Tabs.ListContainer> <Tabs.Panel className="pt-3 text-sm text-muted" id="monthly"> Billed monthly, cancel anytime. </Tabs.Panel> <Tabs.Panel className="pt-3 text-sm text-muted" id="yearly"> Save 20% with annual billing. </Tabs.Panel> </Tabs> ); } ``` ### Global CSS To customize the Tabs component classes, you can use the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .tabs__list { @apply rounded-xl border border-border bg-surface p-1; } .tabs__tab { @apply rounded-lg font-medium; } .tabs__indicator { @apply rounded-lg bg-foreground shadow-sm; } .tabs--secondary > .tabs__list-container > .tabs__list { @apply border-b border-border bg-transparent p-0; } .tabs--secondary > .tabs__list-container .tabs__indicator { @apply rounded-none bg-accent; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Tabs component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tabs.css)): #### Base Classes \[!toc] * `.tabs` - Base tabs container * `.tabs__list-container` - Tab list container wrapper * `.tabs__list-container__scroller` - Scrollable wrapper around the tab list (handles overflow and fading edges) * `.tabs__list-container__scroll-prev` - Scroll chevron button for the previous (left / up) direction * `.tabs__list-container__scroll-next` - Scroll chevron button for the next (right / down) direction * `.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 \[!toc] * `.tabs[data-orientation="horizontal"]` - Horizontal tab layout (default) * `.tabs[data-orientation="vertical"]` - Vertical tab layout #### Variant Classes \[!toc] * `.tabs--secondary` - Secondary variant with underline indicator #### Alignment Classes \[!toc] * `.tabs--align-start` - Aligns tab content to the start * `.tabs--align-end` - Aligns tab content to the end ### 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 | 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 | | `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment of the content inside each tab | | `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 | 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 | 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 | Prop | Type | Default | Description | | ----------- | -------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | ### Tabs.Panel | 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. | ## Related Showcases ## Related Components ## Related Components * **Breadcrumbs**: Display the user's current location within a hierarchy </page> <page url="/en/docs/react/components/alert-dialog"> # AlertDialog **Category**: react **URL**: https://heroui.com/en/docs/react/components/alert-dialog **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(overlays)/alert-dialog.mdx > Modal dialog for critical confirmations requiring user attention and explicit action ## Usage ```tsx import { AlertDialog } from "@heroui/react"; ``` ```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 ```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> ); ``` ## Examples ### 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> ); } ``` ### 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> ); } ``` ### 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 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 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ## Customization ### Tailwind CSS ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; export function CustomStyles() { return ( <AlertDialog> <Button variant="secondary">Sign out</Button> <AlertDialog.Backdrop className="bg-overlay/50 dark:bg-overlay/60" variant="blur"> <AlertDialog.Container> <AlertDialog.Dialog className="relative overflow-hidden border border-border/80 bg-surface shadow-2xl ring-1 ring-accent/10 sm:max-w-[400px] dark:border-border/90 dark:bg-surface dark:ring-accent/15"> <div aria-hidden="true" className="pointer-events-none absolute inset-x-0 top-0 h-24 bg-linear-to-b from-accent/6 to-transparent dark:from-accent/10" /> <div aria-hidden="true" className="pointer-events-none absolute inset-x-8 top-0 h-px bg-linear-to-r from-transparent via-accent/35 to-transparent dark:via-accent/45" /> <AlertDialog.Header className="relative"> <AlertDialog.Icon status="accent" /> <AlertDialog.Heading>Sign out of your account?</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body className="relative"> <p className="text-muted"> You will be signed out on this device. Unsaved work in{" "} <strong className="text-foreground">Acme Workspace</strong> may be lost unless it was saved to the cloud. </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> Stay signed in </Button> <Button slot="close">Sign out</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); } ``` ### Global CSS To customize the AlertDialog 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-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; } } ``` ## Styling Reference 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 \[!toc] * `.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 \[!toc] * `.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) \[!toc] * `.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) ## Related Components ## Related Components * **Button**: Allows a user to perform an action * **CloseButton**: Button for dismissing overlays </page> <page url="/en/docs/react/components/drawer"> # Drawer **Category**: react **URL**: https://heroui.com/en/docs/react/components/drawer **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(overlays)/drawer.mdx > Slide-out panel for supplementary content and actions ## Usage ```tsx import { Drawer, Button } from "@heroui/react"; ``` ```tsx import {Button, Drawer} from "@heroui/react"; export function Basic() { return ( <Drawer> <Button variant="secondary">Open Drawer</Button> <Drawer.Backdrop> <Drawer.Content placement="right"> <Drawer.Dialog> <Drawer.Header> <Drawer.Heading>Drawer Title</Drawer.Heading> </Drawer.Header> <Drawer.Body> <p> This is a bottom drawer built with React Aria's Modal component. It slides up from the bottom of the screen with a smooth CSS transition. </p> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Confirm</Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ## Anatomy ```tsx import { Drawer, Button } from "@heroui/react"; export default () => ( <Drawer> <Button>Open Drawer</Button> <Drawer.Backdrop> <Drawer.Content> <Drawer.Dialog> <Drawer.Handle /> {/* Optional: Drag handle */} <Drawer.CloseTrigger /> {/* Optional: Close button */} <Drawer.Header> <Drawer.Heading /> </Drawer.Header> <Drawer.Body /> <Drawer.Footer /> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); ``` ## Examples ### Placement ```tsx import {Button, Drawer} from "@heroui/react"; export function Placements() { const placements = ["bottom", "top", "left", "right"] as const; return ( <div className="flex flex-wrap gap-4"> {placements.map((placement) => ( <Drawer key={placement}> <Button variant="secondary"> {placement.charAt(0).toUpperCase() + placement.slice(1)} </Button> <Drawer.Backdrop> <Drawer.Content placement={placement}> <Drawer.Dialog> <Drawer.CloseTrigger /> {placement === "bottom" && <Drawer.Handle />} <Drawer.Header> <Drawer.Heading> {placement.charAt(0).toUpperCase() + placement.slice(1)} Drawer </Drawer.Heading> </Drawer.Header> <Drawer.Body> <p> This drawer slides in from the <strong>{placement}</strong> edge of the screen. </p> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Done</Button> </Drawer.Footer> {placement === "top" && <Drawer.Handle />} </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ))} </div> ); } ``` ### Non-Dismissable Set `isDismissable={false}` on `Drawer.Backdrop` to prevent closing by clicking outside or dragging. The user must interact with the drawer's action buttons. ```tsx import {Button, Drawer} from "@heroui/react"; export function NonDismissable() { return ( <Drawer> <Button variant="secondary">Important Action</Button> <Drawer.Backdrop isDismissable={false}> <Drawer.Content> <Drawer.Dialog> <Drawer.Header> <Drawer.Heading>Confirm Action</Drawer.Heading> </Drawer.Header> <Drawer.Body> <p> This drawer cannot be dismissed by clicking outside or dragging. You must use one of the buttons below. </p> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Confirm</Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ### Scrollable Content The `Drawer.Body` automatically handles overflow with native scrolling. Drag-to-dismiss is excluded from the body area to avoid scroll conflicts. ```tsx import {Button, Drawer} from "@heroui/react"; export function ScrollableContent() { return ( <Drawer> <Button variant="secondary">Terms & Conditions</Button> <Drawer.Backdrop> <Drawer.Content> <Drawer.Dialog> <Drawer.Handle /> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading>Terms & Conditions</Drawer.Heading> </Drawer.Header> <Drawer.Body> {Array.from({length: 20}).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> ))} </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> Decline </Button> <Button slot="close">Accept</Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ### Controlled State ```tsx "use client"; import {Button, Drawer, 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 drawer using React's <code className="text-foreground">useState</code> hook for simple state management. </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 Drawer </Button> <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}> Toggle </Button> </div> </div> <Drawer.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}> <Drawer.Content placement="right"> <Drawer.Dialog> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading>Controlled with useState()</Drawer.Heading> </Drawer.Header> <Drawer.Body> <p> This drawer is controlled by React's <code>useState</code> hook. Pass{" "} <code>isOpen</code> and <code>onOpenChange</code> props to manage the drawer state externally. </p> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> Close </Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.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 Drawer </Button> <Button size="sm" variant="tertiary" onPress={state.toggle}> Toggle </Button> </div> </div> <Drawer.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}> <Drawer.Content placement="right"> <Drawer.Dialog> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading>Controlled with useOverlayState()</Drawer.Heading> </Drawer.Header> <Drawer.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> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> Close </Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </div> </div> ); } ``` ### With Form ```tsx import {Button, Drawer, Input, Label, TextField} from "@heroui/react"; export function WithForm() { return ( <Drawer> <Button variant="secondary">Edit Profile</Button> <Drawer.Backdrop> <Drawer.Content placement="right"> <Drawer.Dialog> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading>Edit Profile</Drawer.Heading> </Drawer.Header> <Drawer.Body> <form className="flex flex-col gap-4"> <TextField className="w-full" name="name" type="text"> <Label>Name</Label> <Input placeholder="Enter your name" variant="secondary" /> </TextField> <TextField className="w-full" name="email" type="email"> <Label>Email</Label> <Input placeholder="Enter your email" variant="secondary" /> </TextField> <TextField className="w-full" name="bio"> <Label>Bio</Label> <Input placeholder="Tell us about yourself" variant="secondary" /> </TextField> </form> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Save Changes</Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ### Navigation Drawer ```tsx import type {ComponentType, SVGProps} from "react"; import {Bars, Bell, Envelope, Gear, House, Magnifier, Person} from "@gravity-ui/icons"; import {Button, Drawer} from "@heroui/react"; export function Navigation() { const navItems: {icon: ComponentType<SVGProps<SVGSVGElement>>; label: string}[] = [ {icon: House, label: "Home"}, {icon: Magnifier, label: "Search"}, {icon: Bell, label: "Notifications"}, {icon: Envelope, label: "Messages"}, {icon: Person, label: "Profile"}, {icon: Gear, label: "Settings"}, ]; return ( <Drawer> <Button variant="secondary"> <Bars /> Menu </Button> <Drawer.Backdrop> <Drawer.Content placement="left"> <Drawer.Dialog> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading>Navigation</Drawer.Heading> </Drawer.Header> <Drawer.Body> <nav className="flex flex-col gap-1"> {navItems.map((item) => ( <button key={item.label} className="flex items-center gap-3 rounded-xl px-3 py-2.5 text-sm text-foreground transition-colors hover:bg-default" type="button" > <item.icon className="size-5 text-muted" /> {item.label} </button> ))} </nav> </Drawer.Body> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ### Backdrop Variants ```tsx import {Button, Drawer} from "@heroui/react"; export function BackdropVariants() { const variants = ["opaque", "blur", "transparent"] as const; return ( <div className="flex flex-wrap gap-4"> {variants.map((variant) => ( <Drawer key={variant}> <Button variant="secondary">{variant.charAt(0).toUpperCase() + variant.slice(1)}</Button> <Drawer.Backdrop variant={variant}> <Drawer.Content> <Drawer.Dialog> <Drawer.Handle /> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading> Backdrop: {variant.charAt(0).toUpperCase() + variant.slice(1)} </Drawer.Heading> </Drawer.Header> <Drawer.Body> <p> This drawer uses the <code>{variant}</code> backdrop variant. </p> </Drawer.Body> <Drawer.Footer> <Button className="w-full" slot="close"> Close </Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ))} </div> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Button, Drawer} from "@heroui/react"; export function CustomStyles() { return ( <Drawer> <Button variant="secondary">Open filters</Button> <Drawer.Backdrop variant="blur"> <Drawer.Content placement="right"> <Drawer.Dialog className="border-l border-border/80 bg-surface"> <Drawer.Header> <Drawer.Heading className="text-foreground">Filters</Drawer.Heading> </Drawer.Header> <Drawer.Body> <p className="text-sm text-muted">Narrow results by status, owner, or date.</p> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> Cancel </Button> <Button slot="close">Apply</Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ### Global CSS To customize the Drawer component classes, you can use the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .drawer__backdrop { @apply bg-gradient-to-br from-black/50 to-black/70; } .drawer__dialog { @apply rounded-2xl border border-white/10 shadow-2xl; } .drawer__header { @apply text-center; } .drawer__close-trigger { @apply rounded-full bg-white/10 hover:bg-white/20; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Drawer component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/drawer.css)): #### Base Classes \[!toc] * `.drawer__trigger` - Trigger element that opens the drawer * `.drawer__backdrop` - Overlay backdrop behind the drawer * `.drawer__content` - Positioning wrapper for the drawer panel * `.drawer__dialog` - The drawer panel itself * `.drawer__header` - Header section for titles * `.drawer__heading` - Main title text * `.drawer__body` - Main scrollable content area * `.drawer__footer` - Footer section for actions * `.drawer__handle` - Visual drag handle indicator * `.drawer__close-trigger` - Close button element #### Backdrop Variants \[!toc] * `.drawer__backdrop--opaque` - Opaque colored backdrop (default) * `.drawer__backdrop--blur` - Blurred backdrop with glass effect * `.drawer__backdrop--transparent` - Transparent backdrop (no overlay) #### Placement Variants \[!toc] * `.drawer__content--bottom` - Slides up from the bottom edge (default) * `.drawer__content--top` - Slides down from the top edge * `.drawer__content--left` - Slides in from the left edge * `.drawer__content--right` - Slides in from the right edge #### Dialog Variants \[!toc] * `.drawer__dialog--top` - Slides down from the top edge * `.drawer__dialog--bottom` - Slides up from the bottom edge * `.drawer__dialog--left` - Slides in from the left edge * `.drawer__dialog--right` - Slides in from the right edge ### Interactive States The component supports these interactive states: * **Focus**: `:focus-visible` or `[data-focus-visible="true"]` - Applied to trigger and close button * **Hover**: `:hover` or `[data-hovered="true"]` - Applied to close button on hover * **Active**: `:active` or `[data-pressed="true"]` - Applied to trigger and close button when pressed * **Entering**: `[data-entering]` - Applied during drawer opening animation * **Exiting**: `[data-exiting]` - Applied during drawer closing animation * **Placement**: `[data-placement="*"]` - Applied based on drawer position (top, bottom, left, right) ## API Reference ### Drawer | Prop | Type | Default | Description | | ---------- | ----------------------- | ------- | ----------------------------- | | `children` | `ReactNode` | - | Trigger and backdrop elements | | `state` | `UseOverlayStateReturn` | - | Controlled overlay state | ### Drawer.Trigger | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `children` | `ReactNode` | - | Custom trigger content | | `className` | `string` | - | CSS classes | ### Drawer.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 | ### Drawer.Content | Prop | Type | Default | Description | | ----------- | ---------------------------------------- | ---------- | --------------------------- | | `placement` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | Edge the drawer slides from | | `className` | `string \| (values) => string` | - | Content CSS classes | ### Drawer.Dialog | Prop | Type | Default | Description | | ----------------- | ----------- | ---------- | ------------------- | | `children` | `ReactNode` | - | Dialog content | | `className` | `string` | - | CSS classes | | `role` | `string` | `"dialog"` | ARIA role | | `aria-label` | `string` | - | Accessibility label | | `aria-labelledby` | `string` | - | ID of label element | ### Drawer.Header | Prop | Type | Default | Description | | ----------- | ----------- | ------- | -------------- | | `children` | `ReactNode` | - | Header content | | `className` | `string` | - | CSS classes | ### Drawer.Heading | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ----------- | | `children` | `ReactNode` | - | Title text | | `className` | `string` | - | CSS classes | ### Drawer.Body | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------ | | `children` | `ReactNode` | - | Body content | | `className` | `string` | - | CSS classes | ### Drawer.Footer | Prop | Type | Default | Description | | ----------- | ----------- | ------- | -------------- | | `children` | `ReactNode` | - | Footer content | | `className` | `string` | - | CSS classes | ### Drawer.Handle | Prop | Type | Default | Description | | ----------- | -------- | ------- | ----------- | | `className` | `string` | - | CSS classes | ### Drawer.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 drawer state.close(); // Close drawer 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 drawer when open * **Keyboard**: `ESC` closes (when dismissable), `Tab` cycles elements * **Screen readers**: Proper ARIA attributes via React Aria * **Scroll lock**: Body scroll disabled when open * **Drag to dismiss**: Supports pointer-based drag gestures on handle, header, and footer areas ## Related Components ## Related Components * **Modal**: Displays content in a modal overlay * **Button**: Allows a user to perform an action * **CloseButton**: Button for dismissing overlays </page> <page url="/en/docs/react/components/modal"> # Modal **Category**: react **URL**: https://heroui.com/en/docs/react/components/modal **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(overlays)/modal.mdx > Dialog overlay for focused user interactions and important content ## Usage ```tsx import { Modal } from "@heroui/react"; ``` ```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 ```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> ); ``` ## Examples ### 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> ); } ``` ### 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> ); } ``` ### Scroll Behavior ```tsx "use client"; import {Button, 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.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Inside </Radio.Content> </Radio> <Radio value="outside"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> Outside </Radio.Content> </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" variant="secondary"> <Label>Name</Label> <Input placeholder="Enter your name" /> </TextField> <TextField className="w-full" name="email" type="email" variant="secondary"> <Label>Email</Label> <Input placeholder="Enter your email" /> </TextField> <TextField className="w-full" name="phone" type="tel" variant="secondary"> <Label>Phone</Label> <Input placeholder="Enter your phone number" /> </TextField> <TextField className="w-full" name="company" variant="secondary"> <Label>Company</Label> <Input placeholder="Enter your company name" /> </TextField> <TextField className="w-full" name="message" variant="secondary"> <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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ## Customization ### Tailwind CSS ```tsx "use client"; import {CircleCheck} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function CustomStyles() { return ( <Modal> <Button variant="secondary">Open</Button> <Modal.Backdrop className="bg-overlay/50 dark:bg-overlay/65" variant="blur"> <Modal.Container> <Modal.Dialog className="relative overflow-hidden border border-border/80 bg-surface/90 shadow-2xl ring-1 ring-black/5 backdrop-blur-xl sm:max-w-[340px] dark:border-border/90 dark:bg-surface/85 dark:ring-white/10"> <div aria-hidden="true" className="pointer-events-none absolute inset-x-0 top-0 h-20 bg-linear-to-b from-neutral-500/8 to-transparent dark:from-neutral-400/10" /> <div aria-hidden="true" className="pointer-events-none absolute inset-x-10 top-0 h-px bg-linear-to-r from-transparent via-neutral-400/40 to-transparent dark:via-neutral-500/35" /> <Modal.CloseTrigger /> <Modal.Header className="relative"> <Modal.Icon className="bg-neutral-100 text-neutral-700 dark:bg-neutral-800 dark:text-neutral-200"> <CircleCheck className="size-5" /> </Modal.Icon> <Modal.Heading>Changes saved</Modal.Heading> </Modal.Header> <Modal.Body className="relative"> <p className="text-sm text-muted">Your draft is synced across devices.</p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="close"> Done </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); } ``` ### Global CSS To customize the Modal component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.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 \[!toc] * `.modal__backdrop--opaque` - Opaque colored backdrop (default) * `.modal__backdrop--blur` - Blurred backdrop with glass effect * `.modal__backdrop--transparent` - Transparent backdrop (no overlay) #### Scroll Variants \[!toc] * `.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 ## Related Components ## Related Components * **Button**: Allows a user to perform an action * **Tooltip**: Contextual information on hover or focus * **Select**: Dropdown select control </page> <page url="/en/docs/react/components/popover"> # Popover **Category**: react **URL**: https://heroui.com/en/docs/react/components/popover **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(overlays)/popover.mdx > Displays rich content in a portal triggered by a button or any custom element ## Usage ```tsx import { Popover } from '@heroui/react'; ``` ```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 ```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> ) ``` ## Examples ### 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 aria-label="More options" 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> ); } ``` ### 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="ms-1 text-sm text-muted">Following</span> </div> <div> <span className="font-semibold">12.5K</span> <span className="ms-1 text-sm text-muted">Followers</span> </div> </div> </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> ); } ``` ### Render Function ```tsx "use client"; import {Button, Popover} from "@heroui/react"; export function RenderFunction() { 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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Button, Popover} from "@heroui/react"; export function CustomStyles() { return ( <Popover> <Button variant="secondary">Details</Button> <Popover.Content className="max-w-56 overflow-hidden rounded-xl border border-border/80 bg-surface/90 p-0 shadow-xl ring-1 ring-black/5 backdrop-blur-xl dark:border-border/90 dark:bg-surface/85 dark:ring-white/10"> <Popover.Dialog className="relative p-4"> <div aria-hidden="true" className="pointer-events-none absolute inset-x-0 top-0 h-12 bg-linear-to-b from-neutral-500/6 to-transparent dark:from-neutral-400/8" /> <Popover.Heading className="relative font-medium text-neutral-800 dark:text-neutral-100"> Keyboard shortcuts </Popover.Heading> <dl className="relative mt-3 space-y-2 text-sm"> <div className="flex justify-between gap-4"> <dt className="text-muted">Save</dt> <dd className="font-mono text-neutral-700 dark:text-neutral-300">⌘ S</dd> </div> <div className="flex justify-between gap-4"> <dt className="text-muted">Search</dt> <dd className="font-mono text-neutral-700 dark:text-neutral-300">⌘ K</dd> </div> </dl> </Popover.Dialog> </Popover.Content> </Popover> ); } ``` ### Global CSS To customize the Popover component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.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 | 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 | 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 | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | ---------------------- | | `children` | `React.ReactNode` | - | Dialog content | | `className` | `string` | - | Additional CSS classes | ### Popover.Trigger | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | --------------------------------- | | `children` | `React.ReactNode` | - | Element that triggers the popover | | `className` | `string` | - | Additional CSS classes | ### Popover.Arrow | 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. | ## Related Components ## Related Components * **Button**: Allows a user to perform an action * **Tooltip**: Contextual information on hover or focus * **Select**: Dropdown select control </page> <page url="/en/docs/react/components/sheet"> # Sheet **Category**: react **URL**: https://heroui.com/en/docs/react/components/sheet **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(overlays)/sheet.mdx > Swipeable overlay with native scroll snapping, partial positions, and nested sheets ## Usage ```tsx import {Button, Sheet} from "@heroui/react"; ``` ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function Basic() { return ( <Sheet> <Sheet.Trigger> <Button variant="secondary">Open Sheet</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-h-[95vh] max-w-[420px]"> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger /> <Sheet.Header> <Sheet.Heading>Sheet Title</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> This is a bottom sheet built with smooth drag-to-dismiss animations. Try dragging the handle down to close, or use the close button. </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">Cancel</Button> </Sheet.Close> <Sheet.Close> <Button variant="secondary">Confirm</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ## Anatomy ```tsx import {Button, Sheet} from "@heroui/react"; export default () => ( <Sheet> <Sheet.Trigger> <Button>Open sheet</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger /> <Sheet.Header> <Sheet.Heading>Details</Sheet.Heading> </Sheet.Header> <Sheet.Body>Sheet content</Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button>Done</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); ``` `Sheet.Root` is an alias for `Sheet`. `Sheet.Trigger` wraps a pressable child such as `Button` and is placed directly inside the root. Provide a `Sheet.Heading`, `aria-label`, or `aria-labelledby` for the dialog's accessible name. Use `Sheet.Close`, `Sheet.CloseTrigger`, or a button with `slot="close"` for keyboard-accessible dismissal; the handle is decorative to assistive technology. ## Examples ### Placements Set `placement` on the root to `bottom` (default), `top`, `left`, or `right`. ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function Placements() { const placements = ["bottom", "top", "left", "right"] as const; return ( <div className="flex flex-wrap gap-4"> {placements.map((p) => ( <Sheet key={p} placement={p}> <Sheet.Trigger> <Button variant="secondary">{p.charAt(0).toUpperCase() + p.slice(1)}</Button> </Sheet.Trigger> <Sheet.Backdrop variant="blur"> <Sheet.Content className={p === "left" || p === "right" ? "w-[400px]" : undefined}> <Sheet.Dialog> <Sheet.CloseTrigger /> {p === "bottom" && <Sheet.Handle />} <Sheet.Header> <Sheet.Heading>{p.charAt(0).toUpperCase() + p.slice(1)} Sheet</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> This sheet slides in from the <strong>{p}</strong> edge of the screen with a smooth spring-like animation. </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">Cancel</Button> </Sheet.Close> <Sheet.Close> <Button variant="secondary">Done</Button> </Sheet.Close> </Sheet.Footer> {p === "top" && <Sheet.Handle />} </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ))} </div> ); } ``` ### Snap Points Numbers are **pixels**, not fractions. Strings are CSS lengths; percentages are relative to the sheet. The sheet opens at the first point and can expand to full size without an explicit final point. A trailing `1`, `"1"`, or `"100%"` is ignored. Other numbers retain their pixel meaning. ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; const snapPointValues = ["148px", "355px"]; export function SnapPoints() { return ( <Sheet snapPoints={snapPointValues}> <Sheet.Trigger> <Button variant="secondary">Snap Points</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content> <Sheet.Dialog> <Sheet.Handle /> <Sheet.Header> <Sheet.Heading>Snap Points</Sheet.Heading> </Sheet.Header> <Sheet.Body> <div className="flex flex-col gap-4"> <p className="text-sm text-muted"> This sheet opens at 148px and snaps again at 355px. Dragging past the last detent reveals the full sheet, and the backdrop fades in after that point. </p> {Array.from({length: 6}).map((_, i) => ( <p key={i} className="text-sm text-muted"> {i === 0 ? "Swipe up to reveal more content and fade the backdrop in." : `More content at this level (${i + 1}).`} </p> ))} </div> </Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### Snap Points (Sequential) A swipe can pass through multiple snap points. Full expansion is implicit; no additional sequential-snapping prop is needed. ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; const snapPointValues = ["148px", "355px"]; export function SnapPointsSequential() { return ( <Sheet snapPoints={snapPointValues}> <Sheet.Trigger> <Button variant="secondary">Sequential Snap Points</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content> <Sheet.Dialog> <Sheet.Handle /> <Sheet.Header> <Sheet.Heading>Snap points</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> A swipe can move across several detents. Full height is the end of the gesture, so it is not listed as its own snap point. </p> </Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### Snap Points (Custom Fade) The backdrop remains clear through the partial snap points and fades in as the sheet expands past the last point. React Aria manages this behavior; `fadeFromIndex` is not supported. ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; const fadeSnapPoints = ["150px", "300px", "450px"]; export function SnapPointsCustomFade() { return ( <Sheet snapPoints={fadeSnapPoints}> <Sheet.Trigger> <Button variant="secondary">Custom Fade Index</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content> <Sheet.Dialog> <Sheet.Handle /> <Sheet.Header> <Sheet.Heading>Backdrop fade</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> The backdrop stays clear through the snap points and fades in only after the last detent, as the sheet opens to its full height. </p> </Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### Backdrop Variants ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function BackdropVariants() { const variants = ["opaque", "blur", "transparent"] as const; return ( <div className="flex flex-wrap gap-4"> {variants.map((v) => ( <Sheet key={v}> <Sheet.Trigger> <Button variant="secondary">{v.charAt(0).toUpperCase() + v.slice(1)}</Button> </Sheet.Trigger> <Sheet.Backdrop variant={v}> <Sheet.Content className="mx-auto max-h-[95vh] max-w-[420px]"> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger /> <Sheet.Header> <Sheet.Heading>Backdrop: {v.charAt(0).toUpperCase() + v.slice(1)}</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> This sheet uses the <code className="text-foreground">{v}</code> backdrop variant. </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button className="w-full">Close</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ))} </div> ); } ``` ### Non-Dismissable `isDismissable={false}` prevents outside interaction, Escape, and swipe dismissal. Explicit close controls still work. ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function NonDismissable() { return ( <Sheet isDismissable={false}> <Sheet.Trigger> <Button variant="secondary">Important Action</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog> <Sheet.Header> <Sheet.Heading>Confirm Action</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> This sheet cannot be dismissed by clicking outside or dragging. You must use one of the buttons below. </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">Cancel</Button> </Sheet.Close> <Sheet.Close> <Button variant="secondary">Confirm</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### Scrollable Content At a partial snap point, swiping expands the sheet. Once fully expanded, `Sheet.Body` scrolls its content. `Sheet.Handle` also supports pointer dragging, including a mouse. ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function ScrollableContent() { return ( <Sheet> <Sheet.Trigger> <Button variant="secondary">Terms & Conditions</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-h-[95vh] max-w-[420px]"> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger /> <Sheet.Header> <Sheet.Heading>Terms & Conditions</Sheet.Heading> </Sheet.Header> <Sheet.Body> {Array.from({length: 20}).map((_, i) => ( <p key={i} className="mb-3 text-sm text-muted"> 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. Donec nec vestibulum libero. </p> ))} </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">Decline</Button> </Sheet.Close> <Sheet.Close> <Button variant="secondary">Accept</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### With Form Compose form fields inside `Sheet.Body`. Use secondary inputs on the overlay surface. ```tsx "use client"; import {Button, Input, Label, Sheet, TextField} from "@heroui/react"; export function WithForm() { return ( <Sheet placement="right"> <Sheet.Trigger> <Button variant="secondary">Edit Profile</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="w-[400px]"> <Sheet.Dialog> <Sheet.CloseTrigger /> <Sheet.Header> <Sheet.Heading>Edit Profile</Sheet.Heading> </Sheet.Header> <Sheet.Body> <form className="flex flex-col gap-4"> <TextField className="w-full" name="name" type="text"> <Label>Name</Label> <Input placeholder="Enter your name" variant="secondary" /> </TextField> <TextField className="w-full" name="email" type="email"> <Label>Email</Label> <Input placeholder="Enter your email" variant="secondary" /> </TextField> <TextField className="w-full" name="bio"> <Label>Bio</Label> <Input placeholder="Tell us about yourself" variant="secondary" /> </TextField> </form> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">Cancel</Button> </Sheet.Close> <Sheet.Close> <Button variant="secondary">Save Changes</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### Detached `isDetached` adds space around the sheet and rounds all corners. ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function Detached() { const placements = ["bottom", "top", "left", "right"] as const; return ( <div className="flex flex-wrap gap-4"> {placements.map((p) => ( <Sheet key={p} isDetached placement={p}> <Sheet.Trigger> <Button variant="secondary">{p.charAt(0).toUpperCase() + p.slice(1)}</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className={p === "left" || p === "right" ? "w-[310px]" : "mx-auto max-w-[420px]"} > <Sheet.Dialog className={p === "left" || p === "right" ? "h-full" : undefined}> {p === "bottom" && <Sheet.Handle />} <Sheet.Body className="flex flex-col gap-4 py-5"> <Sheet.Heading>Detached {p}</Sheet.Heading> <p className="text-sm text-muted"> The sheet floats away from the viewport edge with rounded corners on all sides. </p> </Sheet.Body> {p === "top" && <Sheet.Handle />} </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ))} </div> ); } ``` ### Controlled State Use `isOpen` with `onOpenChange`, or `defaultOpen` for uncontrolled state. A controlled sheet may omit `Sheet.Trigger`. ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [isOpen, setIsOpen] = useState(false); return ( <div className="flex flex-col items-start gap-4"> <div className="flex items-center gap-3"> <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}> Open Sheet </Button> <Button size="sm" variant="secondary" onPress={() => setIsOpen(!isOpen)}> Toggle </Button> <p className="text-xs text-muted"> Status:{" "} <span className="font-mono font-medium text-foreground"> {isOpen ? "open" : "closed"} </span> </p> </div> <Sheet isOpen={isOpen} onOpenChange={setIsOpen}> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger /> <Sheet.Header> <Sheet.Heading>Controlled Sheet</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> This sheet is controlled via <code>isOpen</code> and <code>onOpenChange</code>{" "} props. The parent manages the state externally. </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button>Close</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> </div> ); } ``` ### Handle Only The handle offers a visible grip and supports pointer dragging. Touch gestures also work on the panel until it is fully expanded; the handle does not restrict swipes to itself. ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function HandleOnly() { return ( <Sheet> <Sheet.Trigger> <Button variant="secondary">Handle Only</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger /> <Sheet.Header> <Sheet.Heading>Swipe the sheet</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> The handle is a visual grip. Swipe anywhere on the sheet until it is fully expanded. After that, the body scrolls instead of moving the sheet. </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">Done</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### Nested Sheets Place `Sheet.NestedRoot` inside another sheet. React Aria manages stacking and focus restoration; only the bottom sheet dims the page. ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; const NESTED_DIALOG_HEIGHT = "h-[320px]"; export function Nested() { return ( <Sheet> <Sheet.Trigger> <Button variant="secondary">Open Parent Sheet</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog className={NESTED_DIALOG_HEIGHT}> <Sheet.Handle /> <Sheet.CloseTrigger /> <Sheet.Header> <Sheet.Heading>Parent Sheet</Sheet.Heading> </Sheet.Header> <Sheet.Body className="flex flex-col justify-between pb-4"> <p className="mb-4 text-sm text-muted"> This is the parent sheet. Open a nested sheet from here — the parent will scale down and the child slides on top. </p> <Sheet.NestedRoot> <Sheet.Trigger> <Button className="w-full" variant="secondary"> Open Nested Sheet </Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog className={NESTED_DIALOG_HEIGHT}> <Sheet.Handle /> <Sheet.CloseTrigger /> <Sheet.Header> <Sheet.Heading>Nested Sheet</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="mb-4 text-sm text-muted"> This is a nested sheet that sits on top of the parent. Drag it down to dismiss and return to the parent sheet. </p> <Sheet.NestedRoot> <Sheet.Trigger> <Button className="w-full" variant="secondary"> Go Deeper </Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog className={NESTED_DIALOG_HEIGHT}> <Sheet.Handle /> <Sheet.CloseTrigger /> <Sheet.Header> <Sheet.Heading>Third Level</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> Three levels deep! Each parent sheet scales down as the next one opens, creating a stacking effect. </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button className="w-full">Close</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet.NestedRoot> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">Back</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet.NestedRoot> </Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### Professions Picker Combine a search field and a virtualized list inside a sheet with a 355px initial snap point. Selecting an occupation updates the value and closes the sheet. ```tsx "use client"; import { Button, EmptyState, Label, ListBox, ListLayout, SearchField, Sheet, Virtualizer, } from "@heroui/react"; import {Icon} from "@iconify/react"; import {useMemo, useState} from "react"; const PROFESSIONS = [ "Accountants and Auditors", "Actors", "Actuaries", "Administrative Services Managers", "Advertising and Promotions Managers", "Advertising Sales Agents", "Aerospace Engineers", "Agricultural Engineers", "Air Traffic Controllers", "Aircraft Mechanics and Service Technicians", "Ambulance Drivers and Attendants", "Anesthesiologists", "Animal Control Workers", "Animators", "Arbitrators, Mediators, and Conciliators", "Architects, Except Landscape and Naval", "Architectural and Engineering Managers", "Archivists", "Art Directors", "Athletic Trainers", "Atmospheric and Space Scientists", "Audiologists", "Automotive Body and Related Repairers", "Automotive Service Technicians and Mechanics", "Baggage Porters and Bellhops", "Bakers", "Barbers", "Bartenders", "Bicycle Repairers", "Billing and Posting Clerks", "Biochemists and Biophysicists", "Biomedical Engineers", "Bookkeeping, Accounting, and Auditing Clerks", "Brickmasons and Blockmasons", "Broadcast Technicians", "Budget Analysts", "Bus Drivers", "Business Operations Specialists", "Butchers and Meat Cutters", "Cabinetmakers and Bench Carpenters", "Camera Operators, Television, Video, and Film", "Cardiovascular Technologists and Technicians", "Cargo and Freight Agents", "Carpenters", "Cashiers", "Cement Masons and Concrete Finishers", "Chefs and Head Cooks", "Chemical Engineers", "Chemists", "Chief Executives", "Child, Family, and School Social Workers", "Chiropractors", "Civil Engineers", "Claims Adjusters, Examiners, and Investigators", "Clinical Laboratory Technologists and Technicians", "Coaches and Scouts", "Commercial Pilots", "Community Health Workers", "Compensation and Benefits Managers", "Computer and Information Systems Managers", "Computer Hardware Engineers", "Computer Network Architects", "Computer Programmers", "Computer Systems Analysts", "Conservation Scientists", "Construction Laborers", "Construction Managers", "Correctional Officers and Jailers", "Cost Estimators", "Counselors", "Court Reporters and Simultaneous Captioners", "Credit Analysts", "Curators", "Customer Service Representatives", "Cybersecurity Analysts", "Data Scientists", "Database Administrators", "Dental Assistants", "Dental Hygienists", "Dentists", "Detectives and Criminal Investigators", "Diagnostic Medical Sonographers", "Dietitians and Nutritionists", "Directors, Religious Activities and Education", "Disc Jockeys", "Dispatchers", "Economists", "Editors", "Education Administrators", "Electrical Engineers", "Electricians", "Elementary School Teachers", "Emergency Management Directors", "Emergency Medical Technicians and Paramedics", "Environmental Engineers", "Environmental Scientists and Specialists", "Epidemiologists", "Event Planners", "Exercise Physiologists", "Fashion Designers", "Film and Video Editors", "Financial Analysts", "Financial Examiners", "Financial Managers", "Fire Inspectors and Investigators", "Firefighters", "Fitness Trainers and Aerobics Instructors", "Flight Attendants", "Floral Designers", "Food Scientists and Technologists", "Forensic Science Technicians", "Fundraisers", "Funeral Attendants", "General and Operations Managers", "Genetic Counselors", "Geographers", "Geoscientists", "Glaziers", "Graphic Designers", "Hairdressers, Hairstylists, and Cosmetologists", "Health and Safety Engineers", "Healthcare Social Workers", "Heating, Air Conditioning, and Refrigeration Mechanics", "High School Teachers", "Historians", "Home Health and Personal Care Aides", "Human Resources Managers", "Human Resources Specialists", "Hydrologists", "Industrial Designers", "Industrial Engineers", "Industrial Machinery Mechanics", "Information Security Analysts", "Insurance Appraisers", "Insurance Sales Agents", "Insurance Underwriters", "Interior Designers", "Interpreters and Translators", "Janitors and Cleaners", "Jewelers and Precious Stone Workers", "Journalists", "Judges and Magistrates", "Kindergarten Teachers", "Landscape Architects", "Lawyers", "Librarians and Media Collections Specialists", "Licensed Practical Nurses", "Loan Officers", "Locksmiths and Safe Repairers", "Logisticians", "Machine Learning Engineers", "Machinists", "Maids and Housekeeping Cleaners", "Management Analysts", "Marine Engineers and Naval Architects", "Market Research Analysts", "Marketing Managers", "Marriage and Family Therapists", "Massage Therapists", "Mathematicians", "Mechanical Engineers", "Medical Assistants", "Medical Records Specialists", "Medical Scientists", "Microbiologists", "Middle School Teachers", "Millwrights", "Mining and Geological Engineers", "Music Directors and Composers", "Musicians and Singers", "Network and Computer Systems Administrators", "Nuclear Engineers", "Nurse Anesthetists", "Nurse Practitioners", "Nursing Assistants", "Occupational Health and Safety Specialists", "Occupational Therapists", "Opticians, Dispensing", "Optometrists", "Orthodontists", "Paralegals and Legal Assistants", "Parking Enforcement Workers", "Pathologists", "Pediatricians", "Personal Financial Advisors", "Pest Control Workers", "Pharmacists", "Pharmacy Technicians", "Phlebotomists", "Photographers", "Physical Therapist Assistants", "Physical Therapists", "Physician Assistants", "Physicians and Surgeons", "Physicists", "Pipefitters and Steamfitters", "Plumbers", "Podiatrists", "Police Officers", "Political Scientists", "Postal Service Mail Carriers", "Postsecondary Teachers", "Preschool Teachers", "Private Detectives and Investigators", "Probation Officers", "Producers and Directors", "Product Managers", "Property Managers", "Prosthodontists", "Psychiatric Technicians", "Psychiatrists", "Psychologists", "Public Relations Managers", "Public Relations Specialists", "Purchasing Managers", "Radiation Therapists", "Radiologic Technologists and Technicians", "Real Estate Agents and Brokers", "Receptionists and Information Clerks", "Recreation Workers", "Recreational Therapists", "Registered Nurses", "Rehabilitation Counselors", "Reporters and Correspondents", "Respiratory Therapists", "Restaurant Cooks", "Roofers", "Sales Engineers", "Sales Managers", "School Bus Drivers", "School Psychologists", "Security Guards", "Sheet Metal Workers", "Sheriffs and Deputy Sheriffs", "Skincare Specialists", "Social and Community Service Managers", "Social Workers", "Software Developers", "Software Quality Assurance Analysts", "Sound Engineering Technicians", "Special Education Teachers", "Speech-Language Pathologists", "Statisticians", "Structural Iron and Steel Workers", "Substance Abuse Counselors", "Surgeons", "Survey Researchers", "Surveyors", "Tax Examiners and Collectors", "Tax Preparers", "Taxi Drivers and Chauffeurs", "Technical Writers", "Telecommunications Equipment Installers", "Tellers", "Training and Development Managers", "Training and Development Specialists", "Travel Agents", "Urban and Regional Planners", "UX Designers", "Veterinarians", "Veterinary Technologists and Technicians", "Waiters and Waitresses", "Water Treatment Plant Operators", "Web Developers", "Welders, Cutters, Solderers, and Brazers", "Writers and Authors", "Zoologists and Wildlife Biologists", ].map((name, i) => ({id: i, name})); const professionSheetSnaps = ["355px"]; export function ProfessionsPicker() { const [isOpen, setIsOpen] = useState(false); const [search, setSearch] = useState(""); const [selected, setSelected] = useState<string | null>(null); const filtered = useMemo(() => { if (!search) return PROFESSIONS; const q = search.toLowerCase(); return PROFESSIONS.filter((p) => p.name.toLowerCase().includes(q)); }, [search]); return ( <div className="flex flex-col items-center gap-3"> <Sheet isOpen={isOpen} snapPoints={professionSheetSnaps} onOpenChange={(open) => { setIsOpen(open); if (!open) setSearch(""); }} > <Sheet.Trigger> <Button variant="secondary">Choose Occupation</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-h-[95vh] max-w-[420px]"> <Sheet.Dialog aria-label="Choose Occupation"> <Sheet.Handle /> <Sheet.Body className="flex min-h-0 flex-col gap-0 overflow-hidden p-0"> <div className="px-4 pt-1 pb-2"> <SearchField aria-label="Search occupations" value={search} variant="secondary" onChange={setSearch} > <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> </div> {filtered.length === 0 ? ( <EmptyState className="flex min-h-32 flex-1 flex-col items-center justify-center gap-2"> <Icon className="size-5 text-muted" icon="gravity-ui:magnifier" /> <p className="text-sm text-muted">No occupations found.</p> </EmptyState> ) : ( <Virtualizer layout={ListLayout} layoutOptions={{padding: 12, rowHeight: 36}}> <ListBox aria-label="Occupations" className="min-h-0 flex-1 overflow-y-auto p-0" items={filtered} selectionMode="single" onAction={(key) => { const prof = PROFESSIONS.find((p) => p.id === Number(key)); if (prof) { setSelected(prof.name); setIsOpen(false); } }} > {(item) => ( <ListBox.Item id={item.id} textValue={item.name}> <Label>{item.name}</Label> </ListBox.Item> )} </ListBox> </Virtualizer> )} </Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> <p className="text-sm text-muted"> Selected: <span className="font-medium text-foreground">{selected}</span> </p> </div> ); } ``` ## Customization Use `className` on compound parts or override the `sheet__*` BEM classes in `@layer components`. Preserve React Aria's scroll positioning rather than adding a separate translate-based entrance animation. ### Tailwind CSS Apply Tailwind CSS utilities to individual parts with `className`. ```tsx <Sheet> <Sheet.Trigger> <Button variant="secondary">Open sheet</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-lg"> <Sheet.Dialog className="rounded-t-3xl border border-border"> <Sheet.Handle /> <Sheet.CloseTrigger /> <Sheet.Header className="text-center"> <Sheet.Heading>Details</Sheet.Heading> </Sheet.Header> <Sheet.Body className="px-6 pb-6">Sheet content</Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ``` ### Global CSS Use `@layer components` to customize the Sheet BEM classes. ```css @layer components { .sheet__dialog { @apply border border-border; } .sheet__header { @apply text-center; } .sheet__body { @apply px-6 pb-6; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to keep component styles reusable and easy to customize. ### CSS Classes #### Base Classes \[!toc] * `.sheet__overlay` - Modal overlay container * `.sheet__backdrop` - Backdrop behind the sheet * `.sheet__content` - Sheet sizing and stacking wrapper * `.sheet__dialog` - Dialog surface * `.sheet__header` - Header section * `.sheet__heading` - Dialog title * `.sheet__body` - Content area that scrolls after full expansion * `.sheet__footer` - Footer actions * `.sheet__handle` - Draggable handle area * `.sheet__handle-bar` - Default visual grip * `.sheet__close-trigger` - Close button #### Backdrop Variants \[!toc] * `.sheet__backdrop--opaque` - Dimmed backdrop (default) * `.sheet__backdrop--blur` - Blurred backdrop * `.sheet__backdrop--transparent` - Transparent backdrop Only the bottom-most sheet in a nested stack dims the page. #### Placement Variants \[!toc] * `.sheet__content--bottom`, `.sheet__dialog--bottom` - Bottom edge (default) * `.sheet__content--top`, `.sheet__dialog--top` - Top edge * `.sheet__content--left`, `.sheet__dialog--left` - Left edge * `.sheet__content--right`, `.sheet__dialog--right` - Right edge ### Interactive States * `[data-focus-visible="true"]` - Keyboard focus on the close button; native fallback uses `:focus-visible:not([data-focused])` * `:hover`, `[data-hovered="true"]` - Close button hover * `:disabled`, `[aria-disabled="true"]` - Disabled close button * `[data-dragging]` - Handle drag in progress * `[data-expanded]` - Fully expanded sheet; enables body scrolling * `[data-has-descendants]` - Parent sheet with an open nested sheet * `[data-detached]` - Inset spacing and rounded corners * `[data-snap-points]` - Sheet configured with partial snap points * `[data-entering]`, `[data-exiting]` - Opening and closing lifecycle states * `[data-closed]` - Retained closed overlay; pointer interaction is disabled ### Data Attributes The rendered parts expose `data-slot`: `sheet-overlay`, `sheet-backdrop`, `sheet-content`, `sheet-dialog`, `sheet-header`, `sheet-heading`, `sheet-body`, `sheet-footer`, `sheet-handle`, `sheet-handle-bar`, and `sheet-close-trigger`. The root, trigger, and close wrappers do not add DOM elements. `Sheet.Content` also exposes `data-placement`, `data-detached`, and `data-snap-points`. React Aria supplies `data-position`, `data-expanded`, `data-stack-index`, `data-has-descendants`, `data-entering`, and `data-exiting` on applicable parts. ## API Reference ### Sheet / Sheet.Root / Sheet.NestedRoot | Prop | Type | Default | Description | | ---------------- | ---------------------------------------- | ---------- | ------------------------------------------------------ | | `children` | `ReactNode` | — | Compound parts. | | `isOpen` | `boolean` | — | Controlled visibility. | | `defaultOpen` | `boolean` | `false` | Initial uncontrolled visibility. | | `onOpenChange` | `(open: boolean) => void` | — | Called when a visibility change is requested. | | `onClose` | `() => void` | — | Called when closing is requested. | | `onAnimationEnd` | `(open: boolean) => void` | — | Called after entering or exiting finishes. | | `placement` | `"bottom" \| "top" \| "left" \| "right"` | `"bottom"` | Physical screen edge. | | `isDismissable` | `boolean` | `true` | Allow outside, Escape, and swipe dismissal. | | `isDetached` | `boolean` | `false` | Inset the sheet from the screen edges. | | `snapPoints` | `(number \| string)[]` | — | Partial resting positions; full expansion is implicit. | `Sheet.NestedRoot` requires a parent Sheet. The `isNested` root flag is internal; use `NestedRoot` for nesting. ### Sheet.Trigger | Prop | Type | Default | Description | | ---------- | -------------- | ------- | ----------------------------------------------------------------- | | `children` | `ReactElement` | — | One pressable child, such as Button. Place directly inside Sheet. | ### Sheet.Close | Prop | Type | Default | Description | | ---------- | -------------- | ------- | ------------------------------------------------------------------ | | `children` | `ReactElement` | — | One pressable child; its onPress handler is composed with closing. | ### Sheet.Backdrop | Prop | Type | Default | Description | | ----------- | ------------------------------------- | ---------- | -------------------------------------------------------- | | `children` | `ReactNode` | — | Content to render. | | `className` | `string` | — | CSS classes. | | `variant` | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | Backdrop appearance. | | `isExiting` | `boolean` | — | Retain content after closing until this flag is cleared. | Other props inherit from React Aria SheetOverlay, excluding root-owned state, position, snap points, and `style`. Closing still releases modal focus containment and scroll locking. Clear `isExiting` when retained content is no longer needed. ### Sheet.Content | Prop | Type | Default | Description | | ----------- | -------------------------------------------------------- | ------- | ------------------------------------------------------- | | `children` | `ReactNode \| ((values: SheetRenderProps) => ReactNode)` | — | Content or a function receiving React Aria sheet state. | | `className` | `string` | — | CSS classes. | Other props inherit from React Aria Sheet. HeroUI manages stacking animation and overscroll padding; `stackAnimation` and `overscrollPadding` cannot be overridden through this component. ### Sheet.Dialog | Prop | Type | Default | Description | | ------------------ | --------------------------- | ---------- | ---------------------------------------------------- | | `children` | `ReactNode` | — | Content to render. | | `className` | `string` | — | CSS classes. | | `role` | `"dialog" \| "alertdialog"` | `"dialog"` | Accessible dialog role. | | `aria-label` | `string` | — | Accessible name when no visible heading is provided. | | `aria-labelledby` | `string` | — | ID of the element that labels the dialog. | | `aria-describedby` | `string` | — | ID of the element describing the dialog. | Other props and refs inherit from React Aria SheetContent. ### Sheet.Header | Prop | Type | Default | Description | | ----------- | ----------- | ------- | --------------- | | `children` | `ReactNode` | — | Header content. | | `className` | `string` | — | CSS classes. | Supports standard div props, event handlers, and refs. ### Sheet.Heading | Prop | Type | Default | Description | | ----------- | ----------- | --------- | --------------------------------------- | | `children` | `ReactNode` | — | Dialog title. | | `className` | `string` | — | CSS classes. | | `slot` | `string` | `"title"` | Associates the heading with the dialog. | Other props and refs inherit from React Aria Heading. ### Sheet.Body | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------ | | `children` | `ReactNode` | — | Scrollable body content. | | `className` | `string` | — | CSS classes. | Supports standard div props, event handlers, and refs. ### Sheet.Footer | Prop | Type | Default | Description | | ----------- | ----------- | ------- | --------------- | | `children` | `ReactNode` | — | Footer actions. | | `className` | `string` | — | CSS classes. | Supports standard div props, event handlers, and refs. ### Sheet.Handle | Prop | Type | Default | Description | | ----------- | ----------- | ------- | -------------------------------------------------- | | `children` | `ReactNode` | — | Custom grip; renders the default bar when omitted. | | `className` | `string` | — | CSS classes. | Supports standard div props, event handlers, and refs. ### Sheet.CloseTrigger | Prop | Type | Default | Description | | ------------ | --------------------------------------------------------- | --------- | ---------------------------------------------------- | | `children` | `ReactNode \| ((values: ButtonRenderProps) => ReactNode)` | — | Custom content; defaults to the close icon. | | `className` | `string` | — | CSS classes. | | `isDisabled` | `boolean` | `false` | Disable the close button. | | `aria-label` | `string` | `"Close"` | Accessible name; provide localized text when needed. | | `onPress` | `(event: PressEvent) => void` | — | Called together with the sheet close action. | Other props and refs inherit from CloseButton. Named exports include `SheetRoot`, `SheetTrigger`, and the other parts, their props types, `SheetProps`, `SheetNestedRootProps`, `sheetVariants`, and `SheetVariants`. Compound prop types use indexed access, for example `Sheet["Props"]` and `Sheet["ContentProps"]`. ## Sheet and Drawer Sheet uses React Aria's native scroll gestures, partial snap positions, and nested stacking. Drawer remains available with its existing API and behavior. Adding Sheet does not migrate or deprecate Drawer. ## Accessibility * **Accessible name**: Label the dialog with `Sheet.Heading`, `aria-label`, or `aria-labelledby`. * **Focus management**: Opening moves focus into the sheet and contains it within the active modal. Closing restores focus to the trigger; closing a nested sheet restores focus within its parent. * **Keyboard**: Use `Tab` and `Shift+Tab` to move between controls. `Escape` closes the sheet when dismissal is enabled. * **Close controls**: `Sheet.Close` and `Sheet.CloseTrigger` support keyboard activation, including when `isDismissable={false}`. * **Scroll locking**: Page scrolling is locked while the modal is open. `Sheet.Body` scrolls after full expansion. Retained closed content does not keep the page locked. * **Drag handle**: The handle is hidden from assistive technology and does not support keyboard dragging. Provide accessible close controls instead of relying solely on swipe gestures. ## Related Components ## Related Components * **Drawer**: Slide-out panel for supplementary content and actions * **Modal**: Displays content in a modal overlay * **Button**: Allows a user to perform an action </page> <page url="/en/docs/react/components/toast"> # Toast **Category**: react **URL**: https://heroui.com/en/docs/react/components/toast **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(overlays)/toast.mdx > Display temporary notifications and messages to users with automatic dismissal and customizable placement ## Usage ```tsx import { Toast, toast } from '@heroui/react'; ``` ```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={() => { const id = toast("You have been invited to join a team", { actionProps: { children: "Dismiss", onPress: () => toast.close(id), variant: "tertiary", }, description: "Bob sent you an invitation to join HeroUI team", indicator: <Persons />, variant: "default", }); }} > Show toast </Button> </div> ); } ``` ## Anatomy ```tsx <Toast.Provider> <Toast> <Toast.Indicator /> <Toast.Content> <Toast.Title /> <Toast.Description /> </Toast.Content> <Toast.ActionButton /> <Toast.CloseButton /> </Toast> </Toast.Provider> ``` ## Examples ### Variants ```tsx "use client"; import {HardDrive, Persons} from "@gravity-ui/icons"; import {Button, toast} from "@heroui/react"; 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={() => { const id = toast("You have been invited to join a team", { actionProps: { children: "Dismiss", onPress: () => toast.close(id), 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={() => { const id = toast.info("You have 2 credits left", { actionProps: {children: "Upgrade", onPress: () => toast.close(id)}, description: "Get a paid plan for more credits", }); }} > Accent toast </Button> <Button className="text-success-soft-foreground" size="sm" variant="tertiary" onPress={() => { const id = toast.success("You have upgraded your plan", { actionProps: { children: "Billing", className: "bg-success text-success-foreground", onPress: () => toast.close(id), }, description: "You can continue using HeroUI Chat", }); }} > Success toast </Button> <Button className="text-warning-soft-foreground" size="sm" variant="tertiary" onPress={() => { const id = toast.warning("You have no credits left", { actionProps: { children: "Upgrade", className: "bg-warning text-warning-foreground", onPress: () => toast.close(id), }, description: "Upgrade to a paid plan to continue", }); }} > Warning toast </Button> <Button size="sm" variant="danger-soft" onPress={() => { const id = toast.danger("Storage is full", { actionProps: {children: "Remove", onPress: () => toast.close(id), variant: "danger"}, description: "Remove files to release space. Adding more text to demonstrate longer content display", indicator: <HardDrive />, }); }} > Danger toast </Button> </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> ); } ``` ### Expanded Stack ```tsx "use client"; import {Button, Toast, ToastQueue} from "@heroui/react"; const queue = new ToastQueue(); export function Expanded() { return ( <div className="flex h-full max-w-xl flex-col items-center justify-center"> <Toast.Provider isExpanded aria-label="Expanded notifications" placement="bottom" queue={queue} /> <Button size="sm" variant="secondary" onPress={() => { queue.add({ title: "Simple message", variant: "default", }); setTimeout(() => { queue.add({ title: "Operation completed", variant: "success", }); }, 400); setTimeout(() => { queue.add({ title: "New update available", variant: "accent", }); }, 800); }} > Show 3 toasts </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> ); } ``` ### 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> ); } ``` ### 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-soft-foreground" variant={content.variant} /> <div className="flex flex-col pe-6"> {content.title ? ( <ToastTitle className="text-accent-soft-foreground"> {content.title} </ToastTitle> ) : null} {content.description ? ( <ToastDescription>{content.description}</ToastDescription> ) : null} </div> </div> </ToastContent> <Toast.CloseButton className="absolute end-2 top-1/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> ); } ``` ### 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.update(loadingId, "File uploaded", { description: "Your file has been uploaded successfully", variant: "success", }); }, 3000); }} > Upload with loading </Button> <Button size="sm" variant="secondary" onPress={() => { const loadingId = toast("Processing payment...", { isLoading: true, timeout: 0, }); setTimeout(() => { toast.update(loadingId, "Payment processed", { description: "Your payment has been processed successfully", variant: "success", }); }, 2500); }} > Payment processing </Button> <Button size="sm" variant="secondary" onPress={() => { const loadingId = toast("Saving changes...", { isLoading: true, timeout: 0, }); setTimeout(() => { toast.update(loadingId, "Failed to save", { description: "Please try again", variant: "danger", }); }, 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="ms-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-soft-foreground"> <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> ); } ``` ### 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-soft-foreground" size="sm" variant="secondary" onPress={() => { successQueue.add({ description: `Operation ${Date.now()}`, title: "Success!", variant: "success", }); }} > Add success (max 1) </Button> </div> </div> ); } ``` ### 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> ); } ``` ## Customization ### Tailwind CSS ```tsx "use client"; import type {ToastContentValue} from "@heroui/react"; import { Button, Toast, ToastContent, ToastDescription, ToastIndicator, ToastQueue, ToastTitle, } from "@heroui/react"; export function CustomStyles() { const queue = new ToastQueue(); return ( <div className="flex flex-col items-center gap-4"> <Toast.Provider placement="bottom" queue={queue}> {({toast: toastItem}) => { const content = toastItem.content as ToastContentValue; return ( <Toast className="rounded-xl border border-border/80 bg-surface shadow-lg ring-1 ring-black/5 dark:ring-white/10" toast={toastItem} variant={content.variant} > <ToastContent> <div className="flex items-center gap-2.5"> <ToastIndicator className="text-neutral-600 dark:text-neutral-400" variant={content.variant} /> <div className="flex flex-col gap-0.5"> {content.title ? ( <ToastTitle className="text-sm font-medium text-neutral-900 dark:text-neutral-50"> {content.title} </ToastTitle> ) : null} {content.description ? ( <ToastDescription className="text-sm text-neutral-600 dark:text-neutral-400"> {content.description} </ToastDescription> ) : null} </div> </div> </ToastContent> </Toast> ); }} </Toast.Provider> <Button size="sm" variant="secondary" onPress={() => { queue.add({ description: "Draft synced", title: "Saved", variant: "default", }); }} > Show toast </Button> </div> ); } ``` ### Global CSS To customize the Toast component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.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-button` - Close button container #### Variant Classes \[!toc] * `.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 * **Entering**: `[data-entering]` - Applied on first paint of a new toast * **Exiting**: `[data-exiting]` - Applied while a closing toast plays its exit transition * **Expanded**: `[data-expanded]` - Applied to every toast while the stack is expanded * **Hidden**: `[data-hidden]` - Applied to toasts beyond `maxVisibleToasts` ## API Reference ### Toast.Provider | 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 | | `isExpanded` | `boolean` | `false` | Force the stack into its expanded layout (does not pause timers) | | `maxVisibleToasts` | `number` | `3` | Maximum number of toasts to display at once | | `hotkey` | `string[]` | `["altKey", "KeyT"]` | Hotkey that moves focus to the toast region and expands the stack. Modifiers match `KeyboardEvent` boolean properties (e.g. `"altKey"`), other keys match `event.code` (e.g. `"KeyT"`). Modifiers you leave out must be up, so `Alt`+`T` does not also fire on `Ctrl`+`Alt`+`T`. Pass `[]` to disable | | `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 | 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 | Prop | Type | Default | Description | | ----------- | ----------- | ------- | --------------------------------------------------- | | `children` | `ReactNode` | - | Content (typically ToastTitle and ToastDescription) | | `className` | `string` | - | Additional CSS classes | ### Toast.Indicator | 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 | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `children` | `ReactNode` | - | Title text | | `className` | `string` | - | Additional CSS classes | ### Toast.Description | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `children` | `ReactNode` | - | Description text | | `className` | `string` | - | Additional CSS classes | ### Toast.ActionButton | Prop | Type | Default | Description | | ------------------ | ----------- | ------- | ---------------------------------- | | `children` | `ReactNode` | - | Action button content | | `className` | `string` | - | Additional CSS classes | | All `Button` props | - | - | Accepts all Button component props | ### Toast.CloseButton | 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 | | ------------------ | -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `exitDuration` | `number` | `300` | How long a closing toast stays mounted for its exit animation (0 removes immediately) | | `maxVisibleToasts` | `number` | `3` | Maximum number of toasts to display at once (visual only) | | `wrapUpdate` | `(fn: () => void) => void` | - | Function to wrap state updates (e.g. `document.startViewTransition`); by default updates are applied directly and animated with CSS transitions | #### Methods | Method | Parameters | Returns | Description | | ----------- | ------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `add` | `(content: T, options?: ToastOptions)` | `string` | Add a toast to the queue, returns toast key | | `update` | `(key: string, content: T, options?: {timeout?: number; onClose?: () => void})` | `boolean` | Update a toast in place, preserving its stack position; `timeout` restarts the countdown (0 keeps it open), omit it to keep the current countdown. Returns `false` if the toast no longer exists | | `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 (each toast animates out and fires its `onClose`) | | `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. The returned id lets the action close its own toast. const eventId = 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: () => toast.close(eventId), }, indicator: <CustomIcon />, }); // Update an existing toast in place (keeps its position in the stack). // Options you omit are inherited, so pass `timeout` to start a countdown // on a toast that was created persistent. const id = toast("Saving…", { timeout: 0 }); toast.update(id, "Saved", { variant: "success", timeout: 4000 }); // Promise support (automatically shows loading spinner). The loading toast // updates in place when the promise settles — same toast, same stack // position; the auto-dismiss countdown starts at that point. 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, update in place and start the auto-dismiss countdown toast.update(loadingId, "Event created", { variant: "success", timeout: 4000 }); // 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` | - | Called when the toast is dismissed, as its exit animation starts | #### 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) | ## Accessibility Each toast implements the [WAI-ARIA alertdialog pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/), grouped inside a labeled landmark region: * **Landmark region**: Toasts render in a labeled landmark reachable with `F6`; `Alt` + `T` moves focus straight to it. The hotkey is configurable via the `hotkey` prop and can be disabled by passing an empty array, and the region label can be overridden with `aria-label` * **Keyboard**: `Tab` reaches the controls of visible toasts, `Escape` collapses the expanded stack, and dismissing a focused toast moves focus to the nearest remaining toast * **Screen readers**: Each toast uses `role="alertdialog"` with its title and description linked; new toasts are announced automatically * **Timers**: Auto-dismiss pauses while the stack is hovered or focused, and while the page is in a background tab ## Related Components ## Related Components * **Button**: Allows a user to perform an action * **Alert**: Display important messages and notifications * **CloseButton**: Button for dismissing overlays </page> <page url="/en/docs/react/components/tooltip"> # Tooltip **Category**: react **URL**: https://heroui.com/en/docs/react/components/tooltip **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(overlays)/tooltip.mdx > Displays informative text when users hover over or focus on an element ## Usage ```tsx import { Tooltip } from '@heroui/react'; ``` ```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 aria-label="More information" variant="tertiary"> <CircleInfo /> </Button> <Tooltip.Content> <p>More information</p> </Tooltip.Content> </Tooltip> </div> ); } ``` ## Anatomy ```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> ) ``` ## Examples ### 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> ); } ``` ### 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> ); } ``` ### 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-soft-foreground" /> </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> ); } ``` ### Render Function ```tsx "use client"; import {CircleInfo} from "@gravity-ui/icons"; import {Button, Tooltip} from "@heroui/react"; export function RenderFunction() { 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 aria-label="More information" variant="tertiary"> <CircleInfo /> </Button> <Tooltip.Content render={(props) => <div {...props} data-custom="foo" />}> <p>More information</p> </Tooltip.Content> </Tooltip> </div> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Button, Tooltip} from "@heroui/react"; export function CustomStyles() { return ( <Tooltip delay={0}> <Button variant="secondary">Share link</Button> <Tooltip.Content className="rounded-lg border border-border/80 bg-surface px-2.5 py-1 text-xs text-foreground shadow-sm"> <p>Copied to clipboard</p> </Tooltip.Content> </Tooltip> ); } ``` ### Global CSS To customize the Tooltip component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### Global Delay Configuration The default theme sets the opening delay to `1500ms` and the closing delay to `500ms`. Override these CSS variables in your global stylesheet: ```css :root { --tooltip-delay: 1500ms; --tooltip-close-delay: 500ms; } .light, [data-theme="light"] { --tooltip-delay: 1200ms; } .dark, [data-theme="dark"] { --tooltip-close-delay: 300ms; } ``` Values support CSS time units such as `ms` and `s`. The `delay` and `closeDelay` props on an individual Tooltip override these global settings. ### 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 \[!toc] * `.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 | Prop | Type | Default | Description | | --------------------- | -------------------- | ---------------------- | --------------------------------------------------------------------------------------------- | | `children` | `React.ReactNode` | - | Trigger element and content | | `delay` | `number` | `1500` or CSS variable | Delay in milliseconds before showing tooltip; configured globally with `--tooltip-delay` | | `closeDelay` | `number` | `500` or CSS variable | Delay in milliseconds before hiding tooltip; configured globally with `--tooltip-close-delay` | | `trigger` | `"hover" \| "focus"` | `"hover"` | How the tooltip is triggered | | `isDisabled` | `boolean` | `false` | Whether the tooltip is disabled | | `shouldSkipAnimation` | `boolean` | `false` | Whether to skip the enter and exit animations when moving quickly from one tooltip to another | ### Tooltip.Content | 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 | Prop | Type | Default | Description | | ----------- | ----------------- | ------- | --------------------------------- | | `children` | `React.ReactNode` | - | Element that triggers the tooltip | | `className` | `string` | - | Additional CSS classes | ### Tooltip.Arrow | 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. | ## Related Components ## Related Components * **Button**: Allows a user to perform an action * **Popover**: Displays content in context with a trigger </page> <page url="/en/docs/react/components/autocomplete"> # Autocomplete **Category**: react **URL**: https://heroui.com/en/docs/react/components/autocomplete **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(pickers)/autocomplete.mdx > An autocomplete combines a select with filtering, allowing users to search and select from a list of options ## Usage ```tsx import { Autocomplete, useFilter } from "@heroui/react"; ``` ```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 aria-label="Search options" 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 ```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> ); ``` ## Examples ### 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 aria-label="Search options" 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 aria-label="Search options" 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 aria-label="Search options" 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 aria-label="Search options" 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> ); } ``` ### 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 aria-label="Search states" 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> ); } ``` ### 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 aria-label="Search states" 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> ); } ``` ### Required ```tsx "use client"; import { Autocomplete, Button, EmptyState, FieldError, Form, Label, ListBox, SearchField, useFilter, } from "@heroui/react"; export function Required() { const onSubmit = (e: React.SyntheticEvent<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 aria-label="Search states" 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 aria-label="Search countries" 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> ); } ``` ### 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 aria-label="Search states" 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 aria-label="Search countries" 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> ); } ``` ### 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 aria-label="Search animals" 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 aria-label="Search states" 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> ); } ``` ### 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 aria-label="Search countries" 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> ); } ``` ### 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 aria-label="Search options" 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> ); } ``` <Callout type="warning"> In multiple mode, a bare `<Autocomplete.Value />` renders a copy of each selected item's `ListBox.Item` children in the trigger, joined with locale-aware separators. Text-only items read as plain text, but visual content such as checkboxes or avatars appears once per selected item, and render function children are always called with `isSelected: false`. </Callout> To display selected values as plain text, use the `selectedText` render prop, which joins the `textValue` of each selected item: ```tsx <Autocomplete.Value> {({isPlaceholder, defaultChildren, selectedText}) => isPlaceholder ? defaultChildren : selectedText } </Autocomplete.Value> ``` For richer layouts such as removable tags, render your own content from `state.selectedItems` as shown in the example above. ### 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 aria-label="Search states" 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, useFilter} from "@heroui/react"; import {useState} from "react"; export function ControlledMultiple() { const [selected, setSelected] = useState<Key[]>(["california", "texas"]); 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"}, ]; return ( <div className="space-y-2"> <Autocomplete className="w-[256px]" placeholder="Select states" selectionMode="multiple" value={selected} onChange={(keys) => setSelected(keys as Key[])} > <Label>States</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="Search states" 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> <p className="text-sm text-muted"> Selected: {selected.length > 0 ? selected.join(", ") : "None"} </p> </div> ); } ``` ### 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 aria-label="Search states" 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 allowsEmptyCollection 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 aria-label="Search characters" 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 end-2 top-1/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> ); } ``` ### 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 aria-label="Search states" 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> ); } ``` ### Custom Value You can customize the displayed value using render props: ```tsx "use client"; import { Autocomplete, Description, EmptyState, Label, ListBox, SearchField, useFilter, } from "@heroui/react"; export function CustomValue() { const {contains} = useFilter({sensitivity: "base"}); const currencies = [ {code: "USD", id: "usd", name: "US Dollar", symbol: "$"}, {code: "EUR", id: "eur", name: "Euro", symbol: "€"}, {code: "GBP", id: "gbp", name: "British Pound", symbol: "£"}, {code: "JPY", id: "jpy", name: "Japanese Yen", symbol: "¥"}, {code: "CHF", id: "chf", name: "Swiss Franc", symbol: "₣"}, ]; return ( <Autocomplete className="w-[256px]" defaultValue="usd" placeholder="Select a currency" selectionMode="single" > <Label>Currency</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}) => { const selectedCurrency = currencies.find( (currency) => currency.id === state.selectedItems[0]?.key, ); if (isPlaceholder || !selectedCurrency) { return defaultChildren; } return ( <span className="flex min-w-0 items-center gap-1.5"> <span className="font-medium">{selectedCurrency.symbol}</span> <span>{selectedCurrency.code}</span> <span className="truncate text-muted">{selectedCurrency.name}</span> </span> ); }} </Autocomplete.Value> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="Search currencies" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search currencies..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>No results found</EmptyState>}> {currencies.map((currency) => ( <ListBox.Item key={currency.id} id={currency.id} textValue={`${currency.code} ${currency.name}`} > <div className="flex flex-col"> <Label>{currency.code}</Label> <Description>{currency.name}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### In Surface When used inside a [Surface](/docs/react/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 OnSurface() { 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-[320px] rounded-3xl p-6"> <Autocomplete className="w-full" 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 aria-label="Search states" 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> ); } ``` ### Virtualization Autocomplete supports virtualization through [Virtualizer](https://react-aria.adobe.com/Virtualizer), enabling efficient rendering of large datasets by displaying only the rows visible within the viewport. ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, Description, EmptyState, Label, ListBox, ListLayout, SearchField, Virtualizer, useFilter, } from "@heroui/react"; import {useMemo, useState} from "react"; interface User { email: string; id: number; name: string; } function generateUsers(n: number): User[] { const firstNames = [ "Emma", "Liam", "Olivia", "Noah", "Ava", "James", "Sophia", "Oliver", "Isabella", "Lucas", "Mia", "Ethan", "Charlotte", "Mason", "Amelia", "Logan", "Harper", "Alexander", "Ella", "Benjamin", ]; const lastNames = [ "Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller", "Davis", "Rodriguez", "Martinez", "Anderson", "Taylor", "Thomas", "Jackson", "White", "Harris", "Clark", "Lewis", "Robinson", "Walker", ]; const users: User[] = []; for (let i = 0; i < n; i++) { const firstName = firstNames[i % firstNames.length]!; const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length]!; const name = `${firstName} ${lastName}`; users.push({ email: `${firstName.toLowerCase()}.${lastName.toLowerCase()}@acme.com`, id: i + 1, name, }); } return users; } export function Virtualization() { const [selectedKey, setSelectedKey] = useState<Key | null>(null); const [searchQuery, setSearchQuery] = useState(""); const {contains} = useFilter({sensitivity: "base"}); const allUsers = useMemo(() => generateUsers(1000), []); const filteredUsers = useMemo(() => { if (!searchQuery) return allUsers; return allUsers.filter( (user) => contains(user.name, searchQuery) || contains(user.email, searchQuery), ); }, [allUsers, contains, searchQuery]); return ( <Autocomplete allowsEmptyCollection className="w-[300px]" placeholder="Select a user" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>User</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter inputValue={searchQuery} onInputChange={setSearchQuery}> <SearchField autoFocus aria-label="Search users" className="sticky top-0 z-10" name="search" variant="secondary" > <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="Search users..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <Virtualizer layout={ListLayout} layoutOptions={{rowHeight: 50}}> <ListBox items={filteredUsers} renderEmptyState={() => <EmptyState>No results found</EmptyState>} > {(user) => ( <ListBox.Item id={user.id} textValue={user.name}> <div className="flex flex-col"> <Label>{user.name}</Label> <Description>{user.email}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> )} </ListBox> </Virtualizer> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ## 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 aria-label="Search users" 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 aria-label="Search users" 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 aria-label="Search cities" 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 aria-label="Search tags" 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 aria-label="Search emails" 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> ); } ``` ## Customization ### Tailwind CSS ```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"; const TEAMMATES = [ {id: "sarah", name: "Sarah Chen", role: "Product Design"}, {id: "marcus", name: "Marcus Lee", role: "Engineering"}, {id: "priya", name: "Priya Patel", role: "Data Science"}, {id: "jordan", name: "Jordan Kim", role: "Customer Success"}, {id: "alex", name: "Alex Rivera", role: "Marketing"}, ] as const; export function CustomStyles() { const {contains} = useFilter({sensitivity: "base"}); const [selectedKeys, setSelectedKeys] = useState<Key[]>([]); const onRemoveTags = (keys: Set<Key>) => { setSelectedKeys((prev) => prev.filter((key) => !keys.has(key))); }; return ( <div className="w-full max-w-sm pt-6"> <Autocomplete className="w-full gap-1.5" placeholder="Search teammates..." selectionMode="multiple" value={selectedKeys} onChange={(keys) => setSelectedKeys((keys ?? []) as Key[])} > <Label className="font-medium text-foreground">Assignees</Label> <Description>People who will be notified when this task updates.</Description> <Autocomplete.Trigger className="rounded-xl border border-border/80 bg-surface shadow-sm ring-1 ring-accent/5 transition-[box-shadow,border-color] focus-within:border-accent/25 focus-within:ring-2 focus-within:ring-accent/15 dark:border-border/90 dark:bg-surface dark:ring-accent/10 dark:focus-within:border-accent/35"> <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 teammate = TEAMMATES.find((member) => member.id === selectedItemKey); if (!teammate) return null; return ( <Tag key={teammate.id} className="border border-accent/15 bg-accent/8 text-foreground dark:border-accent/25 dark:bg-accent/12" id={teammate.id} > {teammate.name} </Tag> ); })} </TagGroup.List> </TagGroup> ); }} </Autocomplete.Value> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover className="overflow-hidden rounded-xl border border-border/80 bg-surface shadow-xl ring-1 ring-black/3 dark:border-border/90 dark:bg-surface dark:ring-white/5"> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="Search by name or role" name="search" variant="secondary" > <SearchField.Group className="border-b border-separator bg-surface-secondary/50"> <SearchField.SearchIcon className="text-muted" /> <SearchField.Input placeholder="Search by name or role..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox className="p-1.5" renderEmptyState={() => <EmptyState>No teammates found</EmptyState>} > {TEAMMATES.map((teammate) => ( <ListBox.Item key={teammate.id} className="rounded-lg data-[focused=true]:bg-accent/10 data-[selected=true]:bg-accent/5 dark:data-[focused=true]:bg-accent/15 dark:data-[selected=true]:bg-accent/8" id={teammate.id} textValue={`${teammate.name} ${teammate.role}`} > <div className="flex flex-col gap-0.5"> <span className="text-sm font-medium text-foreground">{teammate.name}</span> <span className="text-xs text-muted">{teammate.role}</span> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> </div> ); } ``` ### Global CSS To customize the Autocomplete component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.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 \[!toc] * `.autocomplete--primary` - Primary variant with shadow (default) * `.autocomplete--secondary` - Secondary variant without shadow, suitable for use in surfaces #### State Classes \[!toc] * `.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 | 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 | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | ---------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Trigger content or render function | ### Autocomplete.Value | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | -------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Value content or render function | ### Autocomplete.Indicator | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom indicator content | ### Autocomplete.ClearButton | 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 | 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 | 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 | ### Render Props When using render functions with Autocomplete.Value, these values are provided: | Prop | Type | Description | | ----------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `defaultChildren` | `ReactNode` | The default rendered value. In multiple mode this is a copy of each selected item's children joined with locale-aware separators | | `isPlaceholder` | `boolean` | Whether the value is a placeholder | | `state` | `SelectState` | The state of the autocomplete. Use `state.selectedItems` for the selected collection nodes | | `selectedItems` | `(T \| null)[]` | The values of the currently selected items | | `selectedText` | `string` | The `textValue` of the selected items joined with locale-aware separators | ## 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). ## Related Components ## 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 </page> <page url="/en/docs/react/components/combo-box"> # ComboBox **Category**: react **URL**: https://heroui.com/en/docs/react/components/combo-box **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/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 ## Usage ```tsx import { ComboBox } from '@heroui/react'; ``` ```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 ```tsx import { ComboBox, Input, Label, Description, Header, ListBox, Separator } from '@heroui/react'; export default () => ( <ComboBox> <Label /> <ComboBox.InputGroup> <Input /> <ComboBox.Trigger /> </ComboBox.InputGroup> {/* Displays the selected values, primarily used for multiple selection */} <ComboBox.Value /> <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> ) ``` ## Examples ### 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> ); } ``` ### 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> ); } ``` ### Required ```tsx "use client"; import {Button, ComboBox, FieldError, Form, Input, Label, ListBox} from "@heroui/react"; export function Required() { const onSubmit = (e: React.SyntheticEvent<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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> <ChevronsExpandVertical className="size-3" /> </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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### Render Function ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function RenderFunction() { 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> ); } ``` ### 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> ); } ``` ### Form Value Use the `formValue` prop to control whether the selected item's key or text is submitted in forms. `key` is the default. When `allowsCustomValue` is true, the text is always submitted. ```tsx "use client"; import { Button, ComboBox, Description, FieldError, Form, Input, Label, ListBox, } from "@heroui/react"; import {useState} from "react"; const animals = [ {id: "aardvark", name: "Aardvark"}, {id: "cat", name: "Cat"}, {id: "dog", name: "Dog"}, {id: "kangaroo", name: "Kangaroo"}, {id: "panda", name: "Panda"}, {id: "snake", name: "Snake"}, ]; export function FormValue() { const [message, setMessage] = useState<string | null>(null); return ( <Form className="flex w-[256px] flex-col gap-4" onSubmit={(e) => { e.preventDefault(); const formData = new FormData(e.currentTarget); setMessage(`Key: ${formData.get("animal")}. Text: ${formData.get("animal-text")}.`); }} > <ComboBox isRequired className="w-full" formValue="key" name="animal"> <Label>Animal</Label> <ComboBox.InputGroup> <Input placeholder="Select an animal..." /> <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> <Description>Submits the selected key</Description> <FieldError /> </ComboBox> <ComboBox isRequired className="w-full" formValue="text" name="animal-text"> <Label>Animal (text)</Label> <ComboBox.InputGroup> <Input placeholder="Select an animal..." /> <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> <Description>Submits the selected text</Description> <FieldError /> </ComboBox> <Button className="w-fit" type="submit"> Submit </Button> {!!message && <p className="text-sm text-muted">{message}</p>} </Form> ); } ``` ### Validation Behavior Use the `validationBehavior` prop to control how validation is displayed: * `native` (default): blocks form submission when the value is missing or invalid * `aria`: shows errors in realtime and does not block submission ```tsx "use client"; import { Button, ComboBox, Description, FieldError, Form, Input, Label, ListBox, } from "@heroui/react"; import {useState} from "react"; const animals = [ {id: "aardvark", name: "Aardvark"}, {id: "cat", name: "Cat"}, {id: "dog", name: "Dog"}, {id: "kangaroo", name: "Kangaroo"}, {id: "panda", name: "Panda"}, {id: "snake", name: "Snake"}, ]; export function ValidationBehavior() { const [nativeMessage, setNativeMessage] = useState<string | null>(null); const [ariaMessage, setAriaMessage] = useState<string | null>(null); return ( <div className="flex flex-col gap-8"> <Form className="flex w-[256px] flex-col gap-4" onSubmit={(e) => { e.preventDefault(); setNativeMessage("Submitted with native validation."); }} > <ComboBox isRequired className="w-full" name="animal" validationBehavior="native"> <Label>Animal (native)</Label> <ComboBox.InputGroup> <Input placeholder="Select an animal..." /> <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> <Description>Blocks submission when the value is missing</Description> <FieldError /> </ComboBox> <Button className="w-fit" type="submit"> Submit </Button> {!!nativeMessage && <p className="text-sm text-muted">{nativeMessage}</p>} </Form> <Form className="flex w-[256px] flex-col gap-4" onSubmit={(e) => { e.preventDefault(); setAriaMessage("Submitted with ARIA validation."); }} > <ComboBox isRequired className="w-full" name="animal-aria" validationBehavior="aria"> <Label>Animal (ARIA)</Label> <ComboBox.InputGroup> <Input placeholder="Select an animal..." /> <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> <Description>Shows errors in realtime and does not block submission</Description> <FieldError /> </ComboBox> <Button className="w-fit" type="submit"> Submit </Button> {!!ariaMessage && <p className="text-sm text-muted">{ariaMessage}</p>} </Form> </div> ); } ``` ### Custom Validation Use the `validate` prop to return an error message when the value is invalid, or `true` when it is valid. ```tsx "use client"; import {Button, ComboBox, FieldError, Form, Input, Label, ListBox} from "@heroui/react"; const animals = [ {id: "aardvark", name: "Aardvark"}, {id: "cat", name: "Cat"}, {id: "dog", name: "Dog"}, {id: "kangaroo", name: "Kangaroo"}, {id: "panda", name: "Panda"}, {id: "snake", name: "Snake"}, ]; export function CustomValidation() { return ( <Form className="flex w-[256px] flex-col gap-4" onSubmit={(e) => { e.preventDefault(); alert("Form submitted successfully!"); }} > <ComboBox isRequired className="w-full" name="animal" validate={(value) => { if (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> {animals.map((animal) => ( <ListBox.Item key={animal.id} id={animal.id} textValue={animal.name}> {animal.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </ComboBox.Popover> <FieldError /> </ComboBox> <Button className="w-fit" type="submit"> Submit </Button> </Form> ); } ``` ### Read Only Use the `isReadOnly` prop to make the ComboBox read-only. The selected value can be focused, but it cannot be changed. ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; const animals = [ {id: "aardvark", name: "Aardvark"}, {id: "cat", name: "Cat"}, {id: "dog", name: "Dog"}, {id: "kangaroo", name: "Kangaroo"}, {id: "panda", name: "Panda"}, {id: "snake", name: "Snake"}, ]; export function ReadOnly() { return ( <ComboBox isReadOnly className="w-[256px]" defaultSelectedKey="cat"> <Label>Favorite Animal</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> ); } ``` ### Multiple Selection Set `selectionMode="multiple"` to allow selecting more than one option. In multiple selection mode, use `ComboBox.Value` to display the selected items and pass `selectionMode="multiple"` to the inner `ListBox` as well. Selection is controlled with the `value` / `defaultValue` (`Key[]`) props and the `onChange` handler. ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function MultipleSelection() { return ( <ComboBox className="w-[256px]" selectionMode="multiple"> <Label>Favorite Animals</Label> <ComboBox.InputGroup> <Input placeholder="Search animals..." /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Value placeholder="No animals selected" /> <ComboBox.Popover> <ListBox selectionMode="multiple"> <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> ); } ``` ### In Surface When used inside a [Surface](/docs/react/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.SyntheticEvent<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" variant="secondary"> <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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {ComboBox, Input, Label, ListBox} from "@heroui/react"; const itemClass = "rounded-lg data-[focused=true]:bg-muted/70 data-[selected=true]:font-medium data-[selected=true]:text-foreground"; export function CustomStyles() { return ( <ComboBox className="w-64 gap-1.5"> <Label className="font-medium text-neutral-800 dark:text-neutral-100">Framework</Label> <ComboBox.InputGroup className="rounded-xl border border-border/80 bg-surface shadow-sm ring-1 ring-black/5 transition-[box-shadow,border-color] focus-within:ring-2 focus-within:ring-neutral-400/25 dark:ring-white/10 dark:focus-within:ring-neutral-500/30"> <Input placeholder="Search..." /> <ComboBox.Trigger className="text-muted" /> </ComboBox.InputGroup> <ComboBox.Popover className="rounded-xl border border-border/80 bg-surface p-1 shadow-lg ring-1 ring-black/5 dark:ring-white/10"> <ListBox> <ListBox.Item className={itemClass} id="react" textValue="React"> React <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item className={itemClass} id="vue" textValue="Vue"> Vue <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item className={itemClass} id="svelte" textValue="Svelte"> Svelte <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### Global CSS To customize the ComboBox component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.combo-box` - Base ComboBox container * `.combo-box__input-group` - Container for the input and trigger button * `.combo-box__value` - The selected value display (used in multiple selection) * `.combo-box__trigger` - The button that triggers the popover * `.combo-box__popover` - The popover container #### State Classes \[!toc] * `.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 | 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 | | `selectionMode` | `"single" \| "multiple"` | `"single"` | Whether single or multiple selection is enabled | | `selectedKey` | `Key \| null` | - | Current selected key (controlled, single selection) | | `defaultSelectedKey` | `Key \| null` | - | Default selected key (uncontrolled, single selection) | | `onSelectionChange` | `(key: Key \| null) => void` | - | Handler called when the selection changes (single selection) | | `value` | `Key \| null \| Key[]` | - | The currently selected keys (controlled). `Key[]` when `selectionMode="multiple"` | | `defaultValue` | `Key \| null \| Key[]` | - | The initial selected keys (uncontrolled). `Key[]` when `selectionMode="multiple"` | | `onChange` | `(value: Key \| null \| Key[]) => void` | - | Handler called when the selection 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 | | `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` | - | ComboBox content or render function | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ComboBoxRenderProps>` | - | Overrides the default DOM element with a custom render function. | ### ComboBox.InputGroup | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | InputGroup content | ### ComboBox.Value Renders the selected values of a ComboBox, or a placeholder if no value is selected. By default the selected items are rendered as a comma separated list. Use the render function to customize this (for example, to display tags). | Prop | Type | Default | Description | | ------------- | -------------------------------------------------------------- | ------- | ---------------------------------------------- | | `placeholder` | `ReactNode` | - | A value to display when no items are selected | | `className` | `string \| (values: ComboBoxValueRenderProps) => string` | - | Additional CSS classes | | `children` | `ReactNode \| (values: ComboBoxValueRenderProps) => ReactNode` | - | Custom render function for the selected values | ### ComboBox.Trigger | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ---------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom trigger content | ### ComboBox.Popover | 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 | ### Render Props 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 | ## 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). ## Related Components ## 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 </page> <page url="/en/docs/react/components/select"> # Select **Category**: react **URL**: https://heroui.com/en/docs/react/components/select **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(pickers)/select.mdx > A select displays a collapsible list of options and allows a user to select one of them ## Usage ```tsx import { Select } from "@heroui/react"; ``` ```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 ```tsx import {Select, Label, Description, Header, ListBox, Separator} from "@heroui/react"; export default () => ( <Select> <Label /> <Select.Trigger> <Select.Value /> <Select.ClearButton /> <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> ); ``` ## Examples ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### Required ```tsx "use client"; import {Button, FieldError, Form, Label, ListBox, Select} from "@heroui/react"; export function Required() { const onSubmit = (e: React.SyntheticEvent<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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### Controlled ```tsx "use client"; import type {Key} from "@heroui/react"; 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> ); } ``` ### 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> ); } ``` ### With Clear Button `Select.Trigger` is a button, so a nested `<button>` cannot be used for clear. Compose `Select.ClearButton` inside the trigger instead — it renders as a non-button control and does not open the menu. ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function WithClearButton() { return ( <Select className="w-[256px]" defaultValue="california" placeholder="Select one"> <Label>State</Label> <Select.Trigger> <Select.Value /> <Select.ClearButton /> <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> ); } ``` Because ARIA treats the children of a button as presentational, the clear control cannot take focus. It is therefore `aria-hidden` and acts as a pointer affordance only. When a `Select.ClearButton` is composed, the trigger also clears on `Backspace` or `Delete`, which is how keyboard and screen reader users clear the selection. Both paths call `onClear`. ### 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> ); } ``` ### Render Function ```tsx "use client"; import {Label, ListBox, Select} from "@heroui/react"; export function RenderFunction() { 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> ); } ``` ### In Surface When used inside a [Surface](/docs/react/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.SyntheticEvent<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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Label, ListBox, Select} from "@heroui/react"; const itemClass = "rounded-lg data-[focused=true]:bg-accent/10 data-[selected=true]:text-foreground"; export function CustomStyles() { return ( <Select className="w-56" placeholder="Pick a plan" variant="secondary"> <Label className="font-medium text-foreground">Plan</Label> <Select.Trigger className="rounded-xl bg-default"> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover className="rounded-xl border border-border bg-surface p-1 shadow-lg"> <ListBox> <ListBox.Item className={itemClass} id="free" textValue="Free"> Free <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item className={itemClass} id="pro" textValue="Pro"> Pro <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ### Global CSS To customize the Select component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.select` - Base select container * `.select__trigger` - The button that triggers the select * `.select__value` - The displayed value or placeholder * `.select__clear-button` - The optional clear control inside the trigger * `.select__indicator` - The dropdown indicator icon * `.select__popover` - The popover container #### Variant Classes \[!toc] * `.select--primary` - Primary variant with shadow (default) * `.select--secondary` - Secondary variant without shadow, suitable for use in surfaces #### State Classes \[!toc] * `.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__clear-button[data-empty="true"]` - Clear button hidden when no selection * `.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 | 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 | | `onClear` | `() => void` | - | Handler called when the selection is cleared | | `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 | Prop | Type | Default | Description | | ----------- | ----------------------------- | ------- | ---------------------------------- | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode \| RenderFunction` | - | Trigger content or render function | ### Select.Value | 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 | Prop | Type | Default | Description | | ----------- | ----------- | ------- | ------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom indicator content | ### Select.ClearButton | Prop | Type | Default | Description | | ----------- | ------------------------- | ------- | ------------------------------------------ | | `className` | `string` | - | Additional CSS classes | | `children` | `ReactNode` | - | Custom content, replacing the default icon | | `onClick` | `(e: MouseEvent) => void` | - | Handler called when the control is clicked | `Select.ClearButton` renders as a `span` so it can live inside `Select.Trigger` (a button) without nesting buttons. It is visually hidden when the selection is empty. ### Select.Popover | 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 | ### Render Props 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). ## Related Components ## Related Components * **Listbox**: Scrollable list of selectable items * **Popover**: Displays content in context with a trigger * **Label**: Accessible label for form controls </page> <page url="/en/docs/react/components/kbd"> # Kbd **Category**: react **URL**: https://heroui.com/en/docs/react/components/kbd **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(typography)/kbd.mdx > Display keyboard shortcuts and key combinations ## Usage ```tsx import { Kbd } from "@heroui/react"; ``` ```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 ```tsx import { Kbd } from "@heroui/react"; export default () => ( <Kbd> <Kbd.Abbr title="Command">⌘</Kbd.Abbr> <Kbd.Content>K</Kbd.Content> </Kbd> ); ``` ## Examples ### 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> ); } ``` ### 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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {Kbd} from "@heroui/react"; export function CustomStyles() { return ( <div className="flex items-center gap-3"> <Kbd className="rounded-lg bg-accent-soft px-2.5 text-accent-soft-foreground"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>K</Kbd.Content> </Kbd> <Kbd className="rounded-lg bg-default px-2.5 text-muted"> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>P</Kbd.Content> </Kbd> </div> ); } ``` ### Global CSS To customize the Kbd component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.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 | 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 | 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 | 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` | | ## Related Components </page> <page url="/en/docs/react/components/typography"> # Typography **Category**: react **URL**: https://heroui.com/en/docs/react/components/typography **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(typography)/typography.mdx > A semantic typography primitive for headings, body copy, and inline code built on React Aria Components Text. ## Usage ```tsx import {Typography} from "@heroui/react"; ``` ```tsx import {Typography} from "@heroui/react"; export const Default = () => { return ( <div className="flex max-w-xl flex-col gap-4"> <Typography type="h1">Build better interfaces</Typography> <Typography type="h2">Typography that stays semantic</Typography> <Typography type="h3">Composable by default</Typography> <Typography type="h4">Small heading</Typography> <Typography> HeroUI Typography uses React Aria Components Text as the primitive, with semantic typography types and render-prop polymorphism. </Typography> <Typography color="muted" type="body-sm"> Smaller muted body copy for secondary descriptions. </Typography> <Typography type="code">pnpm add @heroui/react</Typography> </div> ); }; ``` ## Anatomy `Typography` maps visual `type` values to semantic elements by default. ```tsx import {Typography} from "@heroui/react"; export default () => ( <Typography type="h1">Heading</Typography> ); ``` ## Examples ### Scale ```tsx import {Typography} from "@heroui/react"; const scale = [ { label: "h1", meta: "36px / 600 / 1.11 / tight", sample: "Build better interfaces", type: "h1" as const, }, { label: "h2", meta: "30px / 600 / 1.17 / tight", sample: "Built for the intelligence age", type: "h2" as const, }, { label: "h3", meta: "24px / 600 / 1.25 / tight", sample: "Pricing on your terms", type: "h3" as const, }, { label: "h4", meta: "20px / 600 / 1.33 / tight", sample: "Apply to the startup program", type: "h4" as const, }, { label: "h5", meta: "18px / 600 / 1.39 / tight", sample: "Card titles", type: "h5" as const, }, { label: "h6", meta: "16px / 600 / 1.50 / tight", sample: "Smaller feature headers", type: "h6" as const, }, { label: "body", meta: "16px / 400 / 1.75", sample: "Primary body text used across documentation, marketing copy, and descriptions.", type: "body" as const, }, { label: "body-sm", meta: "14px / 400 / 1.50", sample: "Secondary body, table cells, navigation, and sidebar items.", type: "body-sm" as const, }, { label: "body-xs", meta: "12px / 400 / 1.25", sample: "Captions, badges, helper text, and fine print.", type: "body-xs" as const, }, { label: "code", meta: "14px / mono", sample: "pnpm add @heroui/react", type: "code" as const, }, ] as const; export const TypographyScale = () => { return ( <div className="flex w-full flex-col divide-y divide-border"> {scale.map((row) => ( <div key={row.label} className="grid grid-cols-[160px_1fr] items-center gap-8 py-5"> <div className="flex shrink-0 flex-col gap-0.5"> <span className="text-sm font-semibold text-foreground">{row.label}</span> <span className="text-xs whitespace-nowrap text-muted">{row.meta}</span> </div> <Typography type={row.type}>{row.sample}</Typography> </div> ))} </div> ); }; ``` ### Primitives ```tsx import {Typography} from "@heroui/react"; export const Primitives = () => { return ( <div className="flex max-w-xl flex-col gap-4"> <Typography.Heading level={1}>Dashboard</Typography.Heading> <Typography.Paragraph> Convenience primitives are thin wrappers over Typography, so you can choose explicit composition without learning a second styling system. </Typography.Paragraph> <Typography.Paragraph color="muted" size="sm"> Paragraph supports base, sm, and xs sizes. </Typography.Paragraph> <Typography.Code>Typography.Code</Typography.Code> </div> ); }; ``` * `Typography.Heading` maps `level={1..6}` to `type="h1"` through `type="h6"`. * `Typography.Paragraph` maps `size="base" | "sm" | "xs"` to body text styles. * `Typography.Code` maps to the inline code style. * `Typography.Prose` styles rich content passed as regular HTML children. ### Prose ```tsx import {Typography} from "@heroui/react"; export const Prose = () => { return ( <Typography.Prose className="flex max-w-xl flex-col gap-3"> <h1>Prose title</h1> <p> Prose is for authored content where the markup is already semantic and HeroUI applies the default typography rhythm. </p> <h2>Section title</h2> <p> Inline code like <code>render</code> receives the same code treatment as the Typography primitive. </p> </Typography.Prose> ); }; ``` ### Render Props ```tsx "use client"; import {Typography} from "@heroui/react"; export const RenderProps = () => { return ( <div className="flex max-w-xl flex-col gap-4"> <Typography render={({children, ...domProps}) => <h2 {...domProps}>{children}</h2>} type="h1"> H1 visual style, h2 semantic element </Typography> <Typography render={({children, ...domProps}) => <span {...domProps}>{children}</span>}> The render prop can swap the underlying element while preserving HeroUI props and styles. </Typography> </div> ); }; ``` Use the React Aria Components-style `render` prop when you need to customize the rendered element. ## Customization ### Tailwind CSS ```tsx import {Typography} from "@heroui/react"; export function CustomStyles() { return ( <div className="flex max-w-md flex-col gap-2 rounded-xl border border-border/80 bg-surface-secondary p-4"> <Typography className="text-xs font-medium tracking-wide text-accent uppercase" type="body-xs" > Changelog </Typography> <Typography className="font-semibold tracking-tight text-foreground" type="h4"> Faster search results </Typography> <Typography className="text-sm leading-relaxed text-muted" type="body-sm"> Queries now return in under 200ms thanks to an improved index. </Typography> </div> ); } ``` ### Global CSS To customize the Typography component classes, you can use the `@layer components` directive. [Learn more](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes). ```css @layer components { .typography--h1 { @apply font-extrabold tracking-tight; } .typography--code { @apply rounded-md bg-default-100 font-mono dark:bg-default-50/20; } } ``` ## Styling Reference HeroUI follows the [BEM](https://getbem.com/) methodology to ensure component variants and states are reusable and easy to customize. ### CSS Classes The Typography component uses these CSS classes ([View source styles](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/typography.css)): #### Base Classes \[!toc] * `.typography` - Base typography primitive * `.typography-prose` - Rich prose container #### Type Classes \[!toc] * `.typography--h1` through `.typography--h6` * `.typography--body`, `.typography--body-sm`, `.typography--body-xs` * `.typography--code` #### Modifier Classes \[!toc] * `.typography--align-start`, `.typography--align-center`, `.typography--align-end`, `.typography--align-justify` * `.typography--color-default`, `.typography--color-muted` * `.typography--truncate` * `.typography--weight-normal`, `.typography--weight-medium`, `.typography--weight-semibold`, `.typography--weight-bold` ## API Reference ### Typography | Prop | Type | Default | Description | | ---------- | -------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------- | | `type` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'body' \| 'body-sm' \| 'body-xs' \| 'code'` | `'body'` | Semantic typography style. | | `align` | `'start' \| 'center' \| 'end' \| 'justify'` | `'start'` | Text alignment. | | `color` | `'default' \| 'muted'` | `'default'` | Text color. | | `weight` | `'normal' \| 'medium' \| 'semibold' \| 'bold'` | - | Font weight override. | | `truncate` | `boolean` | - | Truncates the text to one line with ellipsis. | | `render` | `DOMRenderFunction` | - | Custom render function from React Aria. | | `children` | `ReactNode` | - | Text content. | ## Related Components </page> <page url="/en/docs/react/components/scroll-shadow"> # ScrollShadow **Category**: react **URL**: https://heroui.com/en/docs/react/components/scroll-shadow **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/en/react/components/(utilities)/scroll-shadow.mdx > Apply visual shadows to indicate scrollable content overflow with automatic detection of scroll position. ## Usage ```tsx import { ScrollShadow } from "@heroui/react"; ``` ```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> ); } ``` ## Examples ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ### 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> ); } ``` ## Customization ### Tailwind CSS ```tsx import {ScrollShadow} from "@heroui/react"; const entries = [ "Reviewed quarterly goals with the design team.", "Shipped dark mode tokens to production.", "Merged accessibility fixes for form fields.", "Published updated component documentation.", "Scheduled performance audit for next sprint.", "Added scroll shadow demos to the docs site.", ]; export function CustomStyles() { return ( <div className="w-full sm:max-w-sm"> <ScrollShadow hideScrollBar className="max-h-48 rounded-xl border border-border/80 bg-linear-to-b from-neutral-50/90 to-white p-4 ring-1 ring-black/5 dark:from-neutral-900/80 dark:to-neutral-900 dark:ring-white/10" size={48} variant="fade" > <div className="space-y-3"> {entries.map((entry) => ( <p key={entry} className="text-sm leading-relaxed text-neutral-600 dark:text-neutral-400" > {entry} </p> ))} </div> </ScrollShadow> </div> ); } ``` ### Global CSS To customize the ScrollShadow component classes, you can use the `@layer components` directive. [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; } } ``` ## Styling Reference 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 \[!toc] * `.scroll-shadow` - Root container element #### Orientation Variants \[!toc] * `.scroll-shadow--vertical` - Vertical scrolling (default) * `.scroll-shadow--horizontal` - Horizontal scrolling #### State Modifiers \[!toc] * `.scroll-shadow--hide-scrollbar` - Hides native scrollbar ### CSS Variables The ScrollShadow component uses CSS variables to size the fade mask and reserve space for visible native scrollbars: | Variable | Default | Description | | -------------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- | | `--scroll-shadow-size` | `40px` | Controls the fade gradient size. This is set from the `size` prop. | | `--scroll-shadow-offset` | `0px` | How far the container must be scrolled before the fade starts. This is set from the `offset` prop. | | `--scroll-shadow-scrollbar-size` | `10px` (`0px` when `hideScrollBar`) | Reserves a solid mask gutter for the native scrollbar so the fade does not cover it. Override for wider scrollbars. | ### 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 * **Shadow Mode**: `[data-scroll-shadow-mode]` - `"auto"` when the fade is derived from the scroll position, `"manual"` when `visibility` is controlled or `isEnabled` is `false` ### Scroll-Driven Fade In `auto` mode, browsers that support [scroll-driven animations](https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline) derive the fade from the scroll position in CSS. The mask is therefore correct on the very first paint, with no measurement and no flash of unfaded content during hydration. Browsers without support fall back to the `[data-*-scroll]` attributes above, which are written after hydration. Two things to keep in mind when customizing: * In `auto` mode the root always resolves a `mask-image`, even when there is nothing to scroll. That makes it a stacking context and a containing block for `position: fixed` descendants. Set `visibility` explicitly if you need to opt out. * The scroll-driven fade uses the `animation` property on the root. Applying an `animate-*` utility to the same element replaces it and leaves no fade. Animate a wrapper instead. ## 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 | ## Related Components </page> <page url="/cn/docs/react/components/button-group"> # ButtonGroup 按钮组 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/button-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(buttons)/button-group.mdx > 将相关按钮组合在一起，保持一致的样式与间距 ## 用法 ```tsx import { ButtonGroup, Button } from '@heroui/react'; ``` ```tsx import { ChevronDown, ChevronLeft, ChevronRight, CodeFork, Ellipsis, Picture, Pin, QrCode, Star, TextAlignCenter, TextAlignJustify, TextAlignLeft, TextAlignRight, ThumbsDown, ThumbsUp, Video, } from "@gravity-ui/icons"; import {Button, ButtonGroup, Chip, Description, Dropdown, Label} from "@heroui/react"; export function Basic() { return ( <div className="flex flex-col items-start gap-6"> {/* 单个按钮与下拉菜单 */} <div className="flex flex-col gap-2"> <ButtonGroup> <Button>合并拉取请求</Button> <Dropdown> <Button isIconOnly aria-label="更多选项"> <ButtonGroup.Separator /> <ChevronDown /> </Button> <Dropdown.Popover className="max-w-[290px]" placement="bottom end"> <Dropdown.Menu> <Dropdown.Item className="flex flex-col items-start gap-1" id="merge" textValue="创建合并提交" > <Label>创建合并提交</Label> <Description>此分支上的所有提交都将加入基础分支</Description> </Dropdown.Item> <Dropdown.Item className="flex flex-col items-start gap-1" id="squash-and-merge" textValue="压缩并合并" > <Label>压缩并合并</Label> <Description>此分支上的 14 个提交将合并为一次提交并加入基础分支</Description> </Dropdown.Item> <Dropdown.Item className="flex flex-col items-start gap-1" id="rebase-and-merge" textValue="变基并合并" > <Label>变基并合并</Label> <Description>此分支上的 14 个提交将变基后加入基础分支</Description> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> </ButtonGroup> </div> {/* 独立按钮 */} <div className="flex flex-col gap-2"> <div className="flex flex-wrap gap-x-2 gap-y-4"> <ButtonGroup variant="tertiary"> <Button> <CodeFork className="size-3.5" /> 复刻 <Chip color="accent" size="sm" variant="soft"> 24 </Chip> </Button> <Button isIconOnly aria-label="更多复刻选项"> <ButtonGroup.Separator /> <ChevronDown /> </Button> </ButtonGroup> <ButtonGroup variant="tertiary"> <Button isIconOnly aria-label="显示二维码"> <QrCode /> </Button> <Button> <ButtonGroup.Separator /> 扫码支付 </Button> </ButtonGroup> <ButtonGroup variant="tertiary"> <Button> <ThumbsUp /> <span className="text-xs font-semibold">2.4K</span> </Button> <Button isIconOnly aria-label="点踩"> <ButtonGroup.Separator /> <ThumbsDown /> </Button> </ButtonGroup> <ButtonGroup variant="tertiary"> <Button> <Star className="size-3.5" /> 星标 </Button> <Button className="px-2"> <ButtonGroup.Separator /> <Chip color="accent" size="sm" variant="soft"> 104 </Chip> </Button> </ButtonGroup> <ButtonGroup variant="tertiary"> <Button> <Pin /> 已置顶 </Button> <Button isIconOnly aria-label="更多置顶选项"> <ButtonGroup.Separator /> <ChevronDown /> </Button> </ButtonGroup> </div> </div> {/* 上一页 / 下一页 */} <div className="flex flex-col gap-2"> <ButtonGroup variant="tertiary"> <Button> <ChevronLeft /> 上一页 </Button> <Button> <ButtonGroup.Separator /> 下一页 <ChevronRight /> </Button> </ButtonGroup> </div> {/* 内容类型选择 */} <div className="flex flex-col gap-2"> <ButtonGroup variant="tertiary"> <Button> <Picture /> 照片 </Button> <Button> <ButtonGroup.Separator /> <Video /> 视频 </Button> <Button isIconOnly aria-label="更多选项"> <ButtonGroup.Separator /> <Ellipsis /> </Button> </ButtonGroup> </div> {/* 文本对齐 */} <div className="flex flex-col gap-2"> <ButtonGroup variant="tertiary"> <Button>左对齐</Button> <Button> <ButtonGroup.Separator /> 居中 </Button> <Button> <ButtonGroup.Separator /> 右对齐 </Button> </ButtonGroup> </div> {/* 仅图标：对齐 */} <div className="flex flex-col gap-2"> <ButtonGroup variant="tertiary"> <Button isIconOnly aria-label="左对齐"> <TextAlignLeft /> </Button> <Button isIconOnly aria-label="居中对齐"> <ButtonGroup.Separator /> <TextAlignCenter /> </Button> <Button isIconOnly aria-label="右对齐"> <ButtonGroup.Separator /> <TextAlignRight /> </Button> <Button isIconOnly aria-label="两端对齐"> <ButtonGroup.Separator /> <TextAlignJustify /> </Button> </ButtonGroup> </div> </div> ); } ``` ## 组件结构 ```tsx import { ButtonGroup, Button } from '@heroui/react'; export default () => ( <ButtonGroup> <Button>First</Button> <Button> <ButtonGroup.Separator /> Second </Button> <Button> <ButtonGroup.Separator /> Third </Button> </ButtonGroup> ); ``` > **ButtonGroup** 将多个 Button 组合在一起，应用一致的样式、间距与自动圆角处理。它通过 React Context 向所有子按钮传递 `size`、`variant` 与 `isDisabled` 属性。 ## 示例 ### 变体 ```tsx import {Button, ButtonGroup} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-6"> <div className="flex flex-col gap-2"> <p className="text-sm text-muted">主要</p> <ButtonGroup variant="primary"> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button> <ButtonGroup.Separator /> 第三项 </Button> </ButtonGroup> </div> <div className="flex flex-col gap-2"> <p className="text-sm text-muted">次要</p> <ButtonGroup variant="secondary"> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button> <ButtonGroup.Separator /> 第三项 </Button> </ButtonGroup> </div> <div className="flex flex-col gap-2"> <p className="text-sm text-muted">第三</p> <ButtonGroup variant="tertiary"> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button> <ButtonGroup.Separator /> 第三项 </Button> </ButtonGroup> </div> <div className="flex flex-col gap-2"> <p className="text-sm text-muted">线框</p> <ButtonGroup variant="outline"> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button> <ButtonGroup.Separator /> 第三项 </Button> </ButtonGroup> </div> <div className="flex flex-col gap-2"> <p className="text-sm text-muted">幽灵</p> <ButtonGroup variant="ghost"> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button> <ButtonGroup.Separator /> 第三项 </Button> </ButtonGroup> </div> <div className="flex flex-col gap-2"> <p className="text-sm text-muted">危险</p> <ButtonGroup variant="danger"> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button> <ButtonGroup.Separator /> 第三项 </Button> </ButtonGroup> </div> </div> ); } ``` ### 尺寸 ```tsx import {Button, ButtonGroup} from "@heroui/react"; export function Sizes() { return ( <div className="flex flex-col gap-4"> <div className="flex flex-col items-start gap-2"> <p className="text-sm text-muted">小</p> <ButtonGroup size="sm" variant="secondary"> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button> <ButtonGroup.Separator /> 第三项 </Button> </ButtonGroup> </div> <div className="flex flex-col items-start gap-2"> <p className="text-sm text-muted">中（默认）</p> <ButtonGroup size="md" variant="secondary"> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button> <ButtonGroup.Separator /> 第三项 </Button> </ButtonGroup> </div> <div className="flex flex-col items-start gap-2"> <p className="text-sm text-muted">大</p> <ButtonGroup size="lg" variant="secondary"> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button> <ButtonGroup.Separator /> 第三项 </Button> </ButtonGroup> </div> </div> ); } ``` ### 方向 使用 `orientation` 属性可水平或垂直排列按钮。 ```tsx import {TextAlignCenter, TextAlignJustify, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons"; import {Button, ButtonGroup} from "@heroui/react"; export function Orientation() { return ( <div className="flex items-start gap-8"> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">横向</span> <ButtonGroup orientation="horizontal" variant="tertiary"> <Button isIconOnly aria-label="左对齐"> <TextAlignLeft /> </Button> <Button isIconOnly aria-label="居中对齐"> <ButtonGroup.Separator /> <TextAlignCenter /> </Button> <Button isIconOnly aria-label="右对齐"> <ButtonGroup.Separator /> <TextAlignRight /> </Button> <Button isIconOnly aria-label="两端对齐"> <ButtonGroup.Separator /> <TextAlignJustify /> </Button> </ButtonGroup> </div> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">纵向</span> <ButtonGroup orientation="vertical" variant="tertiary"> <Button isIconOnly aria-label="左对齐"> <TextAlignLeft /> </Button> <Button isIconOnly aria-label="居中对齐"> <ButtonGroup.Separator /> <TextAlignCenter /> </Button> <Button isIconOnly aria-label="右对齐"> <ButtonGroup.Separator /> <TextAlignRight /> </Button> <Button isIconOnly aria-label="两端对齐"> <ButtonGroup.Separator /> <TextAlignJustify /> </Button> </ButtonGroup> </div> </div> ); } ``` ### 带图标 ```tsx import {Globe, Plus, TrashBin} from "@gravity-ui/icons"; import {Button, ButtonGroup} from "@heroui/react"; export function WithIcons() { return ( <div className="flex flex-col gap-6"> <div className="flex flex-col items-start gap-2"> <p className="text-sm text-muted">带图标</p> <ButtonGroup variant="secondary"> <Button> <Globe /> 搜索 </Button> <Button> <ButtonGroup.Separator /> <Plus /> 添加 </Button> <Button> <ButtonGroup.Separator /> <TrashBin /> 删除 </Button> </ButtonGroup> </div> <div className="flex flex-col items-start gap-2"> <p className="text-sm text-muted">仅图标按钮</p> <ButtonGroup variant="tertiary"> <Button isIconOnly aria-label="搜索"> <Globe /> </Button> <Button isIconOnly aria-label="添加"> <ButtonGroup.Separator /> <Plus /> </Button> <Button isIconOnly aria-label="删除"> <ButtonGroup.Separator /> <TrashBin /> </Button> </ButtonGroup> </div> </div> ); } ``` ### 宽度充满 ```tsx import {TextAlignCenter, TextAlignLeft, TextAlignRight} from "@gravity-ui/icons"; import {Button, ButtonGroup} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-3"> <ButtonGroup fullWidth> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button> <ButtonGroup.Separator /> 第三项 </Button> </ButtonGroup> <ButtonGroup fullWidth> <Button isIconOnly aria-label="左对齐"> <TextAlignLeft /> </Button> <Button isIconOnly aria-label="居中对齐"> <ButtonGroup.Separator /> <TextAlignCenter /> </Button> <Button isIconOnly aria-label="右对齐"> <ButtonGroup.Separator /> <TextAlignRight /> </Button> </ButtonGroup> </div> ); } ``` ### 禁用状态 ```tsx import {Button, ButtonGroup} from "@heroui/react"; export function Disabled() { return ( <div className="flex flex-col gap-6"> <div className="flex flex-col items-start gap-2"> <p className="text-sm text-muted">全部禁用</p> <ButtonGroup isDisabled> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button> <ButtonGroup.Separator /> 第三项 </Button> </ButtonGroup> </div> <div className="flex flex-col items-start gap-2"> <p className="text-sm text-muted">组已禁用，但单个按钮可覆盖</p> <ButtonGroup isDisabled> <Button>第一项</Button> <Button> <ButtonGroup.Separator /> 第二项 </Button> <Button isDisabled={false}> <ButtonGroup.Separator /> 第三项（可用） </Button> </ButtonGroup> </div> </div> ); } ``` ### 无分隔线 省略按钮中的 `<ButtonGroup.Separator />` 组件即可。 ```tsx import {Button, ButtonGroup} from "@heroui/react"; export function WithoutSeparator() { return ( <ButtonGroup> <Button>第一项</Button> <Button>第二项</Button> <Button>第三项</Button> </ButtonGroup> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {ChevronDown} from "@gravity-ui/icons"; import {Button, ButtonGroup, Description, Dropdown, Label} from "@heroui/react"; export function CustomStyles() { return ( <ButtonGroup> <Button className="rounded-none bg-[#08872B] data-hovered:bg-[#0FBF3E]">合并拉取请求</Button> <Dropdown> <Button isIconOnly aria-label="合并选项" className="rounded-none bg-[#08872B] data-hovered:bg-[#0FBF3E]" > <ButtonGroup.Separator /> <ChevronDown className="size-4" /> </Button> <Dropdown.Popover className="max-w-[290px] rounded-none" placement="bottom end"> <Dropdown.Menu> <Dropdown.Item className="flex flex-col items-start gap-1 rounded-none" id="merge" textValue="创建合并提交" > <Label>创建合并提交</Label> <Description>此分支的所有提交将添加到基础分支</Description> </Dropdown.Item> <Dropdown.Item className="flex flex-col items-start gap-1 rounded-none" id="squash-and-merge" textValue="压缩并合并" > <Label>压缩并合并</Label> <Description>此分支的 14 个提交将在基础分支中合并为一个提交</Description> </Dropdown.Item> <Dropdown.Item className="flex flex-col items-start gap-1 rounded-none" id="rebase-and-merge" textValue="变基并合并" > <Label>变基并合并</Label> <Description>此分支的 14 个提交将变基后添加到基础分支</Description> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> </ButtonGroup> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 ButtonGroup 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .button-group { @apply gap-2 rounded-lg; } .button-group__separator { @apply opacity-25; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ButtonGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button-group.css)）： #### 基础类 \[!toc] * `.button-group` - 按钮组根容器 * `.button-group--full-width` - 全宽修饰符 * `.button-group__separator` - 按钮之间的分隔元素 ButtonGroup 组件自动为按钮应用圆角： * 第一个按钮圆角左/起始边 * 最后一个按钮圆角右/结束边 * 中间按钮无圆角 * 单个按钮四边全圆角 在每个 Button 内（第一个除外）添加 `<ButtonGroup.Separator />` 以显示分隔线。 ## API 参考 ### ButtonGroup | Prop | 类型 | 默认值 | 描述 | | ------------- | --------------------------------------------------------------- | -------------- | ------------------- | | `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'ghost' \| 'danger'` | - | 应用于组内所有按钮的视觉变体 | | `size` | `'sm' \| 'md' \| 'lg'` | - | 应用于组内所有按钮的尺寸 | | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 按钮组方向 | | `fullWidth` | `boolean` | `false` | 是否占满容器宽度 | | `isDisabled` | `boolean` | `false` | 是否禁用组内所有按钮（单个按钮可覆盖） | | `className` | `string` | - | 附加 CSS 类 | | `children` | `React.ReactNode` | - | 要组合的 Button 组件 | ### ButtonGroup.Separator | Prop | 类型 | 默认值 | 描述 | | ----------- | -------- | --- | -------- | | `className` | `string` | - | 附加 CSS 类 | ## 说明 * ButtonGroup 通过 React Context 向所有子 Button 传递 `size`、`variant` 与 `isDisabled` 属性 * **仅直接子按钮接收 ButtonGroup 属性** - 嵌套在其他组件（如 Modal、Dropdown 等）内的 Button 即使位于 ButtonGroup 后代也不会继承组属性 * 单个 Button 可通过 `isDisabled={false}` 覆盖组的 `isDisabled` 属性 * 组件自动处理按钮之间的圆角 * 在每个 Button 内（第一个除外）添加 `<ButtonGroup.Separator />` 以显示分隔线 * 组内按钮移除 active/pressed 缩放变换，外观更统一 ## 相关组件 ## Related Components * **Button**: Allows a user to perform an action * **Dropdown**: Context menu with actions and options * **Chip**: Compact elements for tags and filters </page> <page url="/cn/docs/react/components/button"> # Button 按钮 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/button **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(buttons)/button.mdx > 可点击的按钮组件，支持多种变体与状态 ## 用法 ```tsx import { Button } from '@heroui/react'; ``` ```tsx "use client"; import {Button} from "@heroui/react"; export function Basic() { return <Button onPress={() => console.log("按钮已按下")}>点我</Button>; } ``` ## 示例 ### 变体 ```tsx import {Button} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-wrap gap-3"> <Button>主要</Button> <Button variant="secondary">次要</Button> <Button variant="tertiary">第三</Button> <Button variant="outline">线框</Button> <Button variant="ghost">幽灵</Button> <Button variant="danger">危险</Button> <Button variant="danger-soft">柔和危险</Button> </div> ); } ``` ### 尺寸 ```tsx import {Button} from "@heroui/react"; export function Sizes() { return ( <div className="flex items-center gap-3"> <Button size="sm">小</Button> <Button size="md">中</Button> <Button size="lg">大</Button> </div> ); } ``` ### 带图标 ```tsx import {Envelope, Globe, Plus, TrashBin} from "@gravity-ui/icons"; import {Button} from "@heroui/react"; export function WithIcons() { return ( <div className="flex flex-wrap gap-3"> <Button> <Globe /> 搜索 </Button> <Button variant="secondary"> <Plus /> 添加成员 </Button> <Button variant="tertiary"> <Envelope /> 邮件 </Button> <Button variant="danger"> <TrashBin /> 删除 </Button> </div> ); } ``` ### 仅图标 ```tsx import {Ellipsis, Gear, TrashBin} from "@gravity-ui/icons"; import {Button} from "@heroui/react"; export function IconOnly() { return ( <div className="flex gap-3"> <Button isIconOnly aria-label="更多选项" variant="tertiary"> <Ellipsis /> </Button> <Button isIconOnly aria-label="设置" variant="secondary"> <Gear /> </Button> <Button isIconOnly aria-label="删除" variant="danger"> <TrashBin /> </Button> </div> ); } ``` ### 加载中 ```tsx "use client"; import {Button, Spinner} from "@heroui/react"; import React from "react"; export function Loading() { return ( <Button isPending> {({isPending}) => ( <> {isPending ? <Spinner color="current" size="sm" /> : null} 上传中… </> )} </Button> ); } ``` ### 加载中（点击触发） ```tsx "use client"; import {Paperclip} from "@gravity-ui/icons"; import {Button, Spinner} from "@heroui/react"; import React, {useState} from "react"; export function LoadingState() { const [isLoading, setLoading] = useState(false); const handlePress = () => { setLoading(true); setTimeout(() => setLoading(false), 2000); }; return ( <Button isPending={isLoading} onPress={handlePress}> {({isPending}) => ( <> {isPending ? <Spinner color="current" size="sm" /> : <Paperclip />} {isPending ? "上传中…" : "上传文件"} </> )} </Button> ); } ``` ### 宽度充满 ```tsx import {Plus} from "@gravity-ui/icons"; import {Button} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-3"> <Button fullWidth>主要按钮</Button> <Button fullWidth> <Plus /> 带图标 </Button> </div> ); } ``` ### 禁用状态 ```tsx import {Button} from "@heroui/react"; export function Disabled() { return ( <div className="flex flex-wrap gap-3"> <Button isDisabled>主要</Button> <Button isDisabled variant="secondary"> 次要 </Button> <Button isDisabled variant="tertiary"> 第三 </Button> <Button isDisabled variant="outline"> 线框 </Button> <Button isDisabled variant="ghost"> 幽灵 </Button> <Button isDisabled variant="danger"> 危险 </Button> </div> ); } ``` ### 社交媒体按钮 ```tsx import {Button} from "@heroui/react"; import {Icon} from "@iconify/react"; export function Social() { return ( <div className="flex w-full max-w-xs flex-col gap-3"> <Button className="w-full" variant="tertiary"> <Icon icon="devicon:google" /> 使用 Google 登录 </Button> <Button className="w-full" variant="tertiary"> <Icon icon="mdi:github" /> 使用 GitHub 登录 </Button> <Button className="w-full" variant="tertiary"> <Icon icon="ion:logo-apple" /> 使用 Apple 登录 </Button> </div> ); } ``` ### 渲染函数 ```tsx "use client"; import {Button} from "@heroui/react"; export function RenderFunction() { return ( <Button render={(props, {isPressed}) => ( <button {...props} data-custom={isPressed ? "pressed" : "bar"} /> )} > 点按 </Button> ); } ``` ### 添加自定义变体 可通过包装组件并添加自定义变体来扩展 HeroUI 组件。 ```tsx import type {ButtonProps} from "@heroui/react"; import type {VariantProps} from "tailwind-variants"; import {Button, buttonVariants} from "@heroui/react"; import {tv} from "tailwind-variants"; const myButtonVariants = tv({ base: "text-md font-semibold shadow-md text-shadow-lg data-[pending=true]:opacity-40", defaultVariants: { radius: "full", variant: "primary", }, extend: buttonVariants, variants: { radius: { full: "rounded-full", lg: "rounded-lg", md: "rounded-md", sm: "rounded-sm", }, size: { lg: "h-12 px-8", md: "h-11 px-6", sm: "h-10 px-4", xl: "h-13 px-10", }, variant: { primary: "text-white dark:bg-white/10 dark:text-white dark:hover:bg-white/15", }, }, }); type MyButtonVariants = VariantProps<typeof myButtonVariants>; export type MyButtonProps = Omit<ButtonProps, "className"> & MyButtonVariants & {className?: string}; function CustomButton({className, radius, variant, ...props}: MyButtonProps) { return <Button className={myButtonVariants({className, radius, variant})} {...props} />; } export function CustomVariants() { return <CustomButton>自定义按钮</CustomButton>; } ``` ### 添加涟漪效果 Button 组件通过组合支持 ripple 效果，可将 ripple 组件作为子节点嵌套。本示例使用 [m3-ripple](https://github.com/saltyaom/m3-ripple)。 ```tsx "use client"; import {Button} from "@heroui/react"; import {Ripple} from "m3-ripple"; import "m3-ripple/ripple.css"; export function RippleEffect() { return ( <Button variant="secondary"> <Ripple /> 点我 </Button> ); } ``` ## 自定义样式 ### Tailwind CSS ````tsx "use client"; import {Button} from "@heroui/react"; /** * 下面的 `gradient-border` 类依赖全局 utility。 * 使用前请将其添加到全局 CSS（例如 `src/app/globals.css`）： * * ```css * @utility gradient-border { * &::before { * content: ""; * position: absolute; * inset: 0; * z-index: 0; * border-radius: inherit; * padding: var(--gradient-border-width, 1px); * background: var(--gradient-border); * pointer-events: none; * -webkit-mask: * linear-gradient(#fff 0 0) content-box, * linear-gradient(#fff 0 0); * -webkit-mask-composite: xor; * mask: * linear-gradient(#fff 0 0) content-box, * linear-gradient(#fff 0 0); * mask-composite: exclude; * } * } * ``` * * 在组件上通过 Tailwind 任意属性或内联样式设置 * `--gradient-border`（渐变）以及可选的 `--gradient-border-width`（默认 `1px`）。 */ export function CustomStyles() { return ( <Button className="gradient-border relative z-0 rounded-full bg-linear-to-t from-neutral-100 to-white px-10 py-3 font-[450] text-neutral-800 shadow-none transition-all duration-300 ease-[cubic-bezier(0.34,1.56,0.64,1)] [--gradient-border-width:1.5px] [--gradient-border:linear-gradient(315deg,#e5e5e5_0%,#fafafa_50%,#c4c4c4_100%)] hover:from-white hover:to-neutral-50 hover:brightness-105 active:scale-95 dark:from-neutral-900 dark:via-neutral-800 dark:to-neutral-800/80 dark:text-neutral-100 dark:[--gradient-border:linear-gradient(315deg,#404040_0%,#262626_50%,#525252_100%)] dark:hover:from-neutral-800 dark:hover:via-neutral-800 dark:hover:to-neutral-900/90" variant="ghost" style={{ boxShadow: "rgba(0, 0, 0, 0.02) 0px 1px 6px, rgba(0, 0, 0, 0.02) 0px 3px 12px, rgba(0, 0, 0, 0.01) 0px 8px 24px, rgba(0, 0, 0, 0.02) 0px 18px 40px, rgba(0, 0, 0, 0.02) 0px 40px 80px", }} > 升级 </Button> ); } ```` ### 全局 CSS 可使用 `@layer components` 指令自定义 Button 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .button { @apply bg-purple-500 text-white hover:bg-purple-600; } .button--icon-only { @apply rounded-lg bg-blue-500; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Button 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/button.css)）： #### 基础与尺寸类 \[!toc] * `.button` - 基础按钮样式 * `.button--sm` - 小尺寸变体 * `.button--md` - 中尺寸变体 * `.button--lg` - 大尺寸变体 #### 变体类 \[!toc] * `.button--primary` * `.button--secondary` * `.button--tertiary` * `.button--outline` * `.button--ghost` * `.button--danger` * `.button--danger-soft` #### 修饰符类 \[!toc] * `.button--icon-only` * `.button--icon-only.button--sm` * `.button--icon-only.button--lg` ### 交互状态 按钮同时支持 CSS 伪类与 data 属性： * **Hover**：`:hover` 或 `[data-hovered="true"]` * **Active/Pressed**：`:active` 或 `[data-pressed="true"]`（含缩放变换） * **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环） * **Disabled**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度，禁用指针事件） * **Pending**：`[data-pending]`（加载期间禁用指针事件） ## API 参考 ### Button | Prop | 类型 | 默认值 | 描述 | | ------------ | --------------------------------------------------------------------------------------------- | ----------- | -------------------------- | | `variant` | `'primary' \| 'secondary' \| 'tertiary' \| 'outline' \| 'ghost' \| 'danger' \| 'danger-soft'` | `'primary'` | 视觉样式变体 | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 按钮尺寸 | | `fullWidth` | `boolean` | `false` | 是否占满容器宽度 | | `isDisabled` | `boolean` | `false` | 是否禁用 | | `isPending` | `boolean` | `false` | 是否处于加载状态 | | `isIconOnly` | `boolean` | `false` | 是否仅包含图标 | | `onPress` | `(e: PressEvent) => void` | - | 按下时的回调 | | `children` | `React.ReactNode \| (values: ButtonRenderProps) => React.ReactNode` | - | 按钮内容或 render prop | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ButtonRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Render Props 使用 render prop 模式时，提供以下值： | Prop | 类型 | 描述 | | ---------------- | --------- | --------- | | `isPending` | `boolean` | 是否处于加载状态 | | `isPressed` | `boolean` | 是否正在按下 | | `isHovered` | `boolean` | 是否悬停 | | `isFocused` | `boolean` | 是否聚焦 | | `isFocusVisible` | `boolean` | 是否显示焦点指示器 | | `isDisabled` | `boolean` | 是否禁用 | ## 相关案例 ## 相关组件 ## Related Components * **Popover**: Displays content in context with a trigger * **Tooltip**: Contextual information on hover or focus * **Form**: Form validation and submission handling </page> <page url="/cn/docs/react/components/close-button"> # CloseButton 关闭按钮 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/close-button **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(buttons)/close-button.mdx > 用于关闭对话框、模态框或 dismiss 内容的按钮组件 ## 用法 ```tsx import { CloseButton } from "@heroui/react"; ``` ```tsx import {CloseButton} from "@heroui/react"; export function Default() { return <CloseButton />; } ``` ## 示例 ### 交互 ```tsx "use client"; import {CloseButton} from "@heroui/react"; import {useState} from "react"; export function Interactive() { const [count, setCount] = useState(0); return ( <div className="flex flex-col items-center justify-center gap-4"> <CloseButton aria-label={`关闭（已点击 ${count} 次）`} onPress={() => setCount(count + 1)} /> <span className="text-sm text-muted">已点击：{count} 次</span> </div> ); } ``` ### 自定义图标 ```tsx import {CircleXmark, Xmark} from "@gravity-ui/icons"; import {CloseButton} from "@heroui/react"; export function WithCustomIcon() { return ( <div className="flex items-center gap-4"> <div className="flex flex-col items-center gap-2"> <CloseButton> <CircleXmark /> </CloseButton> <span className="text-xs text-muted">自定义图标</span> </div> <div className="flex flex-col items-center gap-2"> <CloseButton> <Xmark /> </CloseButton> <span className="text-xs text-muted">备选图标</span> </div> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {CloseButton} from "@heroui/react"; export function CustomStyles() { return ( <CloseButton aria-label="关闭" className="size-8 rounded-full bg-default text-muted hover:bg-default-hover hover:text-foreground active:scale-95" /> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 CloseButton 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .close-button { @apply bg-red-100 text-red-800 hover:bg-red-200; } .close-button--custom { @apply rounded-full border-2 border-red-300; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 CloseButton 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/close-button.css)）： #### 基础类 \[!toc] * `.close-button` - 基础组件样式 #### 变体类 \[!toc] * `.close-button--default` - 默认变体 ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Hover**：`:hover` 或 `[data-hovered="true"]` * **Active/Pressed**：`:active` 或 `[data-pressed="true"]` * **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]` * **Disabled**：`:disabled` 或 `[aria-disabled="true"]` ## API 参考 ### CloseButton | Prop | 类型 | 默认值 | 描述 | | ------------ | ----------------------- | --------------- | ------------- | | `variant` | `"default"` | `"default"` | 按钮视觉变体 | | `children` | `ReactNode \| function` | `<CloseIcon />` | 显示内容（默认为关闭图标） | | `onPress` | `() => void` | - | 按下时的回调 | | `isDisabled` | `boolean` | `false` | 是否禁用 | ### React Aria Button Props CloseButton 继承所有 React Aria Button 属性。常用属性包括： | Prop | 类型 | 描述 | | ------------------ | -------- | ----------- | | `aria-label` | `string` | 屏幕阅读器的无障碍标签 | | `aria-labelledby` | `string` | 标注按钮的元素 ID | | `aria-describedby` | `string` | 描述按钮的元素 ID | ### Render Props 使用 render prop 模式时，提供以下值： | Prop | 类型 | 描述 | | ------------ | --------- | ---- | | `isHovered` | `boolean` | 是否悬停 | | `isPressed` | `boolean` | 是否按下 | | `isFocused` | `boolean` | 是否聚焦 | | `isDisabled` | `boolean` | 是否禁用 | ## 相关组件 ## Related Components * **Alert**: Display important messages and notifications * **AlertDialog**: Critical confirmations requiring user attention * **Chip**: Compact elements for tags and filters </page> <page url="/cn/docs/react/components/toggle-button-group"> # ToggleButtonGroup 切换按钮组 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/toggle-button-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(buttons)/toggle-button-group.mdx > 将多个 ToggleButton 组合为统一控件，允许用户选择单个或多个选项。 ## 用法 ```tsx import { ToggleButtonGroup, ToggleButton } from '@heroui/react'; ``` ```tsx import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function Basic() { return ( <ToggleButtonGroup selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> <ToggleButton isIconOnly aria-label="删除线" id="strikethrough"> <ToggleButtonGroup.Separator /> <Strikethrough /> </ToggleButton> </ToggleButtonGroup> ); } ``` ## 组件结构 导入 ToggleButtonGroup 组件，并通过点语法访问所有子部分。 ```tsx import { ToggleButtonGroup, ToggleButton } from '@heroui/react'; export default () => ( <ToggleButtonGroup selectionMode="multiple"> <ToggleButton id="first">First</ToggleButton> <ToggleButton id="second"> <ToggleButtonGroup.Separator /> Second </ToggleButton> <ToggleButton id="third"> <ToggleButtonGroup.Separator /> Third </ToggleButton> </ToggleButtonGroup> ); ``` ## 示例 ### 尺寸 ```tsx import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function Sizes() { return ( <div className="flex flex-col gap-6"> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">小</span> <ToggleButtonGroup selectionMode="multiple" size="sm"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> <ToggleButton isIconOnly aria-label="删除线" id="strikethrough"> <ToggleButtonGroup.Separator /> <Strikethrough /> </ToggleButton> </ToggleButtonGroup> </div> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">中（默认）</span> <ToggleButtonGroup selectionMode="multiple" size="md"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> <ToggleButton isIconOnly aria-label="删除线" id="strikethrough"> <ToggleButtonGroup.Separator /> <Strikethrough /> </ToggleButton> </ToggleButtonGroup> </div> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">大</span> <ToggleButtonGroup selectionMode="multiple" size="lg"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> <ToggleButton isIconOnly aria-label="删除线" id="strikethrough"> <ToggleButtonGroup.Separator /> <Strikethrough /> </ToggleButton> </ToggleButtonGroup> </div> </div> ); } ``` ### 方向 ```tsx import {Bold, Italic, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function Orientation() { return ( <div className="flex items-start gap-8"> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">水平</span> <ToggleButtonGroup orientation="horizontal" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> </div> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">垂直</span> <ToggleButtonGroup orientation="vertical" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> </div> </div> ); } ``` ### 宽度充满 ```tsx import { Bold, Italic, Strikethrough, TextAlignCenter, TextAlignLeft, TextAlignRight, Underline, } from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function FullWidth() { return ( <div className="w-full max-w-md space-y-3"> <ToggleButtonGroup fullWidth selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> <ToggleButton isIconOnly aria-label="删除线" id="strikethrough"> <ToggleButtonGroup.Separator /> <Strikethrough /> </ToggleButton> </ToggleButtonGroup> <ToggleButtonGroup fullWidth selectionMode="single"> <ToggleButton id="left"> <TextAlignLeft /> 左对齐 </ToggleButton> <ToggleButton id="center"> <ToggleButtonGroup.Separator /> <TextAlignCenter /> 居中 </ToggleButton> <ToggleButton id="right"> <ToggleButtonGroup.Separator /> <TextAlignRight /> 右对齐 </ToggleButton> </ToggleButtonGroup> </div> ); } ``` ### 禁用 ```tsx import {Bold, Italic, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function Disabled() { return ( <div className="flex flex-col gap-6"> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">全部按钮已禁用</span> <ToggleButtonGroup isDisabled selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> </div> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">单个按钮已禁用</span> <ToggleButtonGroup selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isDisabled isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> </div> </div> ); } ``` ### 无分隔线 省略按钮中的 `<ToggleButtonGroup.Separator />` 组件即可。 ```tsx import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function WithoutSeparator() { return ( <ToggleButtonGroup selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <Underline /> </ToggleButton> <ToggleButton isIconOnly aria-label="删除线" id="strikethrough"> <Strikethrough /> </ToggleButton> </ToggleButtonGroup> ); } ``` ### 分离模式 使用 `isDetached` 让按钮之间留出间隔，而不是彼此连接。 ```tsx import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function Attached() { return ( <div className="flex flex-col gap-6"> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">附着（默认）</span> <ToggleButtonGroup selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> <ToggleButton isIconOnly aria-label="删除线" id="strikethrough"> <ToggleButtonGroup.Separator /> <Strikethrough /> </ToggleButton> </ToggleButtonGroup> </div> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">分离</span> <ToggleButtonGroup isDetached selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <Underline /> </ToggleButton> <ToggleButton isIconOnly aria-label="删除线" id="strikethrough"> <Strikethrough /> </ToggleButton> </ToggleButtonGroup> </div> </div> ); } ``` ### 选择模式 使用 `selectionMode="single"` 实现互斥选择，或使用 `selectionMode="multiple"` 实现独立切换。 ```tsx import { Bold, Italic, Strikethrough, TextAlignCenter, TextAlignLeft, TextAlignRight, Underline, } from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; export function SelectionMode() { return ( <div className="flex flex-col gap-6"> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">单选</span> <ToggleButtonGroup defaultSelectedKeys={["center"]} selectionMode="single"> <ToggleButton id="left"> <TextAlignLeft /> 左对齐 </ToggleButton> <ToggleButton id="center"> <ToggleButtonGroup.Separator /> <TextAlignCenter /> 居中 </ToggleButton> <ToggleButton id="right"> <ToggleButtonGroup.Separator /> <TextAlignRight /> 右对齐 </ToggleButton> </ToggleButtonGroup> </div> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">多选</span> <ToggleButtonGroup defaultSelectedKeys={["bold", "underline"]} selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> <ToggleButton isIconOnly aria-label="删除线" id="strikethrough"> <ToggleButtonGroup.Separator /> <Strikethrough /> </ToggleButton> </ToggleButtonGroup> </div> </div> ); } ``` ### 受控组件 ```tsx "use client"; import type {Key} from "@heroui/react"; import {Bold, Italic, Strikethrough, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [selectedKeys, setSelectedKeys] = useState(new Set<Key>(["bold"])); return ( <div className="flex flex-col gap-4"> <ToggleButtonGroup selectedKeys={selectedKeys} selectionMode="multiple" onSelectionChange={setSelectedKeys} > <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> <ToggleButton isIconOnly aria-label="删除线" id="strikethrough"> <ToggleButtonGroup.Separator /> <Strikethrough /> </ToggleButton> </ToggleButtonGroup> <p className="text-sm text-muted"> 已选： <span className="font-medium"> {selectedKeys.size > 0 ? [...selectedKeys].join(", ") : "无"} </span> </p> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Bold, Italic, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup} from "@heroui/react"; const toggleClass = "rounded-lg text-muted data-[selected=true]:bg-accent-soft data-[selected=true]:text-accent-soft-foreground"; export function CustomStyles() { return ( <ToggleButtonGroup aria-label="文本格式" className="gap-1 rounded-xl border border-border/80 bg-surface p-1 shadow-sm" selectionMode="multiple" > <ToggleButton isIconOnly aria-label="粗体" className={toggleClass} id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" className={toggleClass} id="italic"> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" className={toggleClass} id="underline"> <Underline /> </ToggleButton> </ToggleButtonGroup> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .toggle-button-group { @apply rounded-lg; } .toggle-button-group__separator { @apply opacity-25; } .toggle-button-group--full-width { @apply w-full; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ToggleButtonGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button-group.css)）： #### 基础与布局类 \[!toc] * `.toggle-button-group` - 容器基础样式 * `.toggle-button-group--horizontal` - 水平方向 * `.toggle-button-group--vertical` - 垂直方向 * `.toggle-button-group--full-width` - 全宽修饰符 * `.toggle-button-group__separator` - 按钮之间的分隔线元素 #### 修饰符类 \[!toc] * `.toggle-button-group--detached` - 分离模式（按钮间有间隔） ## API 参考 ### ToggleButtonGroup 继承自 [React Aria ToggleButtonGroup](https://react-aria.adobe.com/ToggleButtonGroup)。 | Prop | 类型 | 默认值 | 描述 | | ------------------------ | ---------------------------- | -------------- | --------------------- | | `selectionMode` | `"single" \| "multiple"` | `"single"` | 是否允许选中一个或多个按钮 | | `selectedKeys` | `Iterable<Key>` | - | 受控的选中状态 | | `defaultSelectedKeys` | `Iterable<Key>` | - | 默认选中 key（非受控） | | `onSelectionChange` | `(keys: Set<Key>) => void` | - | 选中变化时调用 | | `disallowEmptySelection` | `boolean` | `false` | 是否禁止清空所有选中 | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | 布局方向 | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | 传递给子 ToggleButton 的尺寸 | | `isDetached` | `boolean` | `false` | 按钮是否以间隔分离显示 | | `fullWidth` | `boolean` | `false` | 按钮组是否占满可用宽度 | | `isDisabled` | `boolean` | `false` | 是否禁用组内全部按钮 | | `className` | `string` | - | 额外的 CSS 类 | ### ToggleButtonGroup.Separator | Prop | 类型 | 默认值 | 描述 | | ----------- | -------- | --- | --------- | | `className` | `string` | - | 额外的 CSS 类 | ## 说明 * ToggleButtonGroup 使用 React Context 将 `size` 传递给所有子 ToggleButton 组件 * 每个 ToggleButton 都必须有唯一 `id` prop，并与 `selectedKeys` / `defaultSelectedKeys` 中使用的 key 对应 * `isDisabled` prop 由 React Aria 原生处理，会禁用所有子 ToggleButton；单个按钮可通过设置 `isDisabled={false}` 覆盖 * 组件会自动处理按钮之间的圆角 * 在每个 ToggleButton（第一个除外）内添加 `<ToggleButtonGroup.Separator />`，可在按钮之间显示分隔线 * 将 `disallowEmptySelection` 与 `selectionMode="single"` 一起使用，可确保始终有一个选项被选中 ## 相关组件 ## Related Components * **ToggleButton**: Interactive toggle control for on/off states * **ButtonGroup**: Group related buttons together * **Button**: Allows a user to perform an action </page> <page url="/cn/docs/react/components/toggle-button"> # ToggleButton 切换按钮 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/toggle-button **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(buttons)/toggle-button.mdx > 用于在开启/关闭或已选中/未选中状态之间切换的交互式切换控件。 ## 用法 ```tsx import { ToggleButton } from '@heroui/react'; ``` ```tsx import {Heart} from "@gravity-ui/icons"; import {ToggleButton} from "@heroui/react"; export function Basic() { return ( <ToggleButton> <Heart /> 点赞 </ToggleButton> ); } ``` ## 示例 ### 变体 ```tsx import {Heart} from "@gravity-ui/icons"; import {ToggleButton} from "@heroui/react"; export function Variants() { return ( <div className="flex items-center gap-3"> <ToggleButton> <Heart /> 默认 </ToggleButton> <ToggleButton variant="ghost"> <Heart /> 幽灵 </ToggleButton> </div> ); } ``` ### 仅图标 ```tsx import {Bookmark, Heart} from "@gravity-ui/icons"; import {ToggleButton} from "@heroui/react"; export function IconOnly() { return ( <div className="flex items-center gap-3"> <ToggleButton isIconOnly aria-label="点赞"> <Heart /> </ToggleButton> <ToggleButton isIconOnly aria-label="收藏" variant="ghost"> <Bookmark /> </ToggleButton> </div> ); } ``` ### 尺寸 ```tsx import {Heart} from "@gravity-ui/icons"; import {ToggleButton} from "@heroui/react"; export function Sizes() { return ( <div className="flex flex-col gap-6"> <div className="flex items-center gap-3"> <ToggleButton size="sm"> <Heart />小 </ToggleButton> <ToggleButton size="md"> <Heart />中 </ToggleButton> <ToggleButton size="lg"> <Heart />大 </ToggleButton> </div> <div className="flex items-center gap-3"> <ToggleButton isIconOnly aria-label="点赞" size="sm"> <Heart /> </ToggleButton> <ToggleButton isIconOnly aria-label="点赞" size="md"> <Heart /> </ToggleButton> <ToggleButton isIconOnly aria-label="点赞" size="lg"> <Heart /> </ToggleButton> </div> </div> ); } ``` ### 禁用 ```tsx import {Heart, HeartFill} from "@gravity-ui/icons"; import {ToggleButton} from "@heroui/react"; export function Disabled() { return ( <div className="flex items-center gap-3"> <ToggleButton isDisabled> <Heart /> 点赞 </ToggleButton> <ToggleButton defaultSelected isDisabled> <HeartFill /> 点赞 </ToggleButton> </div> ); } ``` ### 受控组件 ```tsx "use client"; import {Heart, HeartFill} from "@gravity-ui/icons"; import {ToggleButton} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [isSelected, setIsSelected] = useState(false); return ( <div className="flex flex-col gap-4"> <ToggleButton isSelected={isSelected} onChange={setIsSelected}> {({isSelected: selected}) => ( <> {selected ? <HeartFill /> : <Heart />} {selected ? "已点赞" : "点赞"} </> )} </ToggleButton> <p className="text-sm text-muted"> 状态：<span className="font-medium">{isSelected ? "已选" : "未选"}</span> </p> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Heart} from "@gravity-ui/icons"; import {ToggleButton} from "@heroui/react"; export function CustomStyles() { return ( <ToggleButton className="gap-2 rounded-full border border-border/80 bg-surface px-4 text-foreground shadow-sm data-[selected=true]:border-accent/30 data-[selected=true]:bg-accent-soft data-[selected=true]:text-accent-soft-foreground [&_svg]:text-muted data-[selected=true]:[&_svg]:text-accent"> <Heart /> 收藏文章 </ToggleButton> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .toggle-button { @apply bg-purple-500 text-white; } .toggle-button--icon-only { @apply rounded-lg; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ToggleButton 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toggle-button.css)）： #### 基础与尺寸类 \[!toc] * `.toggle-button` - 切换按钮基础样式 * `.toggle-button--sm` - 小尺寸变体 * `.toggle-button--md` - 中尺寸变体（默认） * `.toggle-button--lg` - 大尺寸变体 #### 变体类 \[!toc] * `.toggle-button--default` - 默认变体（填充背景） * `.toggle-button--ghost` - 幽灵变体（透明背景） #### 修饰符类 \[!toc] * `.toggle-button--icon-only` - 仅图标切换按钮 * `.toggle-button--icon-only.toggle-button--sm` - 小尺寸仅图标 * `.toggle-button--icon-only.toggle-button--lg` - 大尺寸仅图标 ### 交互状态 该切换按钮同时支持 CSS 伪类与 data 属性，以便灵活控制状态： * **已选中**：`[data-selected="true"]`（强调色背景与前景） * **悬停**：`:hover` 或 `[data-hovered="true"]` * **激活/按下**：`:active` 或 `[data-pressed="true"]`（包含缩放变换） * **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环） * **禁用**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度，禁用指针事件） ## API 参考 ### ToggleButton 继承自 [React Aria ToggleButton](https://react-spectrum.adobe.com/react-aria/ToggleButton.html)。 | Prop | 类型 | 默认值 | 描述 | | ----------------- | ------------------------------------------------------------------------- | ----------- | --------------- | | `variant` | `'default' \| 'ghost'` | `'default'` | 视觉样式变体 | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 切换按钮尺寸 | | `isIconOnly` | `boolean` | `false` | 按钮是否仅包含图标 | | `isSelected` | `boolean` | - | 受控的已选中状态 | | `defaultSelected` | `boolean` | `false` | 默认已选中状态（非受控） | | `isDisabled` | `boolean` | `false` | 是否禁用切换按钮 | | `onChange` | `(isSelected: boolean) => void` | - | 已选中状态变化时调用的处理函数 | | `onPress` | `(e: PressEvent) => void` | - | 按钮按下时调用的处理函数 | | `children` | `React.ReactNode \| (values: ToggleButtonRenderProps) => React.ReactNode` | - | 按钮内容或渲染 prop | ### ToggleButtonRenderProps 使用渲染 prop 模式时，会提供以下值： | Prop | 类型 | 描述 | | ---------------- | --------- | ------------ | | `isSelected` | `boolean` | 按钮当前是否已选中 | | `isPressed` | `boolean` | 按钮当前是否处于按下状态 | | `isHovered` | `boolean` | 按钮是否处于悬停状态 | | `isFocused` | `boolean` | 按钮是否处于聚焦状态 | | `isFocusVisible` | `boolean` | 按钮是否应显示焦点指示 | | `isDisabled` | `boolean` | 按钮是否被禁用 | ## 相关组件 ## Related Components * **Button**: Allows a user to perform an action * **Switch**: Toggle between two states * **Checkbox**: Binary choice input control </page> <page url="/cn/docs/react/components/dropdown"> # Dropdown 下拉菜单 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/dropdown **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(collections)/dropdown.mdx > 展示用户可选择的操作或选项列表 ## 用法 ```tsx import { Dropdown } from '@heroui/react'; ``` ```tsx "use client"; import {Button, Dropdown, Label} from "@heroui/react"; export function Default() { return ( <Dropdown> <Button aria-label="菜单" variant="secondary"> 操作 </Button> <Dropdown.Popover> <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}> <Dropdown.Item id="new-file" textValue="新建文件"> <Label>新建文件</Label> </Dropdown.Item> <Dropdown.Item id="copy-link" textValue="复制链接"> <Label>复制链接</Label> </Dropdown.Item> <Dropdown.Item id="edit-file" textValue="编辑文件"> <Label>编辑文件</Label> </Dropdown.Item> <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger"> <Label>删除文件</Label> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ## 组件结构 ```tsx import { Dropdown, Button, Label, Description, Header, Kbd, Separator } from '@heroui/react'; export default () => ( <Dropdown> <Dropdown.Trigger> <Button /> </Dropdown.Trigger> <Dropdown.Popover> <Dropdown.Menu> <Dropdown.Item> <Label /> <Description /> <Kbd slot="keyboard" /> <Dropdown.ItemIndicator /> </Dropdown.Item> <Separator /> <Dropdown.Section> <Header /> <Dropdown.Item /> </Dropdown.Section> <Dropdown.SubmenuTrigger> <Dropdown.Item> <Label /> <Dropdown.SubmenuIndicator /> </Dropdown.Item> <Dropdown.Popover> <Dropdown.Menu> <Dropdown.Item /> </Dropdown.Menu> </Dropdown.Popover> </Dropdown.SubmenuTrigger> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ) ``` ## 示例 ### 带图标 ```tsx "use client"; import {FloppyDisk, FolderOpen, SquarePlus, TrashBin} from "@gravity-ui/icons"; import {Button, Dropdown, Kbd, Label} from "@heroui/react"; export function WithIcons() { return ( <Dropdown> <Button aria-label="菜单" variant="secondary"> 操作 </Button> <Dropdown.Popover> <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}> <Dropdown.Item id="new-file" textValue="新建文件"> <SquarePlus className="size-4 shrink-0 text-muted" /> <Label>新建文件</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>N</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="open-file" textValue="打开文件"> <FolderOpen className="size-4 shrink-0 text-muted" /> <Label>打开文件</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>O</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="save-file" textValue="保存文件"> <FloppyDisk className="size-4 shrink-0 text-muted" /> <Label>保存文件</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>S</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger"> <TrashBin className="size-4 shrink-0 text-danger" /> <Label>删除文件</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>D</Kbd.Content> </Kbd> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 带描述 ```tsx "use client"; import {FloppyDisk, FolderOpen, SquarePlus, TrashBin} from "@gravity-ui/icons"; import {Button, Description, Dropdown, Kbd, Label} from "@heroui/react"; export function WithDescriptions() { return ( <Dropdown> <Button aria-label="菜单" variant="secondary"> 操作 </Button> <Dropdown.Popover> <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}> <Dropdown.Item id="new-file" textValue="新建文件"> <div className="flex h-8 items-start justify-center pt-px"> <SquarePlus className="size-4 shrink-0 text-muted" /> </div> <div className="flex flex-col"> <Label>新建文件</Label> <Description>创建新文件</Description> </div> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>N</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="open-file" textValue="打开文件"> <div className="flex h-8 items-start justify-center pt-px"> <FolderOpen className="size-4 shrink-0 text-muted" /> </div> <div className="flex flex-col"> <Label>打开文件</Label> <Description>打开已有文件</Description> </div> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>O</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="save-file" textValue="保存文件"> <div className="flex h-8 items-start justify-center pt-px"> <FloppyDisk className="size-4 shrink-0 text-muted" /> </div> <div className="flex flex-col"> <Label>保存文件</Label> <Description>保存当前文件</Description> </div> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>S</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger"> <div className="flex h-8 items-start justify-center pt-px"> <TrashBin className="size-4 shrink-0 text-danger" /> </div> <div className="flex flex-col"> <Label>删除文件</Label> <Description>移至废纸篓</Description> </div> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>D</Kbd.Content> </Kbd> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 含禁用项 ```tsx "use client"; import {Bars, Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons"; import {Button, Description, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react"; export function WithDisabledItems() { return ( <Dropdown> <Button isIconOnly aria-label="菜单" variant="secondary"> <Bars className="outline-none" /> </Button> <Dropdown.Popover className="min-w-[220px]"> <Dropdown.Menu disabledKeys={["delete-file"]} onAction={(key) => console.log(`Selected: ${key}`)} > <Dropdown.Section> <Header>操作</Header> <Dropdown.Item id="new-file" textValue="新建文件"> <div className="flex h-8 items-start justify-center pt-px"> <SquarePlus className="size-4 shrink-0 text-muted" /> </div> <div className="flex flex-col"> <Label>新建文件</Label> <Description>创建新文件</Description> </div> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>N</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="edit-file" textValue="编辑文件"> <div className="flex h-8 items-start justify-center pt-px"> <Pencil className="size-4 shrink-0 text-muted" /> </div> <div className="flex flex-col"> <Label>编辑文件</Label> <Description>进行修改</Description> </div> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>E</Kbd.Content> </Kbd> </Dropdown.Item> </Dropdown.Section> <Separator /> <Dropdown.Section> <Header>危险区域</Header> <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger"> <div className="flex h-8 items-start justify-center pt-px"> <TrashBin className="size-4 shrink-0 text-danger" /> </div> <div className="flex flex-col"> <Label>删除文件</Label> <Description>移至废纸篓</Description> </div> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>D</Kbd.Content> </Kbd> </Dropdown.Item> </Dropdown.Section> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 分组选项 ```tsx "use client"; import {EllipsisVertical, Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons"; import {Button, Description, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react"; export function WithSections() { return ( <Dropdown> <Button isIconOnly aria-label="菜单" variant="secondary"> <EllipsisVertical className="outline-none" /> </Button> <Dropdown.Popover> <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}> <Dropdown.Section> <Header>操作</Header> <Dropdown.Item id="new-file" textValue="新建文件"> <div className="flex h-8 items-start justify-center pt-px"> <SquarePlus className="size-4 shrink-0 text-muted" /> </div> <div className="flex flex-col"> <Label>新建文件</Label> <Description>创建新文件</Description> </div> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>N</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="edit-file" textValue="编辑文件"> <div className="flex h-8 items-start justify-center pt-px"> <Pencil className="size-4 shrink-0 text-muted" /> </div> <div className="flex flex-col"> <Label>编辑文件</Label> <Description>进行修改</Description> </div> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>E</Kbd.Content> </Kbd> </Dropdown.Item> </Dropdown.Section> <Separator /> <Dropdown.Section> <Header>危险区域</Header> <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger"> <div className="flex h-8 items-start justify-center pt-px"> <TrashBin className="size-4 shrink-0 text-danger" /> </div> <div className="flex flex-col"> <Label>删除文件</Label> <Description>移至废纸篓</Description> </div> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>D</Kbd.Content> </Kbd> </Dropdown.Item> </Dropdown.Section> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 多选 ```tsx "use client"; import type {Selection} from "@heroui/react"; import {Button, Dropdown, Header, Label} from "@heroui/react"; import {useState} from "react"; export function WithMultipleSelection() { const [selected, setSelected] = useState<Selection>(new Set(["apple"])); return ( <Dropdown> <Button aria-label="菜单" variant="secondary"> 喜爱的水果 </Button> <Dropdown.Popover className="min-w-[256px]"> <Dropdown.Menu selectedKeys={selected} selectionMode="multiple" onSelectionChange={setSelected} > <Dropdown.Section> <Header>选择水果</Header> <Dropdown.Item id="apple" textValue="苹果"> <Dropdown.ItemIndicator /> <Label>苹果</Label> </Dropdown.Item> <Dropdown.Item id="banana" textValue="香蕉"> <Dropdown.ItemIndicator /> <Label>香蕉</Label> </Dropdown.Item> <Dropdown.Item id="cherry" textValue="樱桃"> <Dropdown.ItemIndicator /> <Label>樱桃</Label> </Dropdown.Item> </Dropdown.Section> <Dropdown.Item id="orange" textValue="橙子"> <Dropdown.ItemIndicator /> <Label>橙子</Label> </Dropdown.Item> <Dropdown.Item id="pear" textValue="梨"> <Dropdown.ItemIndicator /> <Label>梨</Label> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 受控组件 ```tsx "use client"; import type {Selection} from "@heroui/react"; import {Button, Dropdown, Label} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [selected, setSelected] = useState<Selection>(new Set(["bold"])); const selectedItems = Array.from(selected); return ( <div className="flex min-w-sm flex-col items-center justify-center gap-4"> <p className="text-sm text-muted"> 已选：{selectedItems.length > 0 ? selectedItems.join("、") : "无"} </p> <Dropdown> <Button aria-label="菜单" variant="secondary"> 操作 </Button> <Dropdown.Popover> <Dropdown.Menu selectedKeys={selected} selectionMode="multiple" onSelectionChange={setSelected} > <Dropdown.Item id="bold" textValue="粗体"> <Label>粗体</Label> <Dropdown.ItemIndicator /> </Dropdown.Item> <Dropdown.Item id="italic" textValue="斜体"> <Label>斜体</Label> <Dropdown.ItemIndicator /> </Dropdown.Item> <Dropdown.Item id="underline" textValue="下划线"> <Label>下划线</Label> <Dropdown.ItemIndicator /> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> </div> ); } ``` ### 受控展开状态 ```tsx "use client"; import {Button, Dropdown, Label} from "@heroui/react"; import {useState} from "react"; export function ControlledOpenState() { const [open, setOpen] = useState(false); return ( <div className="flex min-w-sm flex-col items-center justify-center gap-4"> <p className="text-sm text-muted"> 下拉菜单：<strong>{open ? "打开" : "关闭"}</strong> </p> <Dropdown isOpen={open} onOpenChange={setOpen}> <Button aria-label="菜单" variant="secondary"> 操作 </Button> <Dropdown.Popover> <Dropdown.Menu> <Dropdown.Item id="new-file" textValue="新建文件"> <Label>新建文件</Label> </Dropdown.Item> <Dropdown.Item id="open-file" textValue="打开文件"> <Label>打开文件</Label> </Dropdown.Item> <Dropdown.Item id="save-file" textValue="保存文件"> <Label>保存文件</Label> </Dropdown.Item> <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger"> <Label>删除文件</Label> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> </div> ); } ``` ### 单选 ```tsx "use client"; import type {Selection} from "@heroui/react"; import {Button, Dropdown, Header, Label} from "@heroui/react"; import {useState} from "react"; export function WithSingleSelection() { const [selected, setSelected] = useState<Selection>(new Set(["apple"])); return ( <Dropdown> <Button aria-label="菜单" variant="secondary"> 水果 </Button> <Dropdown.Popover className="min-w-[256px]"> <Dropdown.Menu selectedKeys={selected} selectionMode="single" onSelectionChange={setSelected} > <Dropdown.Section> <Header>选择水果</Header> <Dropdown.Item id="apple" textValue="苹果"> <Dropdown.ItemIndicator /> <Label>苹果</Label> </Dropdown.Item> <Dropdown.Item id="banana" textValue="香蕉"> <Dropdown.ItemIndicator /> <Label>香蕉</Label> </Dropdown.Item> <Dropdown.Item id="cherry" textValue="樱桃"> <Dropdown.ItemIndicator /> <Label>樱桃</Label> </Dropdown.Item> </Dropdown.Section> <Dropdown.Item id="orange" textValue="橙子"> <Dropdown.ItemIndicator /> <Label>橙子</Label> </Dropdown.Item> <Dropdown.Item id="pear" textValue="梨"> <Dropdown.ItemIndicator /> <Label>梨</Label> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 单选自定义指示器 ```tsx "use client"; import type {Selection} from "@heroui/react"; import {Button, Dropdown, Header, Label} from "@heroui/react"; import {useState} from "react"; export function SingleWithCustomIndicator() { const [selected, setSelected] = useState<Selection>(new Set(["apple"])); const CustomCheckmarkIcon = ( <svg height="16" viewBox="0 0 16 16" width="16" xmlns="http://www.w3.org/2000/svg"> <path className="text-accent" clipRule="evenodd" d="M8 15A7 7 0 1 0 8 1a7 7 0 0 0 0 14m3.1-8.55a.75.75 0 1 0-1.2-.9L7.419 8.858L6.03 7.47a.75.75 0 0 0-1.06 1.06l2 2a.75.75 0 0 0 1.13-.08z" fill="currentColor" fillRule="evenodd" /> </svg> ); return ( <Dropdown> <Button aria-label="菜单" variant="secondary"> 水果 </Button> <Dropdown.Popover className="min-w-[256px]"> <Dropdown.Menu selectedKeys={selected} selectionMode="single" onSelectionChange={setSelected} > <Dropdown.Section> <Header>选择水果</Header> <Dropdown.Item id="apple" textValue="苹果"> <Dropdown.ItemIndicator> {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)} </Dropdown.ItemIndicator> <Label>苹果</Label> </Dropdown.Item> <Dropdown.Item id="banana" textValue="香蕉"> <Dropdown.ItemIndicator> {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)} </Dropdown.ItemIndicator> <Label>香蕉</Label> </Dropdown.Item> <Dropdown.Item id="cherry" textValue="樱桃"> <Dropdown.ItemIndicator> {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)} </Dropdown.ItemIndicator> <Label>樱桃</Label> </Dropdown.Item> </Dropdown.Section> <Dropdown.Item id="orange" textValue="橙子"> <Dropdown.ItemIndicator> {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)} </Dropdown.ItemIndicator> <Label>橙子</Label> </Dropdown.Item> <Dropdown.Item id="pear" textValue="梨"> <Dropdown.ItemIndicator> {({isSelected}) => (isSelected ? CustomCheckmarkIcon : null)} </Dropdown.ItemIndicator> <Label>梨</Label> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 分组级选择 ```tsx "use client"; import type {Selection} from "@heroui/react"; import {Button, Dropdown, Header, Kbd, Label, Separator} from "@heroui/react"; import {useState} from "react"; export function WithSectionLevelSelection() { const [textStyles, setTextStyles] = useState<Selection>(new Set(["bold", "italic"])); const [textAlignment, setTextAlignment] = useState<Selection>(new Set(["left"])); return ( <Dropdown> <Button aria-label="菜单" variant="secondary"> 样式 </Button> <Dropdown.Popover className="min-w-[256px]"> <Dropdown.Menu> <Dropdown.Section> <Header>操作</Header> <Dropdown.Item id="cut" textValue="剪切"> <Label>剪切</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>X</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="copy" textValue="复制"> <Label>复制</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>C</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="paste" textValue="粘贴"> <Label>粘贴</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>U</Kbd.Content> </Kbd> </Dropdown.Item> </Dropdown.Section> <Separator /> <Dropdown.Section selectedKeys={textStyles} selectionMode="multiple" onSelectionChange={setTextStyles} > <Header>文本样式</Header> <Dropdown.Item id="bold" textValue="粗体"> <Dropdown.ItemIndicator /> <Label>粗体</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>B</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="italic" textValue="斜体"> <Dropdown.ItemIndicator /> <Label>斜体</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>I</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="underline" textValue="下划线"> <Dropdown.ItemIndicator /> <Label>下划线</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>U</Kbd.Content> </Kbd> </Dropdown.Item> </Dropdown.Section> <Separator /> <Dropdown.Section selectedKeys={textAlignment} selectionMode="single" onSelectionChange={setTextAlignment} > <Header>文本对齐</Header> <Dropdown.Item id="left" textValue="左对齐"> <Dropdown.ItemIndicator type="dot" /> <Label>左对齐</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="alt" /> <Kbd.Content>A</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="center" textValue="居中"> <Dropdown.ItemIndicator type="dot" /> <Label>居中</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="alt" /> <Kbd.Content>H</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="right" textValue="右对齐"> <Dropdown.ItemIndicator type="dot" /> <Label>右对齐</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="alt" /> <Kbd.Content>D</Kbd.Content> </Kbd> </Dropdown.Item> </Dropdown.Section> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 带快捷键 ```tsx "use client"; import {Button, Dropdown, Kbd, Label} from "@heroui/react"; export function WithKeyboardShortcuts() { return ( <Dropdown> <Button aria-label="菜单" variant="secondary"> 操作 </Button> <Dropdown.Popover> <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}> <Dropdown.Item id="new" textValue="新建"> <Label>新建</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>N</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="open" textValue="打开"> <Label>打开</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>O</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="save" textValue="保存"> <Label>保存</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>S</Kbd.Content> </Kbd> </Dropdown.Item> <Dropdown.Item id="delete" textValue="删除" variant="danger"> <Label>删除</Label> <Kbd className="ms-auto" slot="keyboard" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>D</Kbd.Content> </Kbd> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 含子菜单 ```tsx "use client"; import {Button, Dropdown, Label} from "@heroui/react"; export function WithSubmenus() { return ( <Dropdown> <Button aria-label="菜单" variant="secondary"> 分享 </Button> <Dropdown.Popover> <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}> <Dropdown.Item id="copy-link" textValue="复制链接"> <Label>复制链接</Label> </Dropdown.Item> <Dropdown.Item id="facebook" textValue="Facebook"> <Label>Facebook</Label> </Dropdown.Item> <Dropdown.Item id="twitter" textValue="Twitter"> <Label>X / Twitter</Label> </Dropdown.Item> <Dropdown.SubmenuTrigger> <Dropdown.Item id="share" textValue="分享"> <Label>其他</Label> <Dropdown.SubmenuIndicator /> </Dropdown.Item> <Dropdown.Popover> <Dropdown.Menu> <Dropdown.Item id="whatsapp" textValue="WhatsApp"> <Label>WhatsApp</Label> </Dropdown.Item> <Dropdown.Item id="telegram" textValue="Telegram"> <Label>Telegram</Label> </Dropdown.Item> <Dropdown.Item id="discord" textValue="Discord"> <Label>Discord</Label> </Dropdown.Item> <Dropdown.SubmenuTrigger> <Dropdown.Item id="email" textValue="邮件"> <Label>Email</Label> <Dropdown.SubmenuIndicator /> </Dropdown.Item> <Dropdown.Popover> <Dropdown.Menu> <Dropdown.Item id="work" textValue="工作邮箱"> <Label>工作邮箱</Label> </Dropdown.Item> <Dropdown.Item id="personal" textValue="个人邮箱"> <Label>个人邮箱</Label> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown.SubmenuTrigger> </Dropdown.Menu> </Dropdown.Popover> </Dropdown.SubmenuTrigger> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 自定义子菜单指示器 ```tsx "use client"; import {ArrowRight} from "@gravity-ui/icons"; import {Button, Dropdown, Label} from "@heroui/react"; export function WithCustomSubmenuIndicator() { return ( <Dropdown> <Button aria-label="菜单" variant="secondary"> 分享 </Button> <Dropdown.Popover> <Dropdown.Menu onAction={(key) => console.log(`Selected: ${key}`)}> <Dropdown.Item id="copy-link" textValue="复制链接"> <Label>复制链接</Label> </Dropdown.Item> <Dropdown.Item id="facebook" textValue="Facebook"> <Label>Facebook</Label> </Dropdown.Item> <Dropdown.SubmenuTrigger> <Dropdown.Item id="share" textValue="分享"> <Label>更多选项</Label> <Dropdown.SubmenuIndicator> <ArrowRight className="size-3.5 text-muted" /> </Dropdown.SubmenuIndicator> </Dropdown.Item> <Dropdown.Popover> <Dropdown.Menu> <Dropdown.Item id="whatsapp" textValue="WhatsApp"> <Label>WhatsApp</Label> </Dropdown.Item> <Dropdown.Item id="telegram" textValue="Telegram"> <Label>Telegram</Label> </Dropdown.Item> <Dropdown.SubmenuTrigger> <Dropdown.Item id="email" textValue="邮件"> <Label>Email</Label> <Dropdown.SubmenuIndicator> <svg className="size-3.5 text-muted" fill="none" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="2" viewBox="0 0 24 24" > <path d="M9 18l6-6-6-6" /> </svg> </Dropdown.SubmenuIndicator> </Dropdown.Item> <Dropdown.Popover> <Dropdown.Menu> <Dropdown.Item id="work" textValue="工作邮箱"> <Label>工作邮箱</Label> </Dropdown.Item> <Dropdown.Item id="personal" textValue="个人邮箱"> <Label>个人邮箱</Label> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown.SubmenuTrigger> <Dropdown.Item id="discord" textValue="Discord"> <Label>Discord</Label> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown.SubmenuTrigger> <Dropdown.SubmenuTrigger> <Dropdown.Item id="other" textValue="其他"> <Label>其他（默认指示器）</Label> <Dropdown.SubmenuIndicator /> </Dropdown.Item> <Dropdown.Popover> <Dropdown.Menu> <Dropdown.Item id="sms" textValue="SMS"> <Label>SMS</Label> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown.SubmenuTrigger> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 自定义触发器 ```tsx import {ArrowRightFromSquare, Gear, Persons} from "@gravity-ui/icons"; import {Avatar, Dropdown, Label} from "@heroui/react"; export function CustomTrigger() { return ( <Dropdown> <Dropdown.Trigger className="rounded-full"> <Avatar> <Avatar.Image alt="Junior Garcia" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg" /> <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback> </Avatar> </Dropdown.Trigger> <Dropdown.Popover> <div className="px-3 pt-3 pb-1"> <div className="flex items-center gap-2"> <Avatar size="sm"> <Avatar.Image alt="Jane" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg" /> <Avatar.Fallback delayMs={600}>JD</Avatar.Fallback> </Avatar> <div className="flex flex-col gap-0"> <p className="text-sm leading-5 font-medium">Jane Doe</p> <p className="text-xs leading-none text-muted">jane@example.com</p> </div> </div> </div> <Dropdown.Menu> <Dropdown.Item id="dashboard" textValue="仪表盘"> <Label>仪表盘</Label> </Dropdown.Item> <Dropdown.Item id="profile" textValue="个人资料"> <Label>个人资料</Label> </Dropdown.Item> <Dropdown.Item id="settings" textValue="设置"> <div className="flex w-full items-center justify-between gap-2"> <Label>设置</Label> <Gear className="size-3.5 text-muted" /> </div> </Dropdown.Item> <Dropdown.Item id="new-project" textValue="新建项目"> <div className="flex w-full items-center justify-between gap-2"> <Label>创建团队</Label> <Persons className="size-3.5 text-muted" /> </div> </Dropdown.Item> <Dropdown.Item id="logout" textValue="退出登录" variant="danger"> <div className="flex w-full items-center justify-between gap-2"> <Label>退出登录</Label> <ArrowRightFromSquare className="size-3.5 text-danger" /> </div> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 长按触发 ```tsx import {Button, Dropdown, Label} from "@heroui/react"; export function LongPressTrigger() { return ( <Dropdown trigger="longPress"> <Button aria-label="菜单" variant="secondary"> 长按 </Button> <Dropdown.Popover> <Dropdown.Menu> <Dropdown.Item id="new-file" textValue="新建文件"> <Label>新建文件</Label> </Dropdown.Item> <Dropdown.Item id="open-file" textValue="打开文件"> <Label>打开文件</Label> </Dropdown.Item> <Dropdown.Item id="save-file" textValue="保存文件"> <Label>保存文件</Label> </Dropdown.Item> <Dropdown.Item id="delete-file" textValue="删除文件" variant="danger"> <Label>删除文件</Label> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Button, Dropdown, Label} from "@heroui/react"; export function CustomStyles() { return ( <Dropdown> <Button variant="secondary">操作</Button> <Dropdown.Popover className="rounded-xl border border-border/80 bg-surface p-1 shadow-sm"> <Dropdown.Menu> <Dropdown.Item className="rounded-lg data-[focused=true]:bg-default" id="rename" textValue="重命名" > <Label>重命名</Label> </Dropdown.Item> <Dropdown.Item className="rounded-lg data-[focused=true]:bg-default" id="duplicate" textValue="复制" > <Label>复制</Label> </Dropdown.Item> <Dropdown.Item className="rounded-lg data-[focused=true]:bg-danger-soft" id="delete" textValue="删除" variant="danger" > <Label>删除</Label> </Dropdown.Item> </Dropdown.Menu> </Dropdown.Popover> </Dropdown> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Dropdown 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .dropdown { @apply flex flex-col gap-1; } .dropdown__trigger { @apply outline-none; } .dropdown__popover { @apply rounded-lg border border-border bg-overlay p-2; } .dropdown__menu { @apply flex flex-col gap-1; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Dropdown 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/dropdown.css)）： #### 基础类 \[!toc] * `.dropdown` - Dropdown 根容器 * `.dropdown__trigger` - 触发 Dropdown 的按钮或元素 * `.dropdown__popover` - Popover 容器 * `.dropdown__menu` - Popover 内的菜单容器 #### 状态类 \[!toc] * `.dropdown__trigger[data-focus-visible="true"]` - 触发器聚焦状态 * `.dropdown__trigger[data-disabled="true"]` - 触发器禁用状态 * `.dropdown__trigger[data-pressed="true"]` - 触发器按下状态 * `.dropdown__popover[data-entering]` - 进入动画状态 * `.dropdown__popover[data-exiting]` - 退出动画状态 * `.dropdown__menu[data-selection-mode="single"]` - 单选模式 * `.dropdown__menu[data-selection-mode="multiple"]` - 多选模式 ### 菜单组件类 Dropdown 使用 Menu、MenuItem 与 MenuSection 作为底层组件。以下类名也可用于自定义： #### 菜单类 \[!toc] * `.menu` - 菜单容器（[menu.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu.css)） * `[data-slot="separator"]` - 菜单内的分隔线元素 #### 菜单项类 \[!toc] * `.menu-item` - 菜单项容器（[menu-item.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-item.css)） * `.menu-item__indicator` - 选中指示器（对勾或圆点） * `[data-slot="menu-item-indicator--checkmark"]` - 对勾指示器 SVG * `[data-slot="menu-item-indicator--dot"]` - 圆点指示器 SVG * `.menu-item__indicator--submenu` - 子菜单指示器（箭头） * `.menu-item--default` - 默认样式变体 * `.menu-item--danger` - 危险样式变体 #### 菜单项状态类 \[!toc] * `.menu-item[data-focus-visible="true"]` - 聚焦状态（键盘焦点） * `.menu-item[data-focus="true"]` - 聚焦状态 * `.menu-item[data-pressed]` - 按下状态 * `.menu-item[data-hovered]` - 悬停状态 * `.menu-item[data-selected="true"]` - 选中状态 * `.menu-item[data-disabled]` - 禁用状态 * `.menu-item[data-has-submenu="true"]` - 带子菜单的项 * `.menu-item[data-selection-mode="single"]` - 单选模式 * `.menu-item[data-selection-mode="multiple"]` - 多选模式 * `.menu-item[aria-checked="true"]` - 已勾选（ARIA） * `.menu-item[aria-selected="true"]` - 已选中（ARIA） #### 菜单分区类 \[!toc] * `.menu-section` - 菜单分区容器（[menu-section.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/menu-section.css)） ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Hover**：触发器与菜单项上 `:hover` 或 `[data-hovered="true"]` * **Focus**：触发器与菜单项上 `:focus-visible` 或 `[data-focus-visible="true"]` * **Disabled**：触发器与菜单项上 `:disabled` 或 `[data-disabled="true"]` * **Pressed**：触发器与菜单项上 `:active` 或 `[data-pressed="true"]` * **Selected**：菜单项上 `[data-selected="true"]` 或 `[aria-selected="true"]` ## API 参考 ### Dropdown | Prop | 类型 | 默认值 | 描述 | | -------------- | --------------------------- | --------- | ------------------- | | `isOpen` | `boolean` | - | 设置菜单展开状态（受控）。 | | `defaultOpen` | `boolean` | - | 设置菜单默认展开状态（非受控）。 | | `onOpenChange` | `(isOpen: boolean) => void` | - | 展开状态变化时调用的事件处理函数。 | | `trigger` | `"press" \| "longPress"` | `"press"` | 触发菜单的交互类型。 | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | Dropdown 内容。 | ### Dropdown.Trigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------- | --- | ------------------- | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 触发器内容或渲染函数。 | 使用 Button 作为触发器时，同样支持所有 [Button](https://react-spectrum.adobe.com/react-aria/Button.html) props。 ### Dropdown.Popover | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------- | | `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"` | 相对于触发器的 Popover 位置。 | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 子内容。 | 同样支持所有 [Popover](https://react-spectrum.adobe.com/react-aria/Popover.html) props。 ### Dropdown.Menu | Prop | 类型 | 默认值 | 描述 | | --------------------- | ---------------------------------- | -------- | ------------------- | | `selectionMode` | `"single" \| "multiple" \| "none"` | `"none"` | 是否启用单选、多选或不启用选择。 | | `selectedKeys` | `Iterable<Key>` | - | 当前选中的 key（受控）。 | | `defaultSelectedKeys` | `Iterable<Key>` | - | 初始选中的 key（非受控）。 | | `onSelectionChange` | `(keys: Selection) => void` | - | 选中变化时调用的事件处理函数。 | | `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key。 | | `onAction` | `(key: Key) => void` | - | 激活菜单项时调用的事件处理函数。 | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 菜单内容。 | 同样支持所有 [Menu](https://react-spectrum.adobe.com/react-aria/Menu.html#menu) props。 ### Dropdown.Section | Prop | 类型 | 默认值 | 描述 | | --------------------- | --------------------------- | --- | ------------------- | | `selectionMode` | `"single" \| "multiple"` | - | 该分组内菜单项的选择模式。 | | `selectedKeys` | `Iterable<Key>` | - | 当前选中的 key（受控）。 | | `defaultSelectedKeys` | `Iterable<Key>` | - | 初始选中的 key（非受控）。 | | `onSelectionChange` | `(keys: Selection) => void` | - | 选中变化时调用的事件处理函数。 | | `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key。 | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 分组内容。 | 同样支持所有 [MenuSection](https://react-spectrum.adobe.com/react-aria/Menu.html#menusection) props。 ### Dropdown.Item | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------- | ----------- | ------------------- | | `id` | `Key` | - | 菜单项唯一标识。 | | `textValue` | `string` | - | 用于首字母导航的文本内容。 | | `variant` | `"default" \| "danger"` | `"default"` | 菜单项视觉变体。 | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 菜单项内容或渲染函数。 | 同样支持所有 [MenuItem](https://react-spectrum.adobe.com/react-aria/Menu.html#menuitem) props。 ### Dropdown.ItemIndicator | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------- | ------------- | ------------------- | | `type` | `"checkmark" \| "dot"` | `"checkmark"` | 指示器类型。 | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 自定义指示器内容或渲染函数。 | 使用渲染函数时，会传入以下值： | Prop | 类型 | 描述 | | ----------------- | --------- | ------------ | | `isSelected` | `boolean` | 该项是否选中。 | | `isIndeterminate` | `boolean` | 该项是否处于不确定状态。 | ### Dropdown.SubmenuIndicator | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------- | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 自定义指示器内容。 | ### Dropdown.SubmenuTrigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------- | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 子菜单触发器内容。 | 同样支持所有 [SubmenuTrigger](https://react-spectrum.adobe.com/react-aria/Menu.html#submenutrigger) props。 ### Render Props 在 Dropdown.Item 中使用渲染函数时，会传入以下值： | Prop | 类型 | 描述 | | ------------ | --------- | ----------- | | `isSelected` | `boolean` | 该项是否选中。 | | `isFocused` | `boolean` | 该项是否聚焦。 | | `isDisabled` | `boolean` | 该项是否禁用。 | | `isPressed` | `boolean` | 该项是否处于按下状态。 | ## 无障碍 Dropdown 组件实现 ARIA 菜单模式，并提供： * 完整键盘导航（方向键、Home/End、首字母导航） * 屏幕阅读器对操作与选中变化的播报 * 合理的焦点管理 * 禁用态支持 * 长按交互支持 * 子菜单导航 更多信息见 [React Aria Menu 文档](https://react-spectrum.adobe.com/react-aria/Menu.html#menu)。 ## 相关组件 ## Related Components * **Button**: Allows a user to perform an action * **Popover**: Displays content in context with a trigger * **Separator**: Visual divider between content </page> <page url="/cn/docs/react/components/list-box"> # ListBox 列表框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/list-box **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(collections)/list-box.mdx > 列表框展示一组选项，并允许用户选择一个或多个。 ## 用法 ```tsx import { ListBox } from '@heroui/react'; ``` ```tsx import {Avatar, Description, Label, ListBox} from "@heroui/react"; export function Default() { return ( <ListBox aria-label="用户" className="w-[220px]" selectionMode="single"> <ListBox.Item id="1" textValue="Bob"> <Avatar size="sm"> <Avatar.Image alt="Bob" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>B</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Bob</Label> <Description>bob@heroui.com</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="2" textValue="Fred"> <Avatar size="sm"> <Avatar.Image alt="Fred" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" /> <Avatar.Fallback>F</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Fred</Label> <Description>fred@heroui.com</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="3" textValue="Martha"> <Avatar size="sm"> <Avatar.Image alt="Martha" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" /> <Avatar.Fallback>M</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Martha</Label> <Description>martha@heroui.com</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> ); } ``` ## 组件结构 ```tsx import { ListBox, Label, Description, Header } from '@heroui/react'; export default () => ( <ListBox> <ListBox.Item> <Label /> <Description /> <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Section> <Header /> <ListBox.Item> <Label /> </ListBox.Item> </ListBox.Section> </ListBox> ) ``` ## 示例 ### 含禁用项 ```tsx "use client"; import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons"; import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react"; export function WithDisabledItems() { return ( <Surface className="w-[256px] rounded-3xl shadow-surface"> <ListBox aria-label="文件操作" className="w-full p-2" disabledKeys={["delete-file"]} selectionMode="none" onAction={(key) => alert(`已选项目：${key}`)} > <ListBox.Section> <Header>操作</Header> <ListBox.Item id="new-file" textValue="新建文件"> <div className="flex h-8 items-start justify-center pt-px"> <SquarePlus className="size-4 shrink-0 text-muted" /> </div> <div className="flex flex-col"> <Label>新建文件</Label> <Description>创建新文件</Description> </div> <Kbd className="ms-auto" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>N</Kbd.Content> </Kbd> </ListBox.Item> <ListBox.Item id="edit-file" textValue="编辑文件"> <div className="flex h-8 items-start justify-center pt-px"> <Pencil className="size-4 shrink-0 text-muted" /> </div> <div className="flex flex-col"> <Label>编辑文件</Label> <Description>进行修改</Description> </div> <Kbd className="ms-auto" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>E</Kbd.Content> </Kbd> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>危险区域</Header> <ListBox.Item id="delete-file" textValue="删除文件" variant="danger"> <div className="flex h-8 items-start justify-center pt-px"> <TrashBin className="size-4 shrink-0 text-danger" /> </div> <div className="flex flex-col"> <Label>删除文件</Label> <Description>移至废纸篓</Description> </div> <Kbd className="ms-auto" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>D</Kbd.Content> </Kbd> </ListBox.Item> </ListBox.Section> </ListBox> </Surface> ); } ``` ### 分组选项 ```tsx "use client"; import {Pencil, SquarePlus, TrashBin} from "@gravity-ui/icons"; import {Description, Header, Kbd, Label, ListBox, Separator, Surface} from "@heroui/react"; export function WithSections() { return ( <Surface className="w-[256px] rounded-3xl shadow-surface"> <ListBox aria-label="文件操作" className="w-full p-2" selectionMode="none" onAction={(key) => alert(`已选项目：${key}`)} > <ListBox.Section> <Header>操作</Header> <ListBox.Item id="new-file" textValue="新建文件"> <div className="flex h-8 items-start justify-center pt-px"> <SquarePlus className="size-4 shrink-0 text-muted" /> </div> <div className="flex flex-col"> <Label>新建文件</Label> <Description>创建新文件</Description> </div> <Kbd className="ms-auto" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>N</Kbd.Content> </Kbd> </ListBox.Item> <ListBox.Item id="edit-file" textValue="编辑文件"> <div className="flex h-8 items-start justify-center pt-px"> <Pencil className="size-4 shrink-0 text-muted" /> </div> <div className="flex flex-col"> <Label>编辑文件</Label> <Description>进行修改</Description> </div> <Kbd className="ms-auto" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>E</Kbd.Content> </Kbd> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>危险区域</Header> <ListBox.Item id="delete-file" textValue="删除文件" variant="danger"> <div className="flex h-8 items-start justify-center pt-px"> <TrashBin className="size-4 shrink-0 text-danger" /> </div> <div className="flex flex-col"> <Label>删除文件</Label> <Description>移至废纸篓</Description> </div> <Kbd className="ms-auto" variant="light"> <Kbd.Abbr keyValue="command" /> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>D</Kbd.Content> </Kbd> </ListBox.Item> </ListBox.Section> </ListBox> </Surface> ); } ``` ### 多选 ```tsx import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react"; export function MultiSelect() { return ( <Surface className="w-[256px] rounded-3xl shadow-surface"> <ListBox aria-label="用户" selectionMode="multiple"> <ListBox.Item id="1" textValue="Bob"> <Avatar size="sm"> <Avatar.Image alt="Bob" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>B</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Bob</Label> <Description>bob@heroui.com</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="2" textValue="Fred"> <Avatar size="sm"> <Avatar.Image alt="Fred" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" /> <Avatar.Fallback>F</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Fred</Label> <Description>fred@heroui.com</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="3" textValue="Martha"> <Avatar size="sm"> <Avatar.Image alt="Martha" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" /> <Avatar.Fallback>M</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Martha</Label> <Description>martha@heroui.com</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Surface> ); } ``` ### 受控组件 ```tsx "use client"; import type {Selection} from "@heroui/react"; import {Check} from "@gravity-ui/icons"; import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [selected, setSelected] = useState<Selection>(new Set(["1"])); const selectedItems = Array.from(selected); return ( <div className="space-y-4"> <Surface className="w-[256px] rounded-3xl shadow-surface"> <ListBox aria-label="用户" selectedKeys={selected} selectionMode="multiple" onSelectionChange={setSelected} > <ListBox.Item id="1" textValue="Bob"> <Avatar size="sm"> <Avatar.Image alt="Bob" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>B</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Bob</Label> <Description>bob@heroui.com</Description> </div> <ListBox.ItemIndicator> {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)} </ListBox.ItemIndicator> </ListBox.Item> <ListBox.Item id="2" textValue="Fred"> <Avatar size="sm"> <Avatar.Image alt="Fred" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" /> <Avatar.Fallback>F</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Fred</Label> <Description>fred@heroui.com</Description> </div> <ListBox.ItemIndicator> {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)} </ListBox.ItemIndicator> </ListBox.Item> <ListBox.Item id="3" textValue="Martha"> <Avatar size="sm"> <Avatar.Image alt="Martha" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" /> <Avatar.Fallback>M</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Martha</Label> <Description>martha@heroui.com</Description> </div> <ListBox.ItemIndicator> {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)} </ListBox.ItemIndicator> </ListBox.Item> </ListBox> </Surface> <p className="text-sm text-muted"> 已选：{selectedItems.length > 0 ? selectedItems.join("、") : "无"} </p> </div> ); } ``` ### 虚拟滚动 ListBox 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见行，从而高效展示大数据集。 ```tsx "use client"; import {Description, Label, ListBox, ListLayout, Virtualizer} from "@heroui/react"; interface User { id: number; name: string; email: string; } export function Virtualization() { const firstNames = [ "Emma", "Liam", "Olivia", "Noah", "Ava", "James", "Sophia", "Oliver", "Isabella", "Lucas", "Mia", "Ethan", "Charlotte", "Mason", "Amelia", "Logan", "Harper", "Alexander", "Ella", "Benjamin", ]; const lastNames = [ "Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller", "Davis", "Rodriguez", "Martinez", "Anderson", "Taylor", "Thomas", "Jackson", "White", "Harris", "Clark", "Lewis", "Robinson", "Walker", ]; function generateUsers(n: number): User[] { const users: User[] = []; for (let i = 0; i < n; i++) { const firstName = firstNames[i % firstNames.length]; const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length]; const name = `${firstName} ${lastName}`; users.push({ email: `${firstName?.toLowerCase()}.${lastName?.toLowerCase()}@acme.com`, id: i + 1, name, }); } return users; } const users = generateUsers(1000); return ( <Virtualizer layout={ListLayout} layoutOptions={{rowHeight: 50}}> <ListBox aria-label="包含 1000 项的虚拟化列表" className="h-[400px] w-[300px] overflow-y-auto" items={users} > {(user) => ( <ListBox.Item id={user.id} textValue={user.name}> <div className="flex flex-col"> <Label>{user.name}</Label> <Description>{user.email}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> )} </ListBox> </Virtualizer> ); } ``` ### 自定义勾选图标 ```tsx "use client"; import {Check} from "@gravity-ui/icons"; import {Avatar, Description, Label, ListBox, Surface} from "@heroui/react"; export function CustomCheckIcon() { return ( <Surface className="w-[256px] rounded-3xl shadow-surface"> <ListBox aria-label="用户" selectionMode="multiple"> <ListBox.Item id="1" textValue="Bob"> <Avatar size="sm"> <Avatar.Image alt="Bob" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>B</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Bob</Label> <Description>bob@heroui.com</Description> </div> <ListBox.ItemIndicator> {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)} </ListBox.ItemIndicator> </ListBox.Item> <ListBox.Item id="2" textValue="Fred"> <Avatar size="sm"> <Avatar.Image alt="Fred" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" /> <Avatar.Fallback>F</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Fred</Label> <Description>fred@heroui.com</Description> </div> <ListBox.ItemIndicator> {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)} </ListBox.ItemIndicator> </ListBox.Item> <ListBox.Item id="3" textValue="Martha"> <Avatar size="sm"> <Avatar.Image alt="Martha" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" /> <Avatar.Fallback>M</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Martha</Label> <Description>martha@heroui.com</Description> </div> <ListBox.ItemIndicator> {({isSelected}) => (isSelected ? <Check className="size-4 text-accent" /> : null)} </ListBox.ItemIndicator> </ListBox.Item> </ListBox> </Surface> ); } ``` ### 渲染函数 ```tsx "use client"; import {Avatar, Description, Label, ListBox} from "@heroui/react"; export function RenderFunction() { return ( <ListBox aria-label="用户" className="w-[220px]" render={(props) => <div {...props} data-custom="true" />} selectionMode="single" > <ListBox.Item id="1" render={(props) => <span {...props} data-custom="foo" />} textValue="Bob" > <Avatar size="sm"> <Avatar.Image alt="Bob" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>B</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Bob</Label> <Description>bob@heroui.com</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="2" render={(props) => <span {...props} data-custom="bar" />} textValue="Fred" > <Avatar size="sm"> <Avatar.Image alt="Fred" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" /> <Avatar.Fallback>F</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Fred</Label> <Description>fred@heroui.com</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="3" render={(props) => <span {...props} data-custom="baz" />} textValue="Martha" > <Avatar size="sm"> <Avatar.Image alt="Martha" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" /> <Avatar.Fallback>M</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Martha</Label> <Description>martha@heroui.com</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Avatar, Description, Label, ListBox} from "@heroui/react"; export function CustomStyles() { return ( <ListBox aria-label="负责人" className="w-56 rounded-xl border border-border/80 bg-surface p-1 shadow-sm" selectionMode="single" > <ListBox.Item className="rounded-lg data-[focused=true]:bg-accent/10 data-[selected=true]:bg-accent/5" id="1" textValue="Bob" > <Avatar size="sm"> <Avatar.Image alt="Bob" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>B</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Bob</Label> <Description>bob@heroui.com</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item className="rounded-lg data-[focused=true]:bg-accent/10 data-[selected=true]:bg-accent/5" id="2" textValue="Fred" > <Avatar size="sm"> <Avatar.Image alt="Fred" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" /> <Avatar.Fallback>F</Avatar.Fallback> </Avatar> <div className="flex flex-col"> <Label>Fred</Label> <Description>fred@heroui.com</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .list-box { @apply rounded-lg border border-border bg-surface p-2; } .list-box-item { @apply rounded px-2 py-1 cursor-pointer; } .list-box-item--danger { @apply text-danger; } .list-box-item__indicator { @apply text-accent; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ListBox 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/list-box.css)）： #### 基础类 \[!toc] * `.list-box` - ListBox 根容器 * `.list-box-item` - 单个列表项 * `.list-box-item__indicator` - 选中指示图标 * `.list-box-section` - 用于分组的区块容器 #### 变体类 \[!toc] * `.list-box--default` - 默认变体样式 * `.list-box--danger` - 危险变体样式 * `.list-box-item--default` - 列表项默认变体 * `.list-box-item--danger` - 列表项危险变体 #### 状态类 \[!toc] * `.list-box-item[data-selected="true"]` - 选中状态 * `.list-box-item[data-focus-visible="true"]` - 聚焦状态 * `.list-box-item[data-disabled="true"]` - 禁用状态 * `.list-box-item__indicator[data-visible="true"]` - 指示器可见状态 ### 交互状态 该组件同时支持 CSS 伪类与 data 属性： * **悬停**：列表项上 `:hover` 或 `[data-hovered="true"]` * **聚焦**：列表项上 `:focus-visible` 或 `[data-focus-visible="true"]` * **已选中**：列表项上 `[data-selected="true"]` * **禁用**：列表项上 `:disabled` 或 `[data-disabled="true"]` ## API 参考 ### ListBox | Prop | 类型 | 默认值 | 描述 | | --------------------- | -------------------------------------------------------------------------- | ----------- | --------------------- | | `aria-label` | `string` | - | ListBox 的无障碍标签。 | | `aria-labelledby` | `string` | - | 标注 ListBox 的元素 id。 | | `selectionMode` | `"none" \| "single" \| "multiple"` | `"single"` | 选择行为。 | | `selectedKeys` | `Selection` | - | 受控的选中 key。 | | `defaultSelectedKeys` | `Selection` | - | 初始选中 key。 | | `onSelectionChange` | `(keys: Selection) => void` | - | 选中变化时调用的事件处理函数。 | | `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key。 | | `onAction` | `(key: Key) => void` | - | 激活某项时调用的事件处理函数。 | | `variant` | `"default" \| "danger"` | `"default"` | 视觉变体。 | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | ListBox 项与分组。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ListBoxRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### ListBox.Item | Prop | 类型 | 默认值 | 描述 | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | --------------------- | | `id` | `Key` | - | 列表项唯一标识。 | | `textValue` | `string` | - | 用于无障碍与首字母导航的文本值。 | | `isDisabled` | `boolean` | `false` | 是否禁用该项。 | | `variant` | `"default" \| "danger"` | `"default"` | 视觉变体。 | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 列表项内容或渲染函数。 | | `render` | `(props: DetailedHTMLProps<LinkWithRequiredHref, HTMLAnchorElement> \| React.JSX.IntrinsicElements[keyof React.JSX.IntrinsicElements], renderProps: ListBoxItemRenderProps) => ReactElement` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### ListBox.ItemIndicator | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------- | --- | ------------------- | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 自定义指示器内容或渲染函数。 | ### ListBox.Section | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | -------------------- | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 分组内容，包含 Header 与列表项。 | ### RenderProps 在 ListBox.Item 或 ListBox.ItemIndicator 中使用渲染函数时，会传入以下值： | Prop | 类型 | 描述 | | ------------ | --------- | ----------- | | `isSelected` | `boolean` | 该项是否选中。 | | `isFocused` | `boolean` | 该项是否聚焦。 | | `isDisabled` | `boolean` | 该项是否禁用。 | | `isPressed` | `boolean` | 该项是否处于按下状态。 | ### ListLayout | Name | 类型 | 默认值 | 描述 | | ------------------------ | --------------------- | --- | ------------------------------------------- | | `rowHeight` | `number \| undefined` | 48 | 行固定高度（px）。 | | `estimatedRowHeight` | `number \| undefined` | — | 行高可变时的估算高度。 | | `headingHeight` | `number \| undefined` | 48 | 分组标题固定高度（px）。 | | `estimatedHeadingHeight` | `number \| undefined` | — | 标题高度可变时的估算高度。 | | `loaderHeight` | `number \| undefined` | 48 | 加载器元素固定高度（px）。该加载器用于在根级或嵌套行/分组中渲染「加载更多」等内容。 | | `dropIndicatorThickness` | `number \| undefined` | 2 | 放置指示线厚度。 | | `gap` | `number \| undefined` | 0 | 项之间的间距。 | | `padding` | `number \| undefined` | 0 | 列表内边距。 | ## 无障碍 ListBox 组件实现 ARIA listbox 模式，并提供： * 完整键盘导航支持 * 屏幕阅读器对选中变化的播报 * 合理的焦点管理 * 禁用状态支持 * 首字母导航（typeahead）搜索能力 更多信息见 [React Aria ListBox 文档](https://react-spectrum.adobe.com/react-aria/ListBox.html)。 ## 相关组件 ## Related Components * **Select**: Dropdown select control * **ComboBox**: Text input with searchable dropdown list * **Avatar**: Display user profile images </page> <page url="/cn/docs/react/components/tag-group"> # TagGroup 标签组 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/tag-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(collections)/tag-group.mdx > 可聚焦的标签列表，支持键盘导航、选择与移除。 ## 用法 ```tsx import { TagGroup } from '@heroui/react'; ``` ```tsx "use client"; import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons"; import {Tag, TagGroup} from "@heroui/react"; export function TagGroupBasic() { return ( <TagGroup aria-label="标签" selectionMode="single"> <TagGroup.List> <Tag id="default-news"> <SquareArticle /> 资讯 </Tag> <Tag id="default-travel"> <PlanetEarth /> 旅行 </Tag> <Tag id="default-gaming"> <Rocket /> 游戏 </Tag> <Tag id="default-shopping"> <ShoppingBag /> 购物 </Tag> </TagGroup.List> </TagGroup> ); } ``` ## 组件结构 ```tsx import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react'; export default () => ( <TagGroup> <Label /> <TagGroup.List> <Tag> <Tag.RemoveButton /> </Tag> </TagGroup.List> <Description /> <ErrorMessage /> </TagGroup> ) ``` ## 示例 ### 尺寸 ```tsx "use client"; import {Label, Tag, TagGroup} from "@heroui/react"; export function TagGroupSizes() { return ( <div className="flex flex-col gap-6"> <TagGroup selectionMode="single" size="sm"> <Label>小</Label> <TagGroup.List> <Tag>资讯</Tag> <Tag>旅行</Tag> <Tag>游戏</Tag> </TagGroup.List> </TagGroup> <TagGroup selectionMode="single" size="md"> <Label>中</Label> <TagGroup.List> <Tag>资讯</Tag> <Tag>旅行</Tag> <Tag>游戏</Tag> </TagGroup.List> </TagGroup> <TagGroup selectionMode="single" size="lg"> <Label>大</Label> <TagGroup.List> <Tag>资讯</Tag> <Tag>旅行</Tag> <Tag>游戏</Tag> </TagGroup.List> </TagGroup> </div> ); } ``` ### 变体 ```tsx "use client"; import {Label, Tag, TagGroup} from "@heroui/react"; export function TagGroupVariants() { return ( <div className="flex flex-col gap-8"> <TagGroup selectionMode="single" variant="default"> <Label>默认</Label> <TagGroup.List> <Tag>资讯</Tag> <Tag>旅行</Tag> <Tag>游戏</Tag> </TagGroup.List> </TagGroup> <TagGroup selectionMode="single" variant="surface"> <Label>表面</Label> <TagGroup.List> <Tag>资讯</Tag> <Tag>旅行</Tag> <Tag>游戏</Tag> </TagGroup.List> </TagGroup> </div> ); } ``` ### 禁用 ```tsx "use client"; import {Description, Label, Tag, TagGroup} from "@heroui/react"; export function TagGroupDisabled() { return ( <div className="flex flex-col gap-4"> <TagGroup selectionMode="single"> <Label>已禁用的标签</Label> <TagGroup.List> <Tag isDisabled>资讯</Tag> <Tag>旅行</Tag> <Tag isDisabled>游戏</Tag> </TagGroup.List> <Description>部分标签已禁用</Description> </TagGroup> <TagGroup disabledKeys={["travel"]} selectionMode="single"> <Label>禁用的键</Label> <TagGroup.List> <Tag id="news">资讯</Tag> <Tag id="travel">旅行</Tag> <Tag id="gaming">游戏</Tag> </TagGroup.List> <Description>通过 disabledKeys 属性禁用的标签</Description> </TagGroup> </div> ); } ``` ### 选择模式 ```tsx "use client"; import type {Key} from "@heroui/react"; import {Description, Label, Tag, TagGroup} from "@heroui/react"; import {useState} from "react"; export function TagGroupSelectionModes() { const [singleSelected, setSingleSelected] = useState<Iterable<Key>>(new Set(["news"])); const [multipleSelected, setMultipleSelected] = useState<Iterable<Key>>( new Set(["news", "travel"]), ); return ( <div className="flex flex-col gap-8"> <TagGroup selectedKeys={singleSelected} selectionMode="single" onSelectionChange={(keys) => setSingleSelected(keys)} > <Label>单选</Label> <TagGroup.List> <Tag>资讯</Tag> <Tag>旅行</Tag> <Tag>游戏</Tag> <Tag>购物</Tag> </TagGroup.List> <Description>选择一个分类</Description> </TagGroup> <TagGroup selectedKeys={multipleSelected} selectionMode="multiple" onSelectionChange={(keys) => setMultipleSelected(keys)} > <Label>多选</Label> <TagGroup.List> <Tag>资讯</Tag> <Tag>旅行</Tag> <Tag>游戏</Tag> <Tag>购物</Tag> </TagGroup.List> <Description>选择多个分类</Description> </TagGroup> </div> ); } ``` ### 受控组件 ```tsx "use client"; import type {Key} from "@heroui/react"; import {Description, Label, Tag, TagGroup} from "@heroui/react"; import {useState} from "react"; export function TagGroupControlled() { const [selected, setSelected] = useState<Iterable<Key>>(new Set(["news", "travel"])); return ( <div className="flex flex-col gap-3"> <TagGroup selectedKeys={selected} selectionMode="multiple" onSelectionChange={(keys) => setSelected(keys)} > <Label>分类（受控）</Label> <TagGroup.List> <Tag id="news">资讯</Tag> <Tag id="travel">旅行</Tag> <Tag id="gaming">游戏</Tag> <Tag id="shopping">购物</Tag> </TagGroup.List> <Description> 已选：{Array.from(selected).length > 0 ? Array.from(selected).join(", ") : "无"} </Description> </TagGroup> </div> ); } ``` ### 带错误信息 ```tsx "use client"; import type {Key} from "@heroui/react"; import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react"; import {useMemo, useState} from "react"; export function TagGroupWithErrorMessage() { const [selected, setSelected] = useState<Iterable<Key>>(new Set()); const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]); return ( <TagGroup selectedKeys={selected} selectionMode="multiple" onSelectionChange={(keys) => setSelected(keys)} > <Label>设施</Label> <TagGroup.List> <Tag id="laundry">洗衣</Tag> <Tag id="fitness">健身中心</Tag> <Tag id="parking">停车</Tag> <Tag id="pool">游泳池</Tag> <Tag id="breakfast">早餐</Tag> </TagGroup.List> <Description> {isInvalid ? "请至少选择一个分类" : "已选：" + Array.from(selected).join(", ")} </Description> <ErrorMessage>{!!isInvalid && <>请至少选择一个分类</>}</ErrorMessage> </TagGroup> ); } ``` ### 带列表数据 ```tsx "use client"; import type {Key} from "@heroui/react"; import {Avatar, Description, EmptyState, Label, Tag, TagGroup, useListData} from "@heroui/react"; export function TagGroupWithListData() { type User = { id: string; name: string; avatar: string; fallback: string; }; const list = useListData<User>({ getKey: (item) => item.id, initialItems: [ { avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", fallback: "F", id: "fred", name: "Fred", }, { avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", fallback: "M", id: "michael", name: "Michael", }, { avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", fallback: "J", id: "jane", name: "Jane", }, { avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", fallback: "A", id: "alice", name: "Alice", }, { avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", fallback: "B", id: "bob", name: "Bob", }, { avatar: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/black.jpg", fallback: "C", id: "charlie", name: "Charlie", }, ], initialSelectedKeys: new Set(["fred", "michael"]), }); const onRemove = (keys: Set<Key>) => { list.remove(...keys); }; return ( <div className="w-sm"> <TagGroup selectedKeys={list.selectedKeys} selectionMode="multiple" onRemove={onRemove} onSelectionChange={(keys) => list.setSelectedKeys(keys)} > <Label>团队成员</Label> <TagGroup.List items={list.items} renderEmptyState={() => <EmptyState className="p-1">暂无团队成员</EmptyState>} > {(user) => ( <Tag key={user.id} id={user.id} textValue={user.name}> <Avatar className="size-4" size="sm"> <Avatar.Image src={user.avatar} /> <Avatar.Fallback>{user.fallback}</Avatar.Fallback> </Avatar> {user.name} </Tag> )} </TagGroup.List> <Description>为项目选择团队成员</Description> </TagGroup> {list.selectedKeys !== "all" && Array.from(list.selectedKeys).length > 0 && ( <div className="mt-4 flex flex-col gap-2"> <p className="text-sm font-medium text-muted">已选：</p> <div className="flex flex-wrap gap-2"> {Array.from(list.selectedKeys).map((key) => { const user = list.getItem(key); if (!user) return null; return ( <div key={`${user.id}-selected`} className="flex items-center gap-2 rounded-lg bg-surface-tertiary px-2 py-1" > <Avatar className="size-4" size="sm"> <Avatar.Image src={user.avatar} /> <Avatar.Fallback>{user.fallback}</Avatar.Fallback> </Avatar> <span className="text-sm">{user.name}</span> </div> ); })} </div> </div> )} </div> ); } ``` ### 带前缀 ```tsx "use client"; import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons"; import {Avatar, Description, Label, Tag, TagGroup} from "@heroui/react"; export function TagGroupWithPrefix() { return ( <div className="flex flex-col gap-8"> <TagGroup selectionMode="single"> <Label>带图标</Label> <TagGroup.List> <Tag> <SquareArticle /> News </Tag> <Tag> <PlanetEarth /> Travel </Tag> <Tag> <Rocket /> Gaming </Tag> <Tag> <ShoppingBag /> Shopping </Tag> </TagGroup.List> <Description>带图标的标签</Description> </TagGroup> <TagGroup selectionMode="single"> <Label>带头像</Label> <TagGroup.List> <Tag> <Avatar className="size-4"> <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>F</Avatar.Fallback> </Avatar> Fred </Tag> <Tag> <Avatar className="size-4"> <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg" /> <Avatar.Fallback>M</Avatar.Fallback> </Avatar> Michael </Tag> <Tag> <Avatar className="size-4"> <Avatar.Image src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" /> <Avatar.Fallback>J</Avatar.Fallback> </Avatar> Jane </Tag> </TagGroup.List> <Description>带头像的标签</Description> </TagGroup> </div> ); } ``` ### 带移除按钮 ```tsx "use client"; import type {Key} from "@heroui/react"; import {CircleXmarkFill} from "@gravity-ui/icons"; import {Description, EmptyState, Label, Tag, TagGroup} from "@heroui/react"; import {useState} from "react"; export function TagGroupWithRemoveButton() { type TagItem = {id: string; name: string}; const [tags, setTags] = useState<TagItem[]>([ {id: "news", name: "资讯"}, {id: "travel", name: "旅行"}, {id: "gaming", name: "游戏"}, {id: "shopping", name: "购物"}, ]); const [frameworks, setFrameworks] = useState<TagItem[]>([ {id: "react", name: "React"}, {id: "vue", name: "Vue"}, {id: "angular", name: "Angular"}, {id: "svelte", name: "Svelte"}, ]); const onRemoveTags = (keys: Set<Key>) => { setTags(tags.filter((tag) => !keys.has(tag.id))); }; const onRemoveFrameworks = (keys: Set<Key>) => { setFrameworks(frameworks.filter((framework) => !keys.has(framework.id))); }; return ( <div className="flex flex-col gap-8"> <div className="w-sm"> <TagGroup selectionMode="single" onRemove={onRemoveTags}> <Label>默认移除按钮</Label> <TagGroup.List items={tags} renderEmptyState={() => <EmptyState className="p-1">未找到分类</EmptyState>} > {(tag) => ( <Tag key={tag.name} id={tag.id} textValue={tag.name}> {tag.name} </Tag> )} </TagGroup.List> <Description>点击 × 移除标签</Description> </TagGroup> </div> <div className="w-md"> <TagGroup selectionMode="single" onRemove={onRemoveFrameworks}> <Label>自定义移除按钮</Label> <TagGroup.List items={frameworks} renderEmptyState={() => <EmptyState className="p-1">未找到框架</EmptyState>} > {(tag) => ( <Tag key={tag.id} id={tag.id} textValue={tag.name}> {(renderProps) => ( <> {tag.name} {!!renderProps.allowsRemoving && ( <Tag.RemoveButton> <CircleXmarkFill /> </Tag.RemoveButton> )} </> )} </Tag> )} </TagGroup.List> <Description>带图标的自定义移除按钮</Description> </TagGroup> </div> </div> ); } ``` ### 渲染函数 ```tsx "use client"; import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons"; import {Tag, TagGroup} from "@heroui/react"; export function RenderFunction() { return ( <TagGroup aria-label="标签" render={(props) => <div {...props} data-custom="foo" />} selectionMode="single" > <TagGroup.List> <Tag id="default-news"> <SquareArticle /> 资讯 </Tag> <Tag id="default-travel"> <PlanetEarth /> 旅行 </Tag> <Tag id="default-gaming"> <Rocket /> 游戏 </Tag> <Tag id="default-shopping"> <ShoppingBag /> 购物 </Tag> </TagGroup.List> </TagGroup> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {PlanetEarth, Rocket, ShoppingBag, SquareArticle} from "@gravity-ui/icons"; import {Tag, TagGroup} from "@heroui/react"; const tagClass = "group/tag gap-1.5 rounded-full border border-neutral-300/80 bg-white/80 px-2.5 py-1 text-sm font-medium text-neutral-700 shadow-sm ring-1 ring-black/5 backdrop-blur-sm transition-colors data-[selected=true]:border-neutral-500 data-[selected=true]:bg-neutral-900 data-[selected=true]:text-neutral-50 dark:border-neutral-600/80 dark:bg-neutral-900/60 dark:text-neutral-200 dark:ring-white/10 dark:data-[selected=true]:border-neutral-400 dark:data-[selected=true]:bg-neutral-100 dark:data-[selected=true]:text-neutral-900"; const iconClass = "size-4 shrink-0 text-neutral-500 group-data-[selected=true]/tag:text-current dark:text-neutral-400"; export function CustomStyles() { return ( <TagGroup aria-label="主题" selectionMode="single"> <TagGroup.List className="gap-2"> <Tag className={tagClass} id="news"> <SquareArticle className={iconClass} /> 资讯 </Tag> <Tag className={tagClass} id="travel"> <PlanetEarth className={iconClass} /> 旅行 </Tag> <Tag className={tagClass} id="gaming"> <Rocket className={iconClass} /> 游戏 </Tag> <Tag className={tagClass} id="shopping"> <ShoppingBag className={iconClass} /> 购物 </Tag> </TagGroup.List> </TagGroup> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .tag-group { @apply flex flex-col gap-2; } .tag-group__list { @apply flex flex-wrap gap-2; } .tag { @apply rounded-full px-3 py-1; } .tag__remove-button { @apply ml-1; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 TagGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag-group.css) 与 [tag.css](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tag.css)）： #### 基础类 \[!toc] * `.tag-group` - TagGroup 根容器 * `.tag-group__list` - 标签列表容器 * `.tag` - 标签基础样式 * `.tag__remove-button` - 移除按钮触发器 #### 插槽类 \[!toc] * `.tag-group [slot="description"]` - Description 插槽样式 * `.tag-group [slot="errorMessage"]` - ErrorMessage 插槽样式 #### 尺寸类 \[!toc] * `.tag--sm` - 小尺寸标签 * `.tag--md` - 中尺寸标签（默认） * `.tag--lg` - 大尺寸标签 #### 变体类 \[!toc] * `.tag--default` - 默认变体 * `.tag--surface` - 带 Surface 背景的变体 #### 状态类 \[!toc] * `.tag[data-selected="true"]` - 选中状态 * `.tag[data-disabled="true"]` - 禁用状态 * `.tag[data-hovered="true"]` - 悬停状态 * `.tag[data-pressed="true"]` - 按下状态 * `.tag[data-focus-visible="true"]` - 聚焦状态（键盘焦点） ### 交互状态 该组件同时支持 CSS 伪类与 data 属性： * **悬停**：标签上 `:hover` 或 `[data-hovered="true"]` * **聚焦**：标签上 `:focus-visible` 或 `[data-focus-visible="true"]` * **按下**：标签上 `:active` 或 `[data-pressed="true"]` * **已选中**：标签上 `[data-selected="true"]` 或 `[aria-selected="true"]` * **禁用**：标签上 `:disabled` 或 `[data-disabled="true"]` ## API 参考 ### TagGroup | Prop | 类型 | 默认值 | 描述 | | --------------------- | ----------------------------------------------------------------- | ----------- | --------------------- | | `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | 允许的选择类型。 | | `selectedKeys` | `Selection` | - | 当前选中的 key（受控）。 | | `defaultSelectedKeys` | `Selection` | - | 初始选中的 key（非受控）。 | | `onSelectionChange` | `(keys: Selection) => void` | - | 选中变化时调用的事件处理函数。 | | `disabledKeys` | `Iterable<Key>` | - | 禁用标签的 key。 | | `isDisabled` | `boolean` | - | 是否禁用整个 TagGroup。 | | `onRemove` | `(keys: Set<Key>) => void` | - | 移除标签时调用的事件处理函数。 | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | 组内标签尺寸。 | | `variant` | `"default" \| "surface"` | `"default"` | 标签视觉变体。 | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | TagGroup 内容或渲染函数。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### TagGroup.List | Prop | 类型 | 默认值 | 描述 | | ------------------ | -------------------------------------------------------------------------- | --- | --------------------- | | `items` | `Iterable<T>` | - | 标签列表要展示的数据项。 | | `renderEmptyState` | `() => ReactNode` | - | 列表为空时的渲染函数。 | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 标签列表内容或渲染函数。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagListRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Tag | Prop | 类型 | 默认值 | 描述 | | ------------ | ---------------------------------------------------------------------- | --- | --------------------- | | `id` | `Key` | - | 标签唯一标识。 | | `textValue` | `string` | - | 标签内容的字符串表示，用于无障碍。 | | `isDisabled` | `boolean` | - | 是否禁用该标签。 | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 标签内容或渲染函数。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TagRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | **提示：** `size`、`variant` 由父级 `TagGroup` 继承，无法在单个 `Tag` 上直接设置。 ### Tag.RemoveButton | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------- | | `className` | `string` | - | 额外的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 自定义移除按钮内容（默认为关闭图标）。 | **提示：** `Tag.RemoveButton` 支持类似 `SearchField.ClearButton` 的定制方式。当为 `TagGroup` 提供 `onRemove` 时： * **自动渲染**：若 `Tag` 的子节点中未包含自定义 `Tag.RemoveButton`，会自动渲染默认移除按钮。 * **自定义按钮**：若在 `Tag` 下提供了自定义 `Tag.RemoveButton`，将替换自动渲染的按钮。 * **自定义图标**：可向 `Tag.RemoveButton` 传入自定义子内容（如图标）以改变外观。 **示例 — 自动渲染（默认）**： ```tsx <TagGroup onRemove={handleRemove}> <TagGroup.List> <Tag id="news">News</Tag> {/* Remove button is automatically rendered */} </TagGroup.List> </TagGroup> ``` **示例 — 自定义 RemoveButton（带图标）**： ```tsx <TagGroup onRemove={handleRemove}> <TagGroup.List> <Tag id="news"> News <Tag.RemoveButton> <CustomIcon /> </Tag.RemoveButton> </Tag> </TagGroup.List> </TagGroup> ``` **示例 — 在 render props 中使用自定义 RemoveButton**： ```tsx <Tag id="news"> {(renderProps) => ( <> News {!!renderProps.allowsRemoving && ( <Tag.RemoveButton> <CustomIcon /> </Tag.RemoveButton> )} </> )} </Tag> ``` ### RenderProps 在 TagGroup.List 中使用渲染函数时，会传入以下值： | Prop | 类型 | 描述 | | ---------------- | --------- | ------------ | | `isSelected` | `boolean` | 标签是否选中。 | | `isDisabled` | `boolean` | 标签是否禁用。 | | `isHovered` | `boolean` | 标签是否悬停。 | | `isPressed` | `boolean` | 标签是否按下。 | | `isFocused` | `boolean` | 标签是否聚焦。 | | `isFocusVisible` | `boolean` | 标签是否为可见键盘焦点。 | ## 相关组件 ## Related Components * **Label**: Accessible label for form controls * **Description**: Helper text for form fields * **ErrorMessage**: Displays validation error messages for components with validation support </page> <page url="/cn/docs/react/components/color-area"> # ColorArea 颜色区域 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/color-area **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(colors)/color-area.mdx > 二维颜色选择器，允许用户从渐变区域中选择颜色 ## 用法 ```tsx import { ColorArea } from '@heroui/react'; ``` ```tsx import {ColorArea} from "@heroui/react"; export function ColorAreaBasic() { return ( <ColorArea defaultValue="rgb(116, 52, 255)"> <ColorArea.Thumb /> </ColorArea> ); } ``` ## 组件结构 ```tsx import { ColorArea } from '@heroui/react'; export default () => ( <ColorArea> <ColorArea.Thumb /> </ColorArea> ); ``` ## 示例 ### 带定位点 ```tsx import {ColorArea} from "@heroui/react"; export function ColorAreaWithDots() { return ( <ColorArea showDots defaultValue="hsl(200, 100%, 50%)"> <ColorArea.Thumb /> </ColorArea> ); } ``` ### 色彩空间与通道 使用 `colorSpace` 设置颜色空间（RGB、HSL、HSB），使用 `xChannel`/`yChannel` 自定义各轴显示的颜色通道。 ```tsx "use client"; import type {ColorSpace, Key} from "@heroui/react"; import {ColorArea, Label, ListBox, Select, parseColor} from "@heroui/react"; import {useState} from "react"; type ColorChannel = "hue" | "saturation" | "brightness" | "lightness" | "red" | "green" | "blue"; interface ChannelOption { id: ColorChannel; name: string; } const colorSpaces: Array<{id: ColorSpace; name: string}> = [ {id: "rgb", name: "RGB"}, {id: "hsl", name: "HSL"}, {id: "hsb", name: "HSB"}, ]; const channelsBySpace: Record<ColorSpace, ChannelOption[]> = { hsb: [ {id: "hue", name: "Hue"}, {id: "saturation", name: "Saturation"}, {id: "brightness", name: "Brightness"}, ], hsl: [ {id: "hue", name: "Hue"}, {id: "saturation", name: "Saturation"}, {id: "lightness", name: "Lightness"}, ], rgb: [ {id: "red", name: "Red"}, {id: "green", name: "Green"}, {id: "blue", name: "Blue"}, ], }; export function ColorAreaSpaceAndChannels() { const [colorSpace, setColorSpace] = useState<ColorSpace>("hsb"); const [color, setColor] = useState(() => parseColor("hsb(219, 58%, 93%)")); const channels = channelsBySpace[colorSpace]; const defaultX = colorSpace === "rgb" ? "blue" : "saturation"; const defaultY = colorSpace === "rgb" ? "green" : colorSpace === "hsl" ? "lightness" : "brightness"; const [xChannel, setXChannel] = useState<ColorChannel>(defaultX); const [yChannel, setYChannel] = useState<ColorChannel>(defaultY); const handleColorSpaceChange = (newSpace: Key | null) => { if (!newSpace) return; const space = newSpace as ColorSpace; setColorSpace(space); // Reset channels to appropriate defaults for the new color space if (space === "rgb") { setXChannel("blue"); setYChannel("green"); } else if (space === "hsl") { setXChannel("saturation"); setYChannel("lightness"); } else { setXChannel("saturation"); setYChannel("brightness"); } }; // Filter out the other channel from options (can't have same channel on both axes) const xChannelOptions = channels.filter((c) => c.id !== yChannel); const yChannelOptions = channels.filter((c) => c.id !== xChannel); return ( <div className="flex flex-col items-center gap-6"> {/* Controls */} <div className="flex gap-4"> {/* Color Space Select */} <Select className="w-32" value={colorSpace} onChange={handleColorSpaceChange}> <Label>Color Space</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {colorSpaces.map((space) => ( <ListBox.Item key={space.id} id={space.id} textValue={space.name}> {space.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> {/* X Channel Select */} <Select className="w-36" value={xChannel} onChange={(value) => value && setXChannel(value as ColorChannel)} > <Label>X Axis</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {xChannelOptions.map((channel) => ( <ListBox.Item key={channel.id} id={channel.id} textValue={channel.name}> {channel.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> {/* Y Channel Select */} <Select className="w-36" value={yChannel} onChange={(value) => value && setYChannel(value as ColorChannel)} > <Label>Y Axis</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {yChannelOptions.map((channel) => ( <ListBox.Item key={channel.id} id={channel.id} textValue={channel.name}> {channel.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> </div> {/* Color Area */} <ColorArea colorSpace={colorSpace} value={color} xChannel={xChannel} yChannel={yChannel} onChange={setColor} > <ColorArea.Thumb /> </ColorArea> {/* Color Value Display */} <div className="flex items-center gap-3"> <div className="size-8 rounded-md border border-default" style={{backgroundColor: color.toString("css")}} /> <code className="rounded bg-default/50 px-2 py-1 text-sm"> {color.toString(colorSpace)} </code> </div> </div> ); } ``` ### 禁用 ```tsx import {ColorArea} from "@heroui/react"; export function ColorAreaDisabled() { return ( <ColorArea isDisabled defaultValue="hsl(200, 100%, 50%)"> <ColorArea.Thumb /> </ColorArea> ); } ``` ### 受控组件 ```tsx "use client"; import type {Color} from "@heroui/react"; import {ColorArea, ColorSwatch, parseColor} from "@heroui/react"; import {useState} from "react"; export function ColorAreaControlled() { const [color, setColor] = useState<Color>(parseColor("#9B80FF")); return ( <div className="flex flex-col gap-4"> <ColorArea colorSpace="rgb" value={color} xChannel="red" yChannel="green" onChange={setColor}> <ColorArea.Thumb /> </ColorArea> <div className="flex w-[300px] items-center gap-3"> <ColorSwatch color={color} size="md" /> <p className="text-sm text-muted"> Current color:{" "} <span className="font-medium">{color ? color.toString("hex") : "(empty)"}</span> </p> </div> </div> ); } ``` ### 渲染函数 ```tsx "use client"; import {ColorArea} from "@heroui/react"; export function RenderFunction() { return ( <ColorArea defaultValue="rgb(116, 52, 255)" render={(props) => <div {...props} data-custom="slider" />} > <ColorArea.Thumb render={(props) => <div {...props} data-custom="thumb" />} /> </ColorArea> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {ColorArea} from "@heroui/react"; export function CustomStyles() { return ( <ColorArea className="size-44 rounded-3xl" defaultValue="rgb(116, 52, 255)"> <ColorArea.Thumb className="size-5 rounded-full border-4 border-white" /> </ColorArea> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 ColorArea 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .color-area { @apply rounded-3xl; } .color-area__thumb { @apply size-5 border-4; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ColorArea 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-area.css)）： #### 基础类 \[!toc] * `.color-area` - 渐变背景与内阴影的基础样式 * `.color-area--show-dots` - 添加点阵网格覆盖层以精确选色 #### 元素类 \[!toc] * `.color-area__thumb` - 可拖拽的滑块指示器 ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Disabled**：`[data-disabled="true"]` * **Focus**：`[data-focus-visible="true"]` * **Dragging**：`[data-dragging="true"]`（仅 thumb） ## API 参考 ### ColorArea 继承自 [React Aria ColorArea](https://react-spectrum.adobe.com/react-aria/ColorArea.html)。 | Prop | 类型 | 默认值 | 描述 | | -------------- | ---------------------------------------------------------------------------- | -------------- | -------------------------- | | `value` | `string \| Color` | - | 当前颜色值（受控） | | `defaultValue` | `string \| Color` | - | 默认颜色值（非受控） | | `onChange` | `(color: Color) => void` | - | 拖拽过程中颜色变化时的回调 | | `onChangeEnd` | `(color: Color) => void` | - | 用户停止拖拽时的回调 | | `xChannel` | `ColorChannel` | `"saturation"` | 水平轴的颜色通道 | | `yChannel` | `ColorChannel` | `"brightness"` | 垂直轴的颜色通道 | | `colorSpace` | `ColorSpace` | - | 通道使用的颜色空间 | | `isDisabled` | `boolean` | `false` | 是否禁用 | | `showDots` | `boolean` | `false` | 是否显示点阵网格覆盖层 | | `className` | `string` | - | 附加 CSS 类 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorAreaRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### ColorArea.Thumb | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------------------------------------------------------- | --- | -------------------------- | | `className` | `string` | - | 附加 CSS 类 | | `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | 内联样式或 render props 函数 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorThumbRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ## 相关组件 ## Related Components * **ColorSwatch**: Visual preview of a color value * **ColorSwatchPicker**: Color swatch selection from a list of colors * **ColorField**: Input for entering color values with hex format </page> <page url="/cn/docs/react/components/color-field"> # ColorField 颜色输入框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/color-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(colors)/color-field.mdx > 基于 React Aria ColorField 的颜色输入字段，支持标签、描述与验证 ## 用法 ```tsx import { ColorField, parseColor } from '@heroui/react'; ``` ```tsx "use client"; import type {Color} from "@heroui/react"; import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react"; import {useState} from "react"; export function Basic() { const [color, setColor] = useState<Color | null>(parseColor("#0485F7")); return ( <ColorField className="w-[280px]" name="color" value={color} onChange={setColor}> <Label>颜色</Label> <ColorField.Group> <ColorField.Prefix> <ColorSwatch color={color ?? undefined} size="xs" /> </ColorField.Prefix> <ColorField.Input /> </ColorField.Group> </ColorField> ); } ``` ## 组件结构 ```tsx import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react'; export default () => ( <ColorField> <Label /> <ColorField.Group> <ColorField.Prefix> <ColorSwatch color="#000000" /> </ColorField.Prefix> <ColorField.Input /> </ColorField.Group> <Description /> <FieldError /> </ColorField> ) ``` > **ColorField** 将标签、颜色输入、描述与错误合并为单个无障碍组件。 ## 示例 ### 变体 ColorField.Group 组件支持两种视觉变体： * **`primary`**（默认）- 标准样式带阴影，适用于大多数场景 * **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内 ```tsx import {ColorField, Label} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-4"> <ColorField className="w-[280px]" defaultValue="#0485F7" name="primary-color"> <Label>主要变体</Label> <ColorField.Group variant="primary"> <ColorField.Input /> </ColorField.Group> </ColorField> <ColorField className="w-[280px]" defaultValue="#F43F5E" name="secondary-color"> <Label>次要变体</Label> <ColorField.Group variant="secondary"> <ColorField.Input /> </ColorField.Group> </ColorField> </div> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 组件内使用时，在 ColorField.Group 上使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。 ```tsx import {ColorField, Description, Label, Surface} from "@heroui/react"; export function OnSurface() { return ( <Surface className="w-[320px] p-4"> <ColorField defaultValue="#3B82F6" name="color"> <Label>主题色</Label> <ColorField.Group variant="secondary"> <ColorField.Input /> </ColorField.Group> <Description>选择你的主题色</Description> </ColorField> </Surface> ); } ``` ### 带描述 ```tsx import {ColorField, Description, Label} from "@heroui/react"; export function WithDescription() { return ( <div className="flex flex-col gap-4"> <ColorField className="w-[280px]" defaultValue="#3B82F6" name="color"> <Label>主色</Label> <ColorField.Group> <ColorField.Input /> </ColorField.Group> <Description>输入品牌主色</Description> </ColorField> <ColorField className="w-[280px]" defaultValue="#F59E0B" name="accent-color"> <Label>强调色</Label> <ColorField.Group> <ColorField.Input /> </ColorField.Group> <Description>用于高亮与行动按钮</Description> </ColorField> </div> ); } ``` ### 必填字段 ```tsx import {ColorField, Description, Label} from "@heroui/react"; export function Required() { return ( <div className="flex flex-col gap-4"> <ColorField isRequired className="w-[280px]" name="color"> <Label>品牌色</Label> <ColorField.Group> <ColorField.Input placeholder="#000000" /> </ColorField.Group> </ColorField> <ColorField isRequired className="w-[280px]" name="theme-color"> <Label>主题色</Label> <ColorField.Group> <ColorField.Input placeholder="#000000" /> </ColorField.Group> <Description>必填项</Description> </ColorField> </div> ); } ``` ### 禁用 ```tsx "use client"; import {ColorField, Description, Label} from "@heroui/react"; export function Disabled() { return ( <div className="flex flex-col gap-4"> <ColorField isDisabled className="w-[280px]" defaultValue="#0485F7" name="color"> <Label>颜色</Label> <ColorField.Group> <ColorField.Input /> </ColorField.Group> <Description>该颜色字段已禁用</Description> </ColorField> <ColorField isDisabled className="w-[280px]" name="color-empty"> <Label>颜色</Label> <ColorField.Group> <ColorField.Input placeholder="#000000" /> </ColorField.Group> <Description>该颜色字段已禁用</Description> </ColorField> </div> ); } ``` ### 宽度充满 ```tsx import {ColorField, Label} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <ColorField fullWidth defaultValue="#10B981" name="color"> <Label>品牌色</Label> <ColorField.Group> <ColorField.Input /> </ColorField.Group> </ColorField> <ColorField fullWidth defaultValue="#8B5CF6" name="color-with-suffix"> <Label>主题色</Label> <ColorField.Group> <ColorField.Input /> </ColorField.Group> </ColorField> </div> ); } ``` ### 表单校验 将 `isInvalid` 与 `FieldError` 一起使用以显示验证消息。 ```tsx import {ColorField, FieldError, Label} from "@heroui/react"; export function Invalid() { return ( <div className="flex flex-col gap-4"> <ColorField isInvalid isRequired className="w-[280px]" name="color"> <Label>颜色</Label> <ColorField.Group> <ColorField.Input placeholder="#000000" /> </ColorField.Group> <FieldError>请输入有效的十六进制颜色</FieldError> </ColorField> <ColorField isInvalid className="w-[280px]" name="invalid-color"> <Label>背景色</Label> <ColorField.Group> <ColorField.Input defaultValue="not-a-color" /> </ColorField.Group> <FieldError>颜色格式无效，请使用十六进制（例如 #FF5733）</FieldError> </ColorField> </div> ); } ``` ### 分量编辑 ColorField 支持通过设置 `colorSpace` 与 `channel` 属性编辑单个颜色通道（hue、saturation、lightness、red、green、blue、alpha）。 ```tsx "use client"; import type {Color} from "@heroui/react"; import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react"; import {useState} from "react"; export function ChannelEditing() { const [color, setColor] = useState<Color | null>(parseColor("#7F007F")); return ( <div className="flex flex-col gap-4"> <p className="text-sm text-muted">分别编辑 HSL 通道：</p> <div className="flex gap-4"> <ColorField channel="hue" className="w-[100px]" colorSpace="hsl" name="hue" value={color} onChange={setColor} > <Label>色相</Label> <ColorField.Group> <ColorField.Input /> </ColorField.Group> </ColorField> <ColorField channel="saturation" className="w-[100px]" colorSpace="hsl" name="saturation" value={color} onChange={setColor} > <Label>饱和度</Label> <ColorField.Group> <ColorField.Input /> <ColorField.Suffix> <span className="text-sm text-muted">%</span> </ColorField.Suffix> </ColorField.Group> </ColorField> <ColorField channel="lightness" className="w-[100px]" colorSpace="hsl" name="lightness" value={color} onChange={setColor} > <Label>明度</Label> <ColorField.Group> <ColorField.Input /> <ColorField.Suffix> <span className="text-sm text-muted">%</span> </ColorField.Suffix> </ColorField.Group> </ColorField> </div> <div className="flex items-center gap-2"> <ColorSwatch color={color ?? undefined} size="md" /> <span className="text-sm">当前：{color ? color.toString("hex") : "（空）"}</span> </div> </div> ); } ``` ### 受控组件 控制值以与其他组件或状态管理同步。 ```tsx "use client"; import type {Color} from "@heroui/react"; import {Button, ColorField, ColorSwatch, Description, Label, parseColor} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [value, setValue] = useState<Color | null>(parseColor("#0485F7")); return ( <div className="flex flex-col gap-4"> <ColorField className="w-[280px]" name="color" value={value} onChange={setValue}> <Label>颜色</Label> <ColorField.Group> <ColorField.Prefix> <ColorSwatch color={value ?? undefined} size="xs" /> </ColorField.Prefix> <ColorField.Input /> </ColorField.Group> <Description>当前值：{value ? value.toString("hex") : "（空）"}</Description> </ColorField> <div className="flex gap-2"> <Button variant="tertiary" onPress={() => setValue(parseColor("#EF4444"))}> 设为红色 </Button> <Button variant="tertiary" onPress={() => setValue(parseColor("#10B981"))}> 设为绿色 </Button> <Button variant="tertiary" onPress={() => setValue(null)}> 清空 </Button> </div> </div> ); } ``` ### 表单示例 包含验证与提交处理的完整表单示例。 ```tsx "use client"; import type {Color} from "@heroui/react"; import {Button, ColorField, ColorSwatch, Description, Form, Label} from "@heroui/react"; import {useState} from "react"; export function FormExample() { const [value, setValue] = useState<Color | null>(null); const [isSubmitting, setIsSubmitting] = useState(false); const handleSubmit = (e: React.SyntheticEvent<HTMLFormElement>) => { e.preventDefault(); if (!value) { return; } setIsSubmitting(true); // Simulate API call setTimeout(() => { console.log("已提交颜色：", {color: value.toString("hex")}); setValue(null); setIsSubmitting(false); }, 1500); }; return ( <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}> <ColorField fullWidth isRequired className="w-full" name="brand-color" value={value} onChange={setValue} > <Label>品牌色</Label> <ColorField.Group> <ColorField.Prefix> <ColorSwatch color={value ?? undefined} size="xs" /> </ColorField.Prefix> <ColorField.Input placeholder="#000000" /> </ColorField.Group> <Description>选择品牌主色</Description> </ColorField> <Button className="w-full" isDisabled={!value} isPending={isSubmitting} type="submit" variant="primary" > {isSubmitting ? "保存中…" : "保存颜色"} </Button> </Form> ); } ``` ### 渲染函数 ```tsx "use client"; import type {Color} from "@heroui/react"; import {ColorField, ColorSwatch, Label, parseColor} from "@heroui/react"; import {useState} from "react"; export function RenderFunction() { const [color, setColor] = useState<Color | null>(parseColor("#0485F7")); return ( <ColorField className="w-[280px]" name="color" render={(props) => <div {...props} data-custom="foo" />} value={color} onChange={setColor} > <Label>颜色</Label> <ColorField.Group render={(props) => <div {...props} data-custom="foo" />}> <ColorField.Prefix> <ColorSwatch color={color ?? undefined} size="xs" /> </ColorField.Prefix> <ColorField.Input /> </ColorField.Group> </ColorField> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import type {Color} from "@heroui/react"; import {ColorField, ColorSwatch, Description, Label, parseColor} from "@heroui/react"; import {useState} from "react"; export function CustomStyles() { const [color, setColor] = useState<Color | null>(parseColor("#6366F1")); return ( <ColorField className="w-full max-w-xs gap-1.5" name="accent-color" value={color} onChange={setColor} > <Label className="font-medium text-foreground">强调色</Label> <Description>应用于按钮、链接和焦点环。</Description> <ColorField.Group className="rounded-xl bg-default shadow-none focus-within:ring-2 focus-within:ring-accent/15" variant="secondary" > <ColorField.Prefix> <ColorSwatch className="rounded-md" color={color ?? undefined} size="xs" /> </ColorField.Prefix> <ColorField.Input className="font-mono text-sm text-foreground placeholder:text-muted" /> </ColorField.Group> </ColorField> ); } ``` ### 全局 CSS ColorField 默认样式较少。覆盖 `.color-field` 类以自定义容器样式。 ```css @layer components { .color-field { @apply flex flex-col gap-1; &[data-invalid="true"], &[aria-invalid="true"] { [data-slot="description"] { @apply hidden; } } [data-slot="label"] { @apply w-fit; } [data-slot="description"] { @apply px-1; } } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 * `.color-field` – 最小样式的根容器（`flex flex-col gap-1`） > **Note:** 子组件（[Label](/docs/react/components/label)、[Description](/docs/react/components/description)、[FieldError](/docs/react/components/field-error)）有各自的 CSS 类与样式。请参阅各自文档了解自定义选项。ColorField.Group 样式见下方 API 参考。 ### 交互状态 ColorField 根据状态自动管理以下 data 属性： * **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` - 无效时自动隐藏 description slot * **Required**：`[data-required="true"]` - `isRequired` 为 true 时应用 * **Disabled**：`[data-disabled="true"]` - `isDisabled` 为 true 时应用 * **Focus Within**：`[data-focus-within="true"]` - 任一子 input 聚焦时应用 ## API 参考 ### ColorField ColorField 继承 React Aria [ColorField](https://react-aria.adobe.com/ColorField.md) 组件的所有属性。 #### Base Props | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------- | ------- | ---------------------------------------- | | `children` | `React.ReactNode \| (values: ColorFieldRenderProps) => React.ReactNode` | - | 子组件（Label、ColorField.Group 等）或 render 函数 | | `className` | `string \| (values: ColorFieldRenderProps) => string` | - | CSS 类，支持 render props | | `style` | `React.CSSProperties \| (values: ColorFieldRenderProps) => React.CSSProperties` | - | 内联样式，支持 render props | | `fullWidth` | `boolean` | `false` | 是否占满容器宽度 | | `id` | `string` | - | 元素唯一标识符 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorFieldRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | #### Value Props | Prop | 类型 | 默认值 | 描述 | | -------------- | -------------------------------- | --- | -------- | | `value` | `Color \| null` | - | 当前值（受控） | | `defaultValue` | `Color \| null` | - | 默认值（非受控） | | `onChange` | `(color: Color \| null) => void` | - | 值变化时的回调 | #### Channel Props | Prop | 类型 | 默认值 | 描述 | | ------------ | -------------- | --- | ------------------------- | | `colorSpace` | `ColorSpace` | - | 提供 `channel` 时颜色字段操作的颜色空间 | | `channel` | `ColorChannel` | - | 要编辑的颜色通道。未提供时编辑 hex 值 | #### Validation Props | Prop | 类型 | 默认值 | 描述 | | -------------------- | ---------------------------------------------------------------- | ---------- | ------------------------ | | `isRequired` | `boolean` | `false` | 表单提交前是否必须输入 | | `isInvalid` | `boolean` | - | 值是否无效 | | `validate` | `(value: Color) => ValidationError \| true \| null \| undefined` | - | 自定义验证函数 | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单验证还是 ARIA 属性 | #### State Props | Prop | 类型 | 默认值 | 描述 | | ----------------- | --------- | --- | ---------- | | `isDisabled` | `boolean` | - | 是否禁用 | | `isReadOnly` | `boolean` | - | 是否可选中但不可更改 | | `isWheelDisabled` | `boolean` | - | 是否禁用滚轮更改值 | #### Form Props | Prop | 类型 | 默认值 | 描述 | | ----------- | --------- | --- | ---------------------- | | `name` | `string` | - | HTML 表单提交时 input 元素的名称 | | `autoFocus` | `boolean` | - | 渲染时是否自动聚焦 | #### Accessibility Props | Prop | 类型 | 默认值 | 描述 | | ------------------ | -------- | --- | ------------ | | `aria-label` | `string` | - | 无可见标签时的无障碍标签 | | `aria-labelledby` | `string` | - | 标注此字段的元素 ID | | `aria-describedby` | `string` | - | 描述此字段的元素 ID | | `aria-details` | `string` | - | 包含附加详情的元素 ID | ### Composition Components ColorField 与以下需单独导入并直接使用的组件配合： * **Label** - 来自 `@heroui/react` 的字段标签组件 * **ColorField.Group** - 颜色输入组组件（见下方文档） * **ColorField.Input** - ColorField.Group 内的 input 元素 * **ColorField.Prefix** / **ColorField.Suffix** - 输入组的前缀与后缀 slot * **ColorSwatch** - 来自 `@heroui/react` 的颜色预览组件 * **Description** - 来自 `@heroui/react` 的帮助文本组件 * **FieldError** - 来自 `@heroui/react` 的验证错误消息 每个组件有各自的 props API。在 ColorField 内直接使用它们进行组合： ```tsx import {ColorField, Label, ColorSwatch, Description, FieldError, parseColor} from '@heroui/react'; <ColorField isRequired isInvalid={hasError} value={color} onChange={setColor} > <Label>Brand Color</Label> <ColorField.Group> <ColorField.Prefix> <ColorSwatch color={color?.toString("hex") || "#E4E4E7"} /> </ColorField.Prefix> <ColorField.Input /> </ColorField.Group> <Description>Select your brand's primary color.</Description> <FieldError>Please enter a valid color.</FieldError> </ColorField> ``` ### Color Types ColorField 使用 React Aria Components 的 `Color` 对象： ```tsx import {parseColor} from '@heroui/react'; // Parse from hex string const color = parseColor('#3B82F6'); // Get hex string from color const hex = color.toString('hex'); // "#3b82f6" // Get RGB values const rgb = color.toString('rgb'); // "rgb(59, 130, 246)" // Use in ColorField <ColorField value={color} onChange={setColor}> {/* ... */} </ColorField> ``` ### Render Props 对 `className`、`style` 或 `children` 使用 render props 时，可使用以下值： | Prop | 类型 | 描述 | | ---------------- | --------- | ------------ | | `isDisabled` | `boolean` | 字段是否禁用 | | `isInvalid` | `boolean` | 字段是否当前无效 | | `isReadOnly` | `boolean` | 字段是否只读 | | `isRequired` | `boolean` | 字段是否必填 | | `isFocused` | `boolean` | 字段是否当前聚焦 | | `isFocusWithin` | `boolean` | 是否有子元素聚焦 | | `isFocusVisible` | `boolean` | 焦点是否可见（键盘导航） | ### ColorField.Group ColorField.Group 接受 React Aria `Group` 组件的所有属性，以及以下属性： | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------ | ----------- | --------------------------------------------------------- | | `className` | `string` | - | 与组件样式合并的 Tailwind 类 | | `fullWidth` | `boolean` | `false` | 颜色输入组是否占满容器宽度 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, GroupRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### ColorField.Input ColorField.Input 接受 React Aria `Input` 组件的所有属性，以及以下属性： | Prop | 类型 | 默认值 | 描述 | | ------------- | -------- | --- | ------------------- | | `className` | `string` | - | 与组件样式合并的 Tailwind 类 | | `placeholder` | `string` | - | 为空时显示的占位文本 | ### ColorField.Prefix ColorField.Prefix 接受标准 HTML `div` 属性： | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------- | | `className` | `string` | - | 与组件样式合并的 Tailwind 类 | | `children` | `ReactNode` | - | 前缀 slot 中显示的内容 | ### ColorField.Suffix ColorField.Suffix 接受标准 HTML `div` 属性： | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------- | | `className` | `string` | - | 与组件样式合并的 Tailwind 类 | | `children` | `ReactNode` | - | 后缀 slot 中显示的内容 | ## ColorField.Group Styling ### Customizing the component classes 基础类驱动每个实例。使用 `@layer components` 一次性覆盖。 ```css @layer components { .color-input-group { @apply inline-flex h-9 items-center overflow-hidden rounded-field border bg-field text-sm text-field-foreground shadow-field outline-none; &:hover, &[data-hovered="true"] { @apply bg-field-hover; } &[data-focus-within="true"], &:focus-within { @apply status-focused-field; } &[data-invalid="true"] { @apply status-invalid-field; } &[data-disabled="true"], &[aria-disabled="true"] { @apply status-disabled; } } .color-input-group__input { @apply flex flex-1 items-center rounded-none border-0 bg-transparent px-3 py-2 shadow-none outline-none; } .color-input-group__prefix, .color-input-group__suffix { @apply shrink-0 text-field-placeholder flex items-center; } } ``` ### ColorField.Group CSS Classes * `.color-input-group` – 根容器样式 * `.color-input-group__input` – Input 包装器样式 * `.color-input-group__prefix` – 前缀元素样式 * `.color-input-group__suffix` – 后缀元素样式 ### ColorField.Group Interactive States * **Hover**：`:hover` 或 `[data-hovered="true"]` * **Focus Within**：`[data-focus-within="true"]` 或 `:focus-within` * **Invalid**：`[data-invalid="true"]`（与 `aria-invalid` 同步） * **Disabled**：`[data-disabled="true"]` 或 `[aria-disabled="true"]` ## 相关组件 ## Related Components * **ColorSwatch**: Visual preview of a color value * **ColorSwatchPicker**: Color swatch selection from a list of colors * **ColorPicker**: Composable color picker with popover </page> <page url="/cn/docs/react/components/color-picker"> # ColorPicker 颜色选择器 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/color-picker **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(colors)/color-picker.mdx > 可组合的颜色选择器，在多个颜色组件间同步颜色值 ## 用法 ```tsx import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, ColorField, ColorSwatchPicker, } from '@heroui/react'; ``` ```tsx import {ColorArea, ColorPicker, ColorSlider, ColorSwatch, Label} from "@heroui/react"; export function Basic() { return ( <ColorPicker defaultValue="#0485F7"> <ColorPicker.Trigger> <ColorSwatch size="lg" /> <Label>选择颜色</Label> </ColorPicker.Trigger> <ColorPicker.Popover> <ColorArea aria-label="取色区域" className="max-w-full" colorSpace="hsb" xChannel="saturation" yChannel="brightness" > <ColorArea.Thumb /> </ColorArea> <ColorSlider channel="hue" className="gap-1 px-1" colorSpace="hsb"> <Label>色相</Label> <ColorSlider.Output className="text-muted" /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> </ColorPicker.Popover> </ColorPicker> ); } ``` ## 组件结构 ColorPicker 是组合多个颜色组件的可组合组件： ```tsx import { ColorPicker, ColorArea, ColorSlider, ColorSwatch, Label } from '@heroui/react'; export default () => ( <ColorPicker defaultValue="#0485F7"> <ColorPicker.Trigger> <ColorSwatch /> <Label>Pick a color</Label> </ColorPicker.Trigger> <ColorPicker.Popover> <ColorArea colorSpace="hsb" xChannel="saturation" yChannel="brightness"> <ColorArea.Thumb /> </ColorArea> <ColorSlider channel="hue" colorSpace="hsb"> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> </ColorPicker.Popover> </ColorPicker> ); ``` ## 示例 ### 受控组件 ```tsx "use client"; import { Button, ColorArea, ColorField, ColorPicker, ColorSlider, ColorSwatch, ColorSwatchPicker, Label, parseColor, } from "@heroui/react"; import {Icon} from "@iconify/react"; import {useState} from "react"; export function Controlled() { const [color, setColor] = useState(parseColor("#325578")); const colorPresets = [ "#ef4444", "#f97316", "#eab308", "#22c55e", "#06b6d4", "#3b82f6", "#8b5cf6", "#ec4899", "#f43f5e", ]; const shuffleColor = () => { const randomHue = Math.floor(Math.random() * 360); const randomSaturation = 50 + Math.floor(Math.random() * 50); // 50-100% const randomLightness = 40 + Math.floor(Math.random() * 30); // 40-70% setColor(parseColor(`hsl(${randomHue}, ${randomSaturation}%, ${randomLightness}%)`)); }; return ( <div className="flex flex-col gap-4"> <ColorPicker value={color} onChange={setColor}> <ColorPicker.Trigger> <ColorSwatch size="lg" /> <Label>选择颜色</Label> </ColorPicker.Trigger> <ColorPicker.Popover className="gap-2"> <ColorSwatchPicker className="justify-center pt-2" size="xs"> {colorPresets.map((preset) => ( <ColorSwatchPicker.Item key={preset} color={preset}> <ColorSwatchPicker.Swatch /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> <ColorArea aria-label="取色区域" className="max-w-full" colorSpace="hsb" xChannel="saturation" yChannel="brightness" > <ColorArea.Thumb /> </ColorArea> <div className="flex items-center gap-2 px-1"> <ColorSlider aria-label="色相滑块" channel="hue" className="flex-1" colorSpace="hsb"> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <Button isIconOnly aria-label="随机颜色" size="sm" variant="tertiary" onPress={shuffleColor} > <Icon className="size-4" icon="gravity-ui:shuffle" /> </Button> </div> <ColorField aria-label="颜色"> <ColorField.Group variant="secondary"> <ColorField.Prefix> <ColorSwatch size="xs" /> </ColorField.Prefix> <ColorField.Input /> </ColorField.Group> </ColorField> </ColorPicker.Popover> </ColorPicker> <p className="w-60 text-sm text-muted"> 已选：<span className="font-medium">{color.toString("hex")}</span> </p> </div> ); } ``` ### 带色板 ```tsx import { ColorArea, ColorPicker, ColorSlider, ColorSwatch, ColorSwatchPicker, Label, } from "@heroui/react"; export function WithSwatches() { const presets = [ "#ef4444", "#f97316", "#eab308", "#22c55e", "#06b6d4", "#3b82f6", "#8b5cf6", "#ec4899", "#f43f5e", ]; return ( <ColorPicker defaultValue="#F43F5E"> <ColorPicker.Trigger> <ColorSwatch size="lg" /> <Label>品牌色</Label> </ColorPicker.Trigger> <ColorPicker.Popover> <ColorArea aria-label="取色区域" className="max-w-full" colorSpace="hsb" xChannel="saturation" yChannel="brightness" > <ColorArea.Thumb /> </ColorArea> <ColorSlider aria-label="色相滑块" channel="hue" className="gap-1 px-1" colorSpace="hsb"> <Label>色相</Label> <ColorSlider.Output className="text-muted" /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <ColorSwatchPicker className="justify-center px-1" size="xs"> {presets.map((preset) => ( <ColorSwatchPicker.Item key={preset} color={preset}> <ColorSwatchPicker.Swatch /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> </ColorPicker.Popover> </ColorPicker> ); } ``` ### 带输入字段 使用 `ColorField` 允许用户编辑单个颜色通道值，配合 `Select` 切换颜色空间。 ```tsx "use client"; import type {ColorChannel, ColorSpace} from "@heroui/react"; import { ColorArea, ColorField, ColorPicker, ColorSlider, ColorSwatch, Label, ListBox, Select, } from "@heroui/react"; import {useState} from "react"; const CHANNEL_LABELS: Record<ColorChannel, string> = { alpha: "透明度", blue: "蓝", brightness: "亮度", green: "绿", hue: "色相", lightness: "明度", red: "红", saturation: "饱和度", }; export function WithFields() { const [colorSpace, setColorSpace] = useState<ColorSpace>("hsl"); const colorChannelsByColorSpace: Record<ColorSpace, ColorChannel[]> = { hsb: ["hue", "saturation", "brightness"], hsl: ["hue", "saturation", "lightness"], rgb: ["red", "green", "blue"], }; return ( <ColorPicker defaultValue="hsla(220, 90%, 50%, 0.8)"> <ColorPicker.Trigger> <ColorSwatch size="lg" /> <Label>选择颜色</Label> </ColorPicker.Trigger> <ColorPicker.Popover className="max-w-62 gap-2"> <ColorArea className="max-w-full" colorSpace="hsb" xChannel="saturation" yChannel="brightness" > <ColorArea.Thumb /> </ColorArea> <ColorSlider channel="hue" className="gap-1 px-1" colorSpace="hsb"> <Label>色相</Label> <ColorSlider.Output className="text-muted" /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <Select aria-label="色彩空间" value={colorSpace} variant="secondary" onChange={(value) => setColorSpace(value as ColorSpace)} > <Select.Trigger> <Select.Value className="uppercase" /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {Object.keys(colorChannelsByColorSpace).map((space) => ( <ListBox.Item key={space} className="uppercase" id={space} textValue={space}> {space} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> <div className="grid w-full grid-cols-3 items-center gap-2"> {colorChannelsByColorSpace[colorSpace].map((channel) => ( <ColorField key={channel} aria-label={CHANNEL_LABELS[channel]} channel={channel} colorSpace={colorSpace} > <ColorField.Group variant="secondary"> <ColorField.Input /> </ColorField.Group> </ColorField> ))} </div> </ColorPicker.Popover> </ColorPicker> ); } ``` ### 带滑块 使用多个 `ColorSlider` 组件调整颜色值的各通道。 ```tsx "use client"; import type {ColorChannel, ColorSpace} from "@heroui/react"; import {ColorPicker, ColorSlider, ColorSwatch, Label, ListBox, Select} from "@heroui/react"; import {useState} from "react"; const CHANNEL_LABELS: Record<ColorChannel, string> = { alpha: "透明度", blue: "蓝", brightness: "亮度", green: "绿", hue: "色相", lightness: "明度", red: "红", saturation: "饱和度", }; export function WithSliders() { const [colorSpace, setColorSpace] = useState<ColorSpace>("hsl"); const colorChannelsByColorSpace: Record<ColorSpace, ColorChannel[]> = { hsb: ["hue", "saturation", "brightness", "alpha"], hsl: ["hue", "saturation", "lightness", "alpha"], rgb: ["red", "green", "blue", "alpha"], }; return ( <ColorPicker defaultValue="hsl(219, 58%, 93%)"> <ColorPicker.Trigger> <ColorSwatch size="lg" /> <Label>选择颜色</Label> </ColorPicker.Trigger> <ColorPicker.Popover className="max-w-62 gap-2 px-2 py-3"> <Select aria-label="色彩空间" value={colorSpace} variant="secondary" onChange={(value) => setColorSpace(value as ColorSpace)} > <Select.Trigger> <Select.Value className="uppercase" /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {Object.keys(colorChannelsByColorSpace).map((space) => ( <ListBox.Item key={space} className="uppercase" id={space} textValue={space}> {space} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> <div className="flex flex-col gap-2"> {colorChannelsByColorSpace[colorSpace].map((channel: ColorChannel) => ( // @ts-expect-error - TypeScript can't correlate dynamic colorSpace with channel type <ColorSlider key={channel} aria-label={CHANNEL_LABELS[channel]} channel={channel} className="gap-1 px-1" colorSpace={colorSpace} > <Label>{CHANNEL_LABELS[channel]}</Label> <ColorSlider.Output className="text-muted" /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> ))} </div> </ColorPicker.Popover> </ColorPicker> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {ColorArea, ColorPicker, ColorSlider, ColorSwatch, Label} from "@heroui/react"; export function CustomStyles() { return ( <ColorPicker defaultValue="#0485F7"> <ColorPicker.Trigger className="rounded-xl bg-default-soft px-3 py-2"> <ColorSwatch size="lg" /> <Label className="font-medium text-foreground">主题色</Label> </ColorPicker.Trigger> <ColorPicker.Popover className="bg-surface"> <ColorArea aria-label="颜色区域" className="max-w-full" colorSpace="hsb" xChannel="saturation" yChannel="brightness" > <ColorArea.Thumb /> </ColorArea> <ColorSlider channel="hue" className="gap-1 px-1" colorSpace="hsb"> <Label>色相</Label> <ColorSlider.Output className="text-muted" /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> </ColorPicker.Popover> </ColorPicker> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 ColorPicker 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .color-picker { @apply inline-flex; } .color-picker__trigger { @apply inline-flex items-center gap-4 rounded-lg; } .color-picker__popover { @apply p-4 rounded-xl; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ColorPicker 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-picker.css)）： #### 基础类 \[!toc] * `.color-picker` - 基础容器 * `.color-picker__trigger` - 触发按钮 * `.color-picker__popover` - 弹出层容器 ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]` * **Disabled**：`:disabled` 或 `[data-disabled="true"]` ## API 参考 ### ColorPicker 继承自 [React Aria ColorPicker](https://react-spectrum.adobe.com/react-aria/ColorPicker.html)。 | Prop | 类型 | 默认值 | 描述 | | -------------- | ------------------------ | --- | -------------------------- | | `value` | `string \| Color` | - | 当前颜色值（受控） | | `defaultValue` | `string \| Color` | - | 默认颜色值（非受控） | | `onChange` | `(color: Color) => void` | - | 颜色变化时的回调 | | `children` | `React.ReactNode` | - | 颜色选择器内容（Trigger、Popover 等） | | `className` | `string` | - | 附加 CSS 类 | ### ColorPicker.Trigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------- | --- | ------------------ | | `children` | `React.ReactNode \| ((renderProps) => React.ReactNode)` | - | 触发器内容或 render prop | | `className` | `string` | - | 附加 CSS 类 | ### ColorPicker.Popover | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --------------- | -------- | | `placement` | `Placement` | `"bottom left"` | 弹出层位置 | | `children` | `React.ReactNode` | - | 弹出层内容 | | `className` | `string` | - | 附加 CSS 类 | ### Related Types #### Color 表示颜色值。完整 API 请参阅 [React Aria Color](https://react-spectrum.adobe.com/react-aria/ColorPicker.html#color)。 | Method | Description | | ---------------------------------- | ----------------------------------- | | `toString(format)` | 将颜色转换为指定格式的字符串（hex、rgb、hsl、hsb、css） | | `toFormat(format)` | 将颜色转换为指定格式并返回新的 Color 对象 | | `getChannelValue(channel)` | 返回指定通道的数值 | | `withChannelValue(channel, value)` | 设置通道数值并返回新的 Color | #### parseColor ```tsx import { parseColor } from 'react-aria-components'; // Parse from string const color = parseColor('#ff0000'); const hslColor = parseColor('hsl(0, 100%, 50%)'); ``` ## 相关组件 ## Related Components * **ColorArea**: 2D color picker for selecting colors from a gradient area * **ColorSlider**: Slider for adjusting individual color channel values * **ColorSwatch**: Visual preview of a color value </page> <page url="/cn/docs/react/components/color-slider"> # ColorSlider 颜色滑块 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/color-slider **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(colors)/color-slider.mdx > 颜色滑块允许用户调整颜色值的单个通道 ## 用法 ```tsx import { ColorSlider, Label } from '@heroui/react'; ``` ```tsx import {ColorSlider, Label} from "@heroui/react"; export function Basic() { return ( <ColorSlider channel="hue" className="w-full max-w-xs" defaultValue="hsl(0, 100%, 50%)"> <Label>色相</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> ); } ``` ## 组件结构 ```tsx import { ColorSlider, Label } from '@heroui/react'; export default () => ( <ColorSlider channel="hue" defaultValue="hsl(0, 100%, 50%)"> <Label>Hue</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> ) ``` ## 示例 ### 禁用 ```tsx import {ColorSlider, Label} from "@heroui/react"; export function Disabled() { return ( <ColorSlider isDisabled channel="hue" className="w-full max-w-xs" defaultValue="hsl(200, 100%, 50%)" > <Label>色相</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> ); } ``` ### 垂直方向 ```tsx import {ColorSlider} from "@heroui/react"; export function Vertical() { return ( <div className="flex h-48 gap-4"> <ColorSlider aria-label="色相" channel="hue" defaultValue="hsl(0, 100%, 50%)" orientation="vertical" > <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <ColorSlider aria-label="饱和度" channel="saturation" defaultValue="hsl(0, 100%, 50%)" orientation="vertical" > <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <ColorSlider aria-label="明度" channel="lightness" defaultValue="hsl(0, 100%, 50%)" orientation="vertical" > <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> </div> ); } ``` ### 受控组件 ```tsx "use client"; import {ColorSlider, ColorSwatch, Label} from "@heroui/react"; import {useState} from "react"; import {parseColor} from "react-aria-components"; export function Controlled() { const [color, setColor] = useState(parseColor("hsl(200, 100%, 50%)")); return ( <div className="flex w-full max-w-xs flex-col gap-4"> <ColorSlider channel="hue" value={color} onChange={setColor}> <Label>色相</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <div className="flex items-center gap-2"> <ColorSwatch color={color} size="sm" /> <p className="text-sm text-muted"> 当前颜色：<code className="font-mono">{color.toString("hsl")}</code> </p> </div> </div> ); } ``` ### HSL 通道 使用多个 ColorSlider 控制颜色值的不同通道。滑块可共享同一颜色值以构建完整颜色选择器。 ```tsx "use client"; import {ColorSlider, ColorSwatch, Label} from "@heroui/react"; import {useState} from "react"; import {parseColor} from "react-aria-components"; export function Channels() { const [color, setColor] = useState(parseColor("hsl(0, 100%, 50%)")); return ( <div className="flex w-full max-w-xs flex-col gap-4"> <ColorSlider channel="hue" value={color} onChange={setColor}> <Label>色相</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <ColorSlider channel="saturation" value={color} onChange={setColor}> <Label>饱和度</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <ColorSlider channel="lightness" value={color} onChange={setColor}> <Label>明度</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <div className="flex items-center gap-2"> <ColorSwatch color={color} size="sm" /> <p className="text-sm text-muted"> 当前颜色：<code className="font-mono">{color.toString("hsl")}</code> </p> </div> </div> ); } ``` ### 透明度通道 Alpha 通道滑块显示透明棋盘格图案，帮助可视化透明度级别。 ```tsx import {ColorSlider, Label} from "@heroui/react"; export function AlphaChannel() { return ( <ColorSlider channel="alpha" className="w-full max-w-xs" defaultValue="hsla(0, 100%, 50%, 0.5)"> <Label>透明度</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> ); } ``` ### RGB 通道 也可使用 RGB 颜色空间的红、绿、蓝通道。 ```tsx "use client"; import {ColorSlider, ColorSwatch, Label} from "@heroui/react"; import {useState} from "react"; import {parseColor} from "react-aria-components"; export function RGBChannels() { const [color, setColor] = useState(parseColor("rgb(255, 100, 50)")); return ( <div className="flex w-full max-w-xs flex-col gap-4"> <ColorSlider channel="red" value={color} onChange={setColor}> <Label>红</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <ColorSlider channel="green" value={color} onChange={setColor}> <Label>绿</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <ColorSlider channel="blue" value={color} onChange={setColor}> <Label>蓝</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> <div className="flex items-center gap-2"> <ColorSwatch color={color} size="sm" /> <p className="text-sm text-muted"> 当前颜色：<code className="font-mono">{color.toString("rgb")}</code> </p> </div> </div> ); } ``` ### 渲染函数 ```tsx "use client"; import {ColorSlider, Label} from "@heroui/react"; export function RenderFunction() { return ( <ColorSlider channel="hue" className="w-full max-w-xs" defaultValue="hsl(0, 100%, 50%)" render={(props) => <div {...props} data-custom="foo" />} > <Label>色相</Label> <ColorSlider.Output /> <ColorSlider.Track> <ColorSlider.Thumb /> </ColorSlider.Track> </ColorSlider> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {ColorSlider, Label} from "@heroui/react"; export function CustomStyles() { return ( <ColorSlider channel="hue" className="w-full max-w-sm" defaultValue="hsl(220, 70%, 50%)"> <Label className="font-medium text-foreground">色相</Label> <ColorSlider.Output className="text-muted tabular-nums" /> <ColorSlider.Track className="h-4! rounded-none! ring-1 ring-border [&::after]:rounded-r-sm! [&::before]:rounded-l-sm!"> <ColorSlider.Thumb className="size-4 rounded-sm! border-2 border-background shadow-md ring-1 ring-black/10 dark:ring-white/20" /> </ColorSlider.Track> </ColorSlider> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 ColorSlider 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .color-slider { @apply flex flex-col gap-2; } .color-slider__output { @apply text-muted text-sm; } .color-slider__track { @apply relative h-5 w-full rounded-full; } .color-slider__thumb { @apply size-4 rounded-full border-3 border-white shadow-overlay; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ColorSlider 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-slider.css)）： #### 基础类 \[!toc] * `.color-slider` - 基础滑块容器 * `.color-slider__output` - 显示当前值的输出元素 * `.color-slider__track` - 带颜色渐变的轨道元素 * `.color-slider__thumb` - 显示当前颜色的滑块元素 #### 状态类 \[!toc] * `.color-slider[data-disabled="true"]` - 禁用滑块状态 * `.color-slider[data-orientation="vertical"]` - 垂直方向 * `.color-slider__thumb[data-dragging="true"]` - 滑块正在拖拽 * `.color-slider__thumb[data-focus-visible="true"]` - 滑块键盘聚焦 * `.color-slider__thumb[data-disabled="true"]` - 禁用滑块状态 ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Hover**：滑块上的 `:hover` 或 `[data-hovered="true"]` * **Focus**：滑块上的 `:focus-visible` 或 `[data-focus-visible="true"]` * **Dragging**：滑块上的 `[data-dragging="true"]` * **Disabled**：滑块或 thumb 上的 `:disabled` 或 `[data-disabled="true"]` ## API 参考 ### ColorSlider 继承自 [React Aria ColorSlider](https://react-spectrum.adobe.com/react-aria/ColorSlider.html)。 | Prop | 类型 | 默认值 | 描述 | | -------------- | ------------------------------------------------------------------------------ | -------------- | ------------------------------------------------------------------- | | `channel` | `ColorChannel` | - | 滑块操作的颜色通道（hue、saturation、lightness、brightness、alpha、red、green、blue） | | `colorSpace` | `ColorSpace` | - | 颜色空间（hsl、hsb、rgb）。默认为值的颜色空间 | | `value` | `string \| Color` | - | 当前颜色值（受控） | | `defaultValue` | `string \| Color` | - | 默认颜色值（非受控） | | `onChange` | `(value: Color) => void` | - | 拖拽过程中值变化时的回调 | | `onChangeEnd` | `(value: Color) => void` | - | 拖拽结束时的回调 | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | 滑块方向 | | `isDisabled` | `boolean` | - | 是否禁用 | | `name` | `string` | - | 表单提交时 input 元素的名称 | | `aria-label` | `string` | - | 滑块的无障碍标签 | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode \| RenderFunction` | - | 滑块内容或 render 函数 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSliderRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### ColorSlider.Output | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------- | --- | --------------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode \| RenderFunction` | - | 输出内容或 render 函数 | ### ColorSlider.Track | Prop | 类型 | 默认值 | 描述 | | ----------- | --------------------------------- | --- | --------------- | | `className` | `string` | - | 附加 CSS 类 | | `style` | `CSSProperties \| RenderFunction` | - | 内联样式或 render 函数 | | `children` | `ReactNode \| RenderFunction` | - | 轨道内容或 render 函数 | ### ColorSlider.Thumb | Prop | 类型 | 默认值 | 描述 | | ----------- | --------------------------------- | --- | --------------- | | `className` | `string` | - | 附加 CSS 类 | | `style` | `CSSProperties \| RenderFunction` | - | 内联样式或 render 函数 | | `children` | `ReactNode \| RenderFunction` | - | 滑块内容或 render 函数 | ### Render Props 使用 render 函数时，提供以下值： | Prop | 类型 | 描述 | | ------------- | ---------------------------- | ------- | | `state` | `ColorSliderState` | 颜色滑块的状态 | | `color` | `Color` | 当前颜色值 | | `orientation` | `"horizontal" \| "vertical"` | 滑块方向 | | `isDisabled` | `boolean` | 是否禁用 | ## 无障碍 ColorSlider 组件实现 ARIA slider 模式，提供： * 完整键盘导航支持（方向键、Home、End、Page Up/Down） * 值变化的屏幕阅读器播报 * 正确的焦点管理 * 禁用状态支持 * 通过隐藏 input 元素集成 HTML 表单 * 支持 locale 感知值格式化的国际化 更多信息请参阅 [React Aria ColorSlider 文档](https://react-spectrum.adobe.com/react-aria/ColorSlider.html)。 ## 相关组件 ## Related Components * **ColorSwatch**: Visual preview of a color value * **ColorSwatchPicker**: Color swatch selection from a list of colors * **ColorPicker**: Composable color picker with popover </page> <page url="/cn/docs/react/components/color-swatch-picker"> # ColorSwatchPicker 颜色色块选择器 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/color-swatch-picker **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(colors)/color-swatch-picker.mdx > 允许用户从预置调色板中选择颜色的 swatch 列表 ## 用法 ```tsx import { ColorSwatchPicker, parseColor } from '@heroui/react'; ``` ```tsx import {ColorSwatchPicker} from "@heroui/react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; export function Basic() { return ( <ColorSwatchPicker> {colors.map((color) => ( <ColorSwatchPicker.Item key={color} color={color}> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> ); } ``` ## 组件结构 ```tsx import { ColorSwatchPicker } from '@heroui/react'; export default () => ( <ColorSwatchPicker> <ColorSwatchPicker.Item color="#F43F5E"> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> <ColorSwatchPicker.Item color="#D946EF"> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> <ColorSwatchPicker.Item color="#8B5CF6"> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> </ColorSwatchPicker> ); ``` ## 示例 ### 变体 ```tsx import {ColorSwatchPicker} from "@heroui/react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; export function Variants() { return ( <div className="flex flex-col gap-6"> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">圆形（默认）</span> <ColorSwatchPicker variant="circle"> {colors.map((color) => ( <ColorSwatchPicker.Item key={color} color={color}> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> </div> <div className="flex flex-col gap-2"> <span className="text-sm text-muted">方形</span> <ColorSwatchPicker variant="square"> {colors.map((color) => ( <ColorSwatchPicker.Item key={color} color={color}> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> </div> </div> ); } ``` ### 尺寸 ```tsx import {ColorSwatchPicker} from "@heroui/react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; const sizes = ["xs", "sm", "md", "lg", "xl"] as const; const SIZE_LABELS: Record<(typeof sizes)[number], string> = { lg: "大", md: "中", sm: "小", xl: "特大", xs: "特小", }; export function Sizes() { return ( <div className="flex flex-col gap-6"> {sizes.map((size) => ( <div key={size} className="flex items-center gap-4"> <span className="w-8 text-sm text-muted">{SIZE_LABELS[size]}</span> <ColorSwatchPicker size={size}> {colors.map((color) => ( <ColorSwatchPicker.Item key={color} color={color}> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> </div> ))} </div> ); } ``` ### 禁用 ```tsx import {ColorSwatchPicker} from "@heroui/react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; export function Disabled() { return ( <ColorSwatchPicker> {colors.map((color) => ( <ColorSwatchPicker.Item key={color} isDisabled color={color}> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> ); } ``` ### 堆叠布局 ```tsx import {ColorSwatchPicker} from "@heroui/react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; export function StackLayout() { return ( <ColorSwatchPicker layout="stack"> {colors.map((color) => ( <ColorSwatchPicker.Item key={color} color={color}> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> ); } ``` ### 默认值 ```tsx import {ColorSwatchPicker} from "@heroui/react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; export function DefaultValue() { return ( <ColorSwatchPicker defaultValue="#8B5CF6"> {colors.map((color) => ( <ColorSwatchPicker.Item key={color} color={color}> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> ); } ``` ### 受控组件 ```tsx "use client"; import {ColorSwatchPicker, parseColor} from "@heroui/react"; import {useState} from "react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; export function Controlled() { const [value, setValue] = useState(parseColor("#F43F5E")); return ( <div className="flex flex-col gap-4"> <ColorSwatchPicker value={value} onChange={setValue}> {colors.map((color) => ( <ColorSwatchPicker.Item key={color} color={color}> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> <p className="text-sm text-muted"> 已选：<span className="font-medium">{value.toString("hex")}</span> </p> </div> ); } ``` ### 自定义指示器 ```tsx import {HeartFill} from "@gravity-ui/icons"; import {ColorSwatchPicker} from "@heroui/react"; export function CustomIndicator() { const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; return ( <ColorSwatchPicker> {colors.map((color) => ( <ColorSwatchPicker.Item key={color} color={color}> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator> <HeartFill /> </ColorSwatchPicker.Indicator> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> ); } ``` ### 渲染函数 ```tsx "use client"; import {ColorSwatchPicker} from "@heroui/react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; export function RenderFunction() { return ( <ColorSwatchPicker render={(props) => <div {...props} data-custom="foo" />}> {colors.map((color) => ( <ColorSwatchPicker.Item key={color} color={color}> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {ColorSwatchPicker} from "@heroui/react"; const colors = ["#F43F5E", "#D946EF", "#8B5CF6", "#3B82F6", "#06B6D4", "#10B981", "#84CC16"]; export function CustomStyles() { return ( <ColorSwatchPicker className="rounded-2xl border border-border/80 bg-surface p-4 shadow-sm ring-1 ring-accent/5" defaultValue="#8B5CF6" variant="square" > {colors.map((color) => ( <ColorSwatchPicker.Item key={`custom-styles-${color}`} color={color}> <ColorSwatchPicker.Swatch /> <ColorSwatchPicker.Indicator /> </ColorSwatchPicker.Item> ))} </ColorSwatchPicker> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 ColorSwatchPicker 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .color-swatch-picker { @apply gap-4; } .color-swatch-picker__item { @apply shadow-md; } .color-swatch-picker__swatch { @apply border-2 border-white; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ColorSwatchPicker 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch-picker.css)）： #### 基础与结构 \[!toc] * `.color-swatch-picker` - 基础容器（flex 布局） * `.color-swatch-picker__item` - 单个 swatch 包裹层 * `.color-swatch-picker__swatch` - swatch 视觉元素 #### 尺寸类 \[!toc] * `.color-swatch-picker--xs` - 特小（16px） * `.color-swatch-picker--sm` - 小（24px） * `.color-swatch-picker--md` - 中（32px，默认） * `.color-swatch-picker--lg` - 大（36px） * `.color-swatch-picker--xl` - 特大（40px） #### 形状变体 \[!toc] * `.color-swatch-picker--circle` - 圆形（默认） * `.color-swatch-picker--square` - 圆角方形 #### 布局类 \[!toc] * `.color-swatch-picker--grid` - 横向换行网格（默认） * `.color-swatch-picker--stack` - 纵向堆叠 ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Hover**：`:hover` 或 `[data-hovered="true"]` - 缩放至 1.1（仅在未选中时） * **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]` - 焦点环 * **Selected**：`[data-selected="true"]` - 与 swatch 同色的内边框 * **Disabled**：`[data-disabled="true"]` - 降低透明度 ## API 参考 ### ColorSwatchPicker 继承自 [React Aria ColorSwatchPicker](https://react-spectrum.adobe.com/react-aria/ColorSwatchPicker.html)。 | Prop | 类型 | 默认值 | 描述 | | -------------- | ------------------------------------------------------------------------------------ | ---------- | -------------------------- | | `value` | `string \| Color` | - | 当前选中颜色（受控） | | `defaultValue` | `string \| Color` | - | 默认选中颜色（非受控） | | `onChange` | `(value: Color) => void` | - | 选中变化时的回调 | | `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | swatch 尺寸 | | `variant` | `"circle" \| "square"` | `"circle"` | swatch 形状 | | `layout` | `"grid" \| "stack"` | `"grid"` | 布局方向 | | `className` | `string` | - | 附加 CSS 类 | | `children` | `React.ReactNode` | - | ColorSwatchPicker.Item 元素 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### ColorSwatchPicker.Item | Prop | 类型 | 默认值 | 描述 | | ------------ | ---------------------------------------------------------------------------------------- | ------- | --------------------------- | | `color` | `string \| Color` | **必填** | swatch 颜色 | | `isDisabled` | `boolean` | `false` | 是否禁用该项 | | `className` | `string` | - | 附加 CSS 类 | | `children` | `React.ReactNode` | - | ColorSwatchPicker.Swatch 元素 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchPickerItemRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### ColorSwatchPicker.Swatch | Prop | 类型 | 默认值 | 描述 | | ----------- | -------- | --- | -------- | | `className` | `string` | - | 附加 CSS 类 | ### parseColor 为方便使用，从 React Aria Components 重新导出 `parseColor` 函数： ```tsx import { parseColor } from '@heroui/react'; // 解析十六进制颜色 const red = parseColor('#ff0000'); // 解析 RGB const green = parseColor('rgb(0, 255, 0)'); // 解析 HSL const blue = parseColor('hsl(240, 100%, 50%)'); ``` ## 相关组件 ## Related Components * **ColorSwatch**: Visual preview of a color value * **ColorField**: Input for entering color values with hex format * **ColorArea**: 2D color picker for selecting colors from a gradient area </page> <page url="/cn/docs/react/components/color-swatch"> # ColorSwatch 颜色色块 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/color-swatch **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(colors)/color-swatch.mdx > 颜色值的视觉预览，并提供无障碍支持 ## 用法 ```tsx import { ColorSwatch } from '@heroui/react'; ``` ```tsx import {ColorSwatch} from "@heroui/react"; export function ColorSwatchBasic() { return ( <div className="flex items-center gap-3"> <ColorSwatch aria-label="蓝色" color="#0485F7" /> <ColorSwatch aria-label="红色" color="#EF4444" /> <ColorSwatch aria-label="琥珀色" color="#F59E0B" /> <ColorSwatch aria-label="绿色" color="#10B981" /> <ColorSwatch aria-label="品红" color="#D946EF" /> </div> ); } ``` ## 示例 ### 尺寸 ```tsx import {ColorSwatch} from "@heroui/react"; export function ColorSwatchSizes() { return ( <div className="flex items-center gap-3"> <ColorSwatch color="#0485F7" size="xs" /> <ColorSwatch color="#EF4444" size="sm" /> <ColorSwatch color="#F59E0B" size="md" /> <ColorSwatch color="#10B981" size="lg" /> <ColorSwatch color="#D946EF" size="xl" /> </div> ); } ``` ### 形状 ```tsx import {ColorSwatch} from "@heroui/react"; export function ColorSwatchShapes() { return ( <div className="flex items-center gap-3"> <ColorSwatch color="#0485F7" shape="circle" /> <ColorSwatch color="#0485F7" shape="square" /> </div> ); } ``` ### 透明度 ```tsx import {ColorSwatch} from "@heroui/react"; export function ColorSwatchTransparency() { return ( <div className="flex items-center gap-3"> <ColorSwatch aria-label="100% 不透明度" color="rgba(4, 133, 247, 1)" /> <ColorSwatch aria-label="75% 不透明度" color="rgba(4, 133, 247, 0.75)" /> <ColorSwatch aria-label="50% 不透明度" color="rgba(4, 133, 247, 0.5)" /> <ColorSwatch aria-label="25% 不透明度" color="rgba(4, 133, 247, 0.25)" /> <ColorSwatch aria-label="0% 不透明度" color="rgba(4, 133, 247, 0)" /> </div> ); } ``` ### 渲染函数 可使用 `style` render prop 读取颜色值并创建自定义视觉效果。 ```tsx "use client"; import {ColorSwatch} from "@heroui/react"; export function RenderFunction() { return ( <div className="flex items-center gap-3"> <ColorSwatch aria-label="蓝色" color="#0485F7" render={(props) => <div {...props} data-custom="blue" />} /> <ColorSwatch aria-label="红色" color="#EF4444" render={(props) => <div {...props} data-custom="red" />} /> <ColorSwatch aria-label="琥珀色" color="#F59E0B" render={(props) => <div {...props} data-custom="amber" />} /> <ColorSwatch aria-label="绿色" color="#10B981" render={(props) => <div {...props} data-custom="green" />} /> <ColorSwatch aria-label="品红" color="#D946EF" render={(props) => <div {...props} data-custom="fuchsia" />} /> </div> ); } ``` ### 无障碍 使用 `colorName` 为颜色提供自定义可访问名称，并使用 `aria-label` 补充颜色用途的上下文。 ```tsx import {ColorSwatch} from "@heroui/react"; export function ColorSwatchAccessibility() { return ( <div className="flex items-center gap-3"> <ColorSwatch aria-label="主品牌色" color="#0485F7" colorName="海洋蓝" /> <ColorSwatch aria-label="错误状态色" color="#EF4444" colorName="珊瑚红" /> <ColorSwatch aria-label="警告色" color="#F59E0B" colorName="落日橙" /> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {ColorSwatch} from "@heroui/react"; export function ColorSwatchCustomStyles() { const colors = ["#0485F7", "#EF4444", "#F59E0B", "#10B981", "#D946EF"]; return ( <div className="flex flex-col gap-8"> {/* 发光效果 */} <div className="flex flex-col gap-2"> <span className="text-sm text-muted">发光效果</span> <div className="flex items-center gap-4"> {colors.map((color) => ( <ColorSwatch key={color} color={color} size="xl" style={() => ({ boxShadow: `0 0 20px 2px ${color}`, })} /> ))} </div> </div> {/* 渐变色块 */} <div className="flex flex-col gap-2"> <span className="text-sm text-muted">渐变</span> <div className="flex items-center gap-4"> {colors.map((color) => ( <ColorSwatch key={color} color={color} size="xl" style={({color: c}) => ({ background: `linear-gradient(135deg, ${c.toString("css")}, white)`, })} /> ))} </div> </div> </div> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 ColorSwatch 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .color-swatch { @apply border-2 border-white; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ColorSwatch 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/color-swatch.css)）： #### 基础类 \[!toc] * `.color-swatch` - 基础 swatch 样式，透明区域使用棋盘格背景 #### 形状类 \[!toc] * `.color-swatch--circle` - 圆形（默认） * `.color-swatch--square` - 圆角方形 #### 尺寸类 \[!toc] * `.color-swatch--xs` - 特小（16px） * `.color-swatch--sm` - 小（24px） * `.color-swatch--md` - 中（32px，默认） * `.color-swatch--lg` - 大（36px） * `.color-swatch--xl` - 特大（40px） ## API 参考 ### ColorSwatch | Prop | 类型 | 默认值 | 描述 | | ------------ | ------------------------------------------------------------------------------ | ---------- | ----------------------------- | | `color` | `string \| Color` | - | 要展示的颜色值（hex、rgb、hsl 等） | | `colorName` | `string` | - | 颜色的可访问名称（会覆盖自动生成的描述） | | `className` | `string` | - | 附加 CSS 类 | | `shape` | `"circle" \| "square"` | `"circle"` | swatch 形状 | | `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"md"` | swatch 尺寸 | | `style` | `CSSProperties \| ((renderProps) => CSSProperties)` | - | 行内样式，或带颜色访问能力的 render prop 函数 | | `aria-label` | `string` | - | swatch 的无障碍标签 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ColorSwatchRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Style Render 当把 `style` 作为函数传入时，会获得包含颜色对象在内的 render props： ```tsx <ColorSwatch color="#0485F7" style={({ color }) => ({ boxShadow: `0 4px 14px ${color.toString("css")}80`, })} /> ``` `color` 对象提供例如： * `color.toString("css")` - 返回 CSS 颜色字符串 * `color.toString("hex")` - 返回十六进制颜色字符串 * `color.getChannelValue("alpha")` - 返回 alpha 通道数值 ## 相关组件 ## Related Components * **ColorSwatchPicker**: Color swatch selection from a list of colors * **ColorField**: Input for entering color values with hex format * **ColorArea**: 2D color picker for selecting colors from a gradient area </page> <page url="/cn/docs/react/components/slider"> # Slider 滑块 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/slider **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(controls)/slider.mdx > Slider 允许用户在范围内选择一个或多个值。 ## 用法 ```tsx import { Slider } from '@heroui/react'; ``` ```tsx import {Label, Slider} from "@heroui/react"; export function Default() { return ( <Slider className="w-full max-w-xs" defaultValue={30}> <Label>音量</Label> <Slider.Output /> <Slider.Track> <Slider.Fill /> <Slider.Thumb /> </Slider.Track> </Slider> ); } ``` ## 组件结构 ```tsx import { Slider, Label } from '@heroui/react'; export default () => ( <Slider step={10}> <Label /> <Slider.Output /> <Slider.Track> <Slider.Fill /> <Slider.Steps /> <Slider.Thumb /> </Slider.Track> <Slider.Marks> <Slider.Mark value={0} /> <Slider.Mark value={50} /> <Slider.Mark value={100} /> </Slider.Marks> </Slider> ) ``` `Slider.Steps` 和 `Slider.Marks` 均为可选组件，可按需独立组合。 ## 示例 ### 步进指示点 将 `Slider.Steps` 放在 `Slider.Track` 内，即可根据 `minValue`、`maxValue` 和 `step` 在每个步进位置显示一个圆点。即使不显示圆点，`step` 也会控制数值的步进间隔。 圆点从 `minValue` 开始排列。如果 `maxValue` 不在步进位置上，则不会在该端点额外添加圆点。范围无效或所需圆点超过 1,000 个时，不渲染指示点。 ```tsx import {Label, Slider} from "@heroui/react"; export function WithSteps() { return ( <Slider className="w-full max-w-xs" defaultValue={40} step={10}> <Label>音量</Label> <Slider.Output /> <Slider.Track> <Slider.Fill /> <Slider.Steps /> <Slider.Thumb /> </Slider.Track> </Slider> ); } ``` ### 刻度标签 将 `Slider.Marks` 作为 `Slider.Track` 的同级元素紧随其后放置，并添加带有必填 `value` 的 `Slider.Mark` 子组件。每个标签根据对应数值定位，因此标签可以不等距排列，也不必与步进位置一致。 通过子内容自定义标签。未提供子内容时，标签会使用 Slider 的区域设置和 `formatOptions` 格式化数值。超出范围或数值非有限的标签不会渲染。刻度标签仅用于展示，不会改变数值或步进吸附行为。 ```tsx import {Label, Slider} from "@heroui/react"; export function WithMarks() { return ( <Slider className="w-full max-w-xs" defaultValue={40}> <Label>音量</Label> <Slider.Output /> <Slider.Track> <Slider.Fill /> <Slider.Thumb /> </Slider.Track> <Slider.Marks> <Slider.Mark value={0}>关闭</Slider.Mark> <Slider.Mark value={20}>轻声</Slider.Mark> <Slider.Mark value={60}>响亮</Slider.Mark> <Slider.Mark value={100}>最大</Slider.Mark> </Slider.Marks> </Slider> ); } ``` ### 步进指示点与刻度标签 圆点和标签可以独立组合。步进支持小数；此示例使用 `step={0.1}`，并在 `0`、`0.5` 和 `1` 处显示标签。 ```tsx import {Label, Slider} from "@heroui/react"; export function WithStepsAndMarks() { return ( <Slider className="w-full max-w-xs" defaultValue={0.4} maxValue={1} step={0.1}> <Label>音量</Label> <Slider.Output /> <Slider.Track> <Slider.Fill /> <Slider.Steps /> <Slider.Thumb /> </Slider.Track> <Slider.Marks> <Slider.Mark value={0} /> <Slider.Mark value={0.5} /> <Slider.Mark value={1} /> </Slider.Marks> </Slider> ); } ``` ### 带指示点与标签的范围滑块 单个滑块控制点下，从最小值到当前选中值之间的圆点和标签会获得 `data-filled="true"`。范围滑块中，仅第一个和最后一个控制点之间的圆点和标签会获得该属性，包含两个端点。 ```tsx "use client"; import {Label, Slider} from "@heroui/react"; export function RangeWithStepsAndMarks() { return ( <Slider className="w-full max-w-xs" defaultValue={[0.2, 0.8]} maxValue={1} step={0.1}> <Label>范围</Label> <Slider.Output /> <Slider.Track> {({state}) => ( <> <Slider.Fill /> <Slider.Steps /> {state.values.map((_, index) => ( <Slider.Thumb key={index} index={index} /> ))} </> )} </Slider.Track> <Slider.Marks> <Slider.Mark value={0} /> <Slider.Mark value={0.5} /> <Slider.Mark value={1} /> </Slider.Marks> </Slider> ); } ``` ### 垂直指示点与标签 圆点和标签会自动适配 `orientation="vertical"`。请为垂直滑块提供具有明确高度的容器。水平方向的指示点和标签也会根据区域设置适配从右到左的排列方向。 ```tsx import {Label, Slider} from "@heroui/react"; export function VerticalWithStepsAndMarks() { return ( <div className="flex h-64 items-center justify-center"> <Slider className="h-full" defaultValue={0.4} maxValue={1} orientation="vertical" step={0.1}> <Label>音量</Label> <Slider.Output /> <Slider.Track> <Slider.Fill /> <Slider.Steps /> <Slider.Thumb /> </Slider.Track> <Slider.Marks> <Slider.Mark value={0} /> <Slider.Mark value={0.5} /> <Slider.Mark value={1} /> </Slider.Marks> </Slider> </div> ); } ``` ### 禁用 ```tsx import {Label, Slider} from "@heroui/react"; export function Disabled() { return ( <Slider isDisabled className="w-full max-w-xs" defaultValue={30}> <Label>音量</Label> <Slider.Output /> <Slider.Track> <Slider.Fill /> <Slider.Thumb /> </Slider.Track> </Slider> ); } ``` ### 范围滑块结构 ```tsx import { Slider, Label } from '@heroui/react'; export default () => ( <Slider defaultValue={[25, 75]}> <Label /> <Slider.Output /> <Slider.Track> {({state}) => ( <> <Slider.Fill /> {state.values.map((_, i) => ( <Slider.Thumb key={i} index={i} /> ))} </> )} </Slider.Track> </Slider> ) ``` ### 垂直方向 ```tsx import {Label, Slider} from "@heroui/react"; export function Vertical() { return ( <div className="flex h-64 items-center justify-center"> <Slider className="h-full" defaultValue={30} orientation="vertical"> <Label>音量</Label> <Slider.Output /> <Slider.Track> <Slider.Fill /> <Slider.Thumb /> </Slider.Track> </Slider> </div> ); } ``` ### 范围选择 ```tsx "use client"; import {Label, Slider} from "@heroui/react"; export function Range() { return ( <Slider className="w-full max-w-xs" defaultValue={[100, 500]} formatOptions={{currency: "USD", style: "currency"}} maxValue={1000} minValue={0} step={50} > <Label>价格区间</Label> <Slider.Output /> <Slider.Track> {({state}) => ( <> <Slider.Fill /> {state.values.map((_, i) => ( <Slider.Thumb key={i} index={i} /> ))} </> )} </Slider.Track> </Slider> ); } ``` ### 受控数值 使用 `value` 和 `onChange` 控制数值。 ```tsx "use client"; import {Label, Slider} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [value, setValue] = useState(25); return ( <div className="flex w-full max-w-xs flex-col gap-4"> <Slider value={value} onChange={(nextValue) => { if (typeof nextValue === "number") { setValue(nextValue); } }} > <Label>音量</Label> <Slider.Output /> <Slider.Track> <Slider.Fill /> <Slider.Thumb /> </Slider.Track> </Slider> <p className="text-sm text-muted">当前数值：{value}</p> </div> ); } ``` ### 自定义数值格式 使用 `formatOptions` 格式化显示的数值。此示例将数值格式化为美元。 ```tsx import {Label, Slider} from "@heroui/react"; export function CustomValueFormatting() { return ( <Slider className="w-full max-w-xs" defaultValue={60} formatOptions={{currency: "USD", style: "currency"}} > <Label>价格</Label> <Slider.Output /> <Slider.Track> <Slider.Fill /> <Slider.Thumb /> </Slider.Track> </Slider> ); } ``` ### 自定义输出展示 自定义 `Slider.Output`，控制已选数值的展示方式。 ```tsx "use client"; import {Label, Slider} from "@heroui/react"; export function CustomOutput() { return ( <Slider className="w-full max-w-xs" defaultValue={[25, 75]}> <Label>区间</Label> <Slider.Output> {({state}) => state.values.map((_, i) => state.getThumbValueLabel(i)).join(" – ")} </Slider.Output> <Slider.Track> {({state}) => ( <> <Slider.Fill /> {state.values.map((_, i) => ( <Slider.Thumb key={i} index={i} /> ))} </> )} </Slider.Track> </Slider> ); } ``` ### 渲染函数 ```tsx "use client"; import {Label, Slider} from "@heroui/react"; export function RenderFunction() { return ( <Slider className="w-full max-w-xs" defaultValue={30} render={(props) => <div {...props} data-custom="foo" />} > <Label>音量</Label> <Slider.Output /> <Slider.Track> <Slider.Fill /> <Slider.Thumb /> </Slider.Track> </Slider> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Label, Slider} from "@heroui/react"; export function CustomStyles() { return ( <Slider className="w-full max-w-xs" defaultValue={40}> <Label className="font-medium text-foreground">亮度</Label> <Slider.Output className="text-xs text-muted tabular-nums" /> <Slider.Track className="bg-default"> <Slider.Fill className="bg-accent" /> <Slider.Thumb className="bg-accent after:bg-accent-foreground" /> </Slider.Track> </Slider> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .slider { @apply gap-2; } .slider__output { @apply text-sm text-muted; } .slider__track { @apply relative h-2 w-full rounded-full bg-surface-secondary; } .slider__fill { @apply absolute h-full rounded-full bg-accent; } .slider__thumb { @apply size-4 rounded-full bg-accent border-2 border-background; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Slider 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/slider.css)）： #### 基础类 \[!toc] * `.slider` - Slider 根容器 * `.slider__output` - 显示当前值的输出元素 * `.slider__track` - 包含填充、可选步进指示点与滑块控制点的轨道元素 * `.slider__fill` - 显示已选范围的填充元素 * `.slider__thumb` - 单个滑块控制点 * `.slider__steps` - 轨道内的装饰性步进指示点容器 * `.slider__step` - 单个步进指示点 * `.slider__marks` - 位于轨道之后的刻度标签容器 * `.slider__mark` - 根据数值定位的单个标签 #### 状态类 \[!toc] * `.slider[data-disabled="true"]` - 禁用状态 * `.slider[data-orientation="vertical"]` - 纵向方向 * `.slider__thumb[data-dragging="true"]` - 滑块正在拖动 * `.slider__thumb[data-focus-visible="true"]` - 滑块键盘聚焦 * `.slider__thumb[data-disabled="true"]` - 滑块禁用状态 * `.slider__track[data-fill-start="true"]` - 填充从起点开始 * `.slider__track[data-fill-end="true"]` - 填充在终点结束 * `.slider__step[data-filled="true"]` - 步进指示点位于已选区间内 * `.slider__mark[data-filled="true"]` - 刻度标签位于已选区间内 ### 指示点与标签的数据属性 | 属性 | 适用元素 | 描述 | | ---------------------- | --------------------- | ---------------------------------------------------------------- | | `data-slot` | 步进指示点容器、指示点、刻度标签容器、标签 | 分别为 `slider-steps`、`slider-step`、`slider-marks` 和 `slider-mark`。 | | `data-value` | 步进指示点和刻度标签 | 对应的数值。 | | `data-filled="true"` | 步进指示点和刻度标签 | 数值位于已选区间内，包含端点。 | | `data-disabled="true"` | 步进指示点容器、指示点、刻度标签容器、标签 | 继承 Slider 的禁用状态。 | | `data-orientation` | 步进指示点容器和刻度标签容器 | `horizontal` 或 `vertical`。 | | `data-direction` | 步进指示点容器和刻度标签容器 | 根据区域设置确定的 `ltr` 或 `rtl`。 | ### 交互状态 该组件同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制： * **悬停**：滑块上的 `:hover` 或 `[data-hovered="true"]` * **聚焦**：滑块上的 `:focus-visible` 或 `[data-focus-visible="true"]` * **拖动**：滑块上的 `[data-dragging="true"]` * **禁用**：Slider 或滑块上的 `:disabled` 或 `[data-disabled="true"]` ## API 参考 ### Slider | Prop | 类型 | 默认值 | 描述 | | ----------------- | ------------------------------------------------------------------------- | -------------- | ----------------------------------------- | | `value` | `number \| number[]` | - | 当前值（受控）。 | | `defaultValue` | `number \| number[]` | - | 默认值（非受控）。 | | `onChange` | `(value: number \| number[]) => void` | - | 值变化时的事件处理函数。 | | `onChangeEnd` | `(value: number \| number[]) => void` | - | 拖动结束时的事件处理函数。 | | `minValue` | `number` | `0` | Slider 的最小值。 | | `maxValue` | `number` | `100` | Slider 的最大值。 | | `step` | `number` | `1` | 数值步进间隔；使用 `Slider.Steps` 时，也决定指示点之间的数值间隔。 | | `formatOptions` | `Intl.NumberFormatOptions` | - | 数值标签的显示格式。 | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Slider 的方向。 | | `isDisabled` | `boolean` | - | Slider 是否禁用。 | | `aria-label` | `string` | - | Slider 的无障碍标签。 | | `aria-labelledby` | `string` | - | 标注 Slider 的元素 ID。 | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | Slider 内容或渲染函数。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Slider.Output | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------- | --- | --------------------- | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 输出内容或渲染函数。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderOutputRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Slider.Track | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------ | --- | --------------------- | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 轨道内容或渲染函数。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderTrackRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Slider.Fill | Prop | 类型 | 默认值 | 描述 | | ----------- | --------------- | --- | ---------- | | `className` | `string` | - | 额外的 CSS 类。 | | `style` | `CSSProperties` | - | 行内样式。 | ### Slider.Thumb | Prop | 类型 | 默认值 | 描述 | | ------------ | ------------------------------------------------------------------------------ | --- | --------------------- | | `index` | `number` | `0` | 滑块在 Slider 内的索引。 | | `isDisabled` | `boolean` | - | 该滑块是否禁用。 | | `name` | `string` | - | 输入元素名称，用于提交 HTML 表单。 | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 滑块内容或渲染函数。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SliderThumbRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Slider.Steps 在 `Slider.Track` 内根据根组件的范围和步进值渲染装饰性圆点。自动生成子元素，支持标准 DOM 属性和 ref。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------------------------------------------- | --- | --------------------- | | `className` | `string` | - | 容器的额外 CSS 类。 | | `style` | `CSSProperties` | - | 容器的行内样式。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Slider.Marks 包含 `Slider.Mark` 子组件。直接放置在 `Slider` 内，位于 `Slider.Track` 之后。支持标准 DOM 属性和 ref。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------------------------------------------- | --- | --------------------- | | `children` | `ReactNode` | - | 刻度标签。 | | `className` | `string` | - | 容器的额外 CSS 类。 | | `style` | `CSSProperties` | - | 容器的行内样式。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Slider.Mark 在 `Slider.Marks` 内根据数值定位的标签。支持标准 DOM 属性和 ref。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------------------------------------------- | ------- | --------------------------------------------- | | `value` | `number` | 必填 | 标签对应的数值；非有限值或超出范围的值不会渲染。 | | `children` | `ReactNode` | 格式化后的数值 | 自定义标签内容；未提供时使用 Slider 的区域设置和 `formatOptions`。 | | `className` | `string` | - | 额外的 CSS 类。 | | `style` | `CSSProperties` | - | 额外的行内样式；数值定位由组件自动管理。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### RenderProps 对 `Slider.Output` 或 `Slider.Track` 使用渲染函数时，会提供以下值： | Prop | 类型 | 描述 | | -------------------- | ---------------------------- | --------------- | | `state` | `SliderState` | Slider 的状态。 | | `values` | `number[]` | 按滑块索引管理的数值。 | | `getThumbValueLabel` | `(index: number) => string` | 返回指定滑块数值的字符串标签。 | | `orientation` | `"horizontal" \| "vertical"` | Slider 的方向。 | | `isDisabled` | `boolean` | Slider 是否禁用。 | ## 无障碍 Slider 组件实现 ARIA slider 模式，并提供： * 完整的键盘导航支持（方向键、Home、End、Page Up/Down） * 数值变化时的屏幕阅读器播报 * 合理的焦点管理 * 禁用状态支持 * 通过隐藏 input 元素与 HTML 表单集成 * 结合区域设置进行数值格式化的国际化支持 * 从右到左（RTL）语言支持 * 步进圆点仅用于装饰，对辅助技术隐藏，且不会增加 Tab 停靠点 * 刻度标签保留为可读文本，不会替代 Slider 的无障碍标签或数值播报 更多信息见 [React Aria Slider 文档](https://react-spectrum.adobe.com/react-aria/Slider.html)。 ## 相关组件 ## Related Components * **Label**: Accessible label for form controls * **Form**: Form validation and submission handling * **Description**: Helper text for form fields </page> <page url="/cn/docs/react/components/switch"> # Switch 开关 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/switch **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(controls)/switch.mdx > 用于布尔状态的开关组件。 ## 用法 ```tsx import { Switch, SwitchGroup, Label } from '@heroui/react'; ``` ```tsx import {Switch} from "@heroui/react"; export function Basic() { return ( <Switch> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 启用通知 </Switch.Content> </Switch> ); } ``` ## 组件结构 ```tsx import { Switch, Label, Description } from '@heroui/react'; export default () => ( <Switch> <Switch.Control> <Switch.Thumb> <Switch.Icon/> {/* 可选 */} </Switch.Thumb> </Switch.Control> <Switch.Content> <Label /> <Description /> {/* 可选 */} </Switch.Content> </Switch> ); ``` 要对多个 Switch 进行分组，请使用 `SwitchGroup` 组件： ```tsx import { Switch, SwitchGroup, Label } from '@heroui/react'; export default () => ( <SwitchGroup> <Switch> <Switch.Control> <Switch.Thumb /> </Switch.Control> <Label>Option 1</Label> </Switch> <Switch> <Switch.Control> <Switch.Thumb /> </Switch.Control> <Label>Option 2</Label> </Switch> </SwitchGroup> ); ``` ## 示例 ### 尺寸 ```tsx import {Switch} from "@heroui/react"; export function Sizes() { return ( <div className="flex gap-6"> <Switch size="sm"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 小 </Switch.Content> </Switch> <Switch size="md"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 中 </Switch.Content> </Switch> <Switch size="lg"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 大 </Switch.Content> </Switch> </div> ); } ``` ### 带图标 ```tsx "use client"; import { BellFill, BellSlash, Check, Microphone, MicrophoneSlash, Moon, Power, Sun, VolumeFill, VolumeSlashFill, } from "@gravity-ui/icons"; import {Switch} from "@heroui/react"; export function WithIcons() { const icons = { check: { off: Power, on: Check, selectedControlClass: "bg-green-500/80", }, darkMode: { off: Moon, on: Sun, selectedControlClass: "", }, microphone: { off: Microphone, on: MicrophoneSlash, selectedControlClass: "bg-red-500/80", }, notification: { off: BellSlash, on: BellFill, selectedControlClass: "bg-purple-500/80", }, volume: { off: VolumeFill, on: VolumeSlashFill, selectedControlClass: "bg-blue-500/80", }, }; return ( <div className="flex gap-3"> {Object.entries(icons).map(([key, value]) => ( <Switch key={key} defaultSelected aria-label={key} size="lg"> {({isSelected}) => ( <Switch.Content> <Switch.Control className={isSelected ? value.selectedControlClass : ""}> <Switch.Thumb> <Switch.Icon> {isSelected ? ( <value.on className="size-3 text-inherit opacity-100" /> ) : ( <value.off className="size-3 text-inherit opacity-70" /> )} </Switch.Icon> </Switch.Thumb> </Switch.Control> </Switch.Content> )} </Switch> ))} </div> ); } ``` ### 禁用 ```tsx import {Switch} from "@heroui/react"; export function Disabled() { return ( <Switch isDisabled> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 启用通知 </Switch.Content> </Switch> ); } ``` ### 无标签 ```tsx import {Switch} from "@heroui/react"; export function WithoutLabel() { return ( <Switch aria-label="启用通知"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> </Switch.Content> </Switch> ); } ``` ### 带描述 ```tsx import {Description, Switch} from "@heroui/react"; export function WithDescription() { return ( <div className="max-w-sm"> <Switch> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 公开资料 </Switch.Content> <Description>允许他人查看你的资料信息</Description> </Switch> </div> ); } ``` ### 默认选中 ```tsx import {Switch} from "@heroui/react"; export function DefaultSelected() { return ( <Switch defaultSelected> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 启用通知 </Switch.Content> </Switch> ); } ``` ### 受控组件 ```tsx "use client"; import {Switch} from "@heroui/react"; import React from "react"; export function Controlled() { const [isSelected, setIsSelected] = React.useState(false); return ( <div className="flex flex-col gap-4"> <Switch isSelected={isSelected} onChange={setIsSelected}> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 启用通知 </Switch.Content> </Switch> <p className="text-sm text-muted">开关{isSelected ? "已打开" : "已关闭"}</p> </div> ); } ``` ### 标签位置 ```tsx import {Switch} from "@heroui/react"; export function LabelPosition() { return ( <div className="flex flex-col gap-4"> <Switch> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 标签在后 </Switch.Content> </Switch> <Switch> <Switch.Content> 标签在前 <Switch.Control> <Switch.Thumb /> </Switch.Control> </Switch.Content> </Switch> </div> ); } ``` ### 分组 ```tsx import {Switch, SwitchGroup} from "@heroui/react"; export function Group() { return ( <SwitchGroup> <Switch name="notifications"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 允许通知 </Switch.Content> </Switch> <Switch name="marketing"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 营销邮件 </Switch.Content> </Switch> <Switch name="social"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 社交媒体更新 </Switch.Content> </Switch> </SwitchGroup> ); } ``` ### 横向分组 ```tsx import {Switch, SwitchGroup} from "@heroui/react"; export function GroupHorizontal() { return ( <SwitchGroup className="overflow-x-auto" orientation="horizontal"> <Switch name="notifications"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 通知 </Switch.Content> </Switch> <Switch name="marketing"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 营销 </Switch.Content> </Switch> <Switch name="social"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 社交 </Switch.Content> </Switch> </SwitchGroup> ); } ``` ### 表单集成 ```tsx "use client"; import {Button, Switch, SwitchGroup} from "@heroui/react"; import React from "react"; export function Form() { const handleSubmit = (e: React.SyntheticEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.target as HTMLFormElement); alert( `表单提交内容：\n${Array.from(formData.entries()) .map(([key, value]) => `${key}: ${value}`) .join("\n")}`, ); }; return ( <form className="flex flex-col gap-4" onSubmit={handleSubmit}> <SwitchGroup> <Switch name="notifications" value="on"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 启用通知 </Switch.Content> </Switch> <Switch defaultSelected name="newsletter" value="on"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 订阅新闻简报 </Switch.Content> </Switch> <Switch name="marketing" value="on"> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 接收营销更新 </Switch.Content> </Switch> </SwitchGroup> <Button className="mt-4" size="sm" type="submit" variant="primary"> Submit </Button> </form> ); } ``` ### 渲染属性 ```tsx "use client"; import {Switch} from "@heroui/react"; export function RenderProps() { return ( <Switch> {({isSelected}) => ( <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> {isSelected ? "已开启" : "已关闭"} </Switch.Content> )} </Switch> ); } ``` ### 渲染函数 ```tsx "use client"; import {Switch} from "@heroui/react"; export function RenderFunction() { return ( <Switch render={(props) => <div {...props} data-custom="foo" />}> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 启用通知 </Switch.Content> </Switch> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {Description, Label, Switch} from "@heroui/react"; export function CustomStyles() { return ( <Switch id="autosave"> <Switch.Content> <Switch.Control className="[--switch-control-bg-checked-hover:var(--success)] [--switch-control-bg-checked:var(--success)]"> <Switch.Thumb /> </Switch.Control> <div className="flex flex-col gap-0.5"> <Label>自动保存草稿</Label> <Description>输入时会自动保存更改。</Description> </div> </Switch.Content> </Switch> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .switch { @apply inline-flex gap-3 items-center; } .switch__control { @apply h-5 w-8 bg-gray-400 data-[selected=true]:bg-blue-500; } .switch__thumb { @apply bg-white shadow-sm; } .switch__content { @apply flex flex-col gap-1; } .switch__icon { @apply h-3 w-3 text-current; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 #### Switch 类 \[!toc] Switch 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch.css)）： * `.switch` - Switch 根容器（字段） * `.switch__content` - 包裹控件与标签文本的可点击 label * `.switch__control` - Switch 轨道 * `.switch__thumb` - 可移动的滑块 * `.switch__icon` - 滑块内可选图标 * `.switch--sm` - 小尺寸变体 * `.switch--md` - 中尺寸变体（默认） * `.switch--lg` - 大尺寸变体 #### SwitchGroup 类 \[!toc] SwitchGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/switch-group.css)）： * `.switch-group` - Switch 组容器 * `.switch-group__items` - Switch 项容器 * `.switch-group--horizontal` - 横向布局 * `.switch-group--vertical` - 纵向布局（默认） ### 交互状态 该 Switch 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制： * **已选中**：`[data-selected="true"]`（滑块位置与背景色变化） * **悬停**：`:hover` 或 `[data-hovered="true"]`（作用于 `Switch.Control` / 按钮） * **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`（在按钮上显示轨道焦点环） * **禁用**：`[data-disabled="true"]`（降低透明度，包括帮助文本） * **按压**：`:active` 或 `[data-pressed="true"]` ## API 参考 ### Switch 继承自 [React Aria SwitchField](https://react-spectrum.adobe.com/react-aria/Switch.html)。 | Prop | 类型 | 默认值 | 描述 | | -------------------- | ------------------------------------------------------------------------------ | ---------- | ---------------------- | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Switch 尺寸。 | | `isSelected` | `boolean` | `false` | Switch 是否打开。 | | `defaultSelected` | `boolean` | `false` | 默认是否打开（非受控）。 | | `isDisabled` | `boolean` | `false` | Switch 是否禁用。 | | `isInvalid` | `boolean` | `false` | Switch 是否无效。 | | `isReadOnly` | `boolean` | `false` | Switch 是否只读。 | | `isRequired` | `boolean` | `false` | Switch 是否必须打开。 | | `validate` | `(value: boolean) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 校验或 ARIA 校验。 | | `name` | `string` | - | 输入元素名称，用于提交 HTML 表单。 | | `value` | `string` | - | 输入元素值，用于提交 HTML 表单。 | | `onChange` | `(isSelected: boolean) => void` | - | Switch 值变化时的事件处理函数。 | | `onPress` | `(e: PressEvent) => void` | - | Switch 被按下时的事件处理函数。 | | `children` | `React.ReactNode \| (values: SwitchFieldRenderProps) => React.ReactNode` | - | Switch 内容或字段级渲染 prop。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SwitchFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Switch.Content 包裹控件与标签文本的可点击 `<label>`。请把 `Switch.Control` 与 `Label` 放在它内部；`Description`/`FieldError` 作为 `Switch.Content` 的兄弟节点。对于没有标签的 switch，省略 `Label` 并在 `Switch` 上传入 `aria-label`。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------- | --- | ------------------------- | | `children` | `React.ReactNode \| (values: SwitchButtonRenderProps) => React.ReactNode` | - | 按钮内容（控件 + 标签），或按钮级渲染 prop | | `className` | `string \| (values: SwitchButtonRenderProps) => string` | - | 应用到可点击 label 的类名 | ### SwitchFieldRenderProps 在根 `Switch` 上使用渲染 prop 时，提供以下字段级值： | Prop | 类型 | 描述 | | ------------ | ------------- | -------------- | | `isSelected` | `boolean` | Switch 当前是否打开。 | | `isDisabled` | `boolean` | Switch 是否禁用。 | | `isReadOnly` | `boolean` | Switch 是否只读。 | | `isInvalid` | `boolean` | Switch 是否无效。 | | `isRequired` | `boolean` | Switch 是否必填。 | | `state` | `ToggleState` | Switch 的状态。 | ### SwitchButtonRenderProps `Switch.Control` 使用按钮级渲染 prop（`isHovered`、`isPressed`、`isFocusVisible` 等）。将函数作为 `Switch.Control` 的子元素即可访问。 ### SwitchGroup | Prop | 类型 | 默认值 | 描述 | | ------------- | ---------------------------- | ------------ | -------------- | | `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | Switch 组方向。 | | `children` | `React.ReactNode` | - | 要渲染的 Switch 项。 | | `className` | `string` | - | 额外的 CSS 类。 | ## 相关组件 ## Related Components * **Label**: Accessible label for form controls * **Description**: Helper text for form fields * **Button**: Allows a user to perform an action </page> <page url="/cn/docs/react/components/badge"> # Badge 徽章 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/badge **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(data-display)/badge.mdx > 相对其他元素定位的小型指示器，常用于通知数量、状态点与标签 ## 用法 ```tsx import { Badge } from '@heroui/react'; ``` ```tsx import {Avatar, Badge} from "@heroui/react"; const GREEN_AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"; const ORANGE_AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg"; const BLUE_AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"; export function BadgeBasic() { return ( <div className="flex items-center gap-6"> <Badge.Anchor> <Avatar> <Avatar.Image alt="头像" src={GREEN_AVATAR_URL} /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Badge color="danger" size="sm"> 5 </Badge> </Badge.Anchor> <Badge.Anchor> <Avatar> <Avatar.Image alt="头像" src={ORANGE_AVATAR_URL} /> <Avatar.Fallback>AB</Avatar.Fallback> </Avatar> <Badge color="accent" size="sm"> 新 </Badge> </Badge.Anchor> <Badge.Anchor> <Avatar> <Avatar.Image alt="头像" src={BLUE_AVATAR_URL} /> <Avatar.Fallback>CD</Avatar.Fallback> </Avatar> <Badge color="success" placement="bottom-right" size="sm" /> </Badge.Anchor> </div> ); } ``` ## 组件结构 Badge 通过 `Badge.Anchor` 相对其他元素定位。纯文本子节点会自动包裹在 `<Badge.Label>` 中。 > 独立标签用法请使用 [Chip](/docs/react/components/chip) 组件。 ```tsx <Badge.Anchor> <Avatar /> <Badge color="danger">5</Badge> </Badge.Anchor> ``` ## 示例 ### 变体 ```tsx import {Avatar, Badge, Separator} from "@heroui/react"; import React from "react"; const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"; const variants = ["primary", "secondary", "soft"] as const; const VARIANT_LABELS: Record<(typeof variants)[number], string> = { primary: "主色", secondary: "次色", soft: "柔和", }; const colors = ["accent", "default", "success", "warning", "danger"] as const; export function BadgeVariants() { return ( <div className="flex flex-col gap-8"> {variants.map((variant, index) => ( <React.Fragment key={variant}> <div className="flex flex-col gap-4"> <h3 className="text-sm font-semibold text-muted">{VARIANT_LABELS[variant]}</h3> <div className="flex items-center gap-6"> {colors.map((color) => ( <Badge.Anchor key={color}> <Avatar> <Avatar.Image alt="头像" src={AVATAR_URL} /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Badge color={color} size="sm" variant={variant}> 5 </Badge> </Badge.Anchor> ))} </div> </div> {index < variants.length - 1 && <Separator />} </React.Fragment> ))} </div> ); } ``` ### 尺寸 ```tsx import {Avatar, Badge} from "@heroui/react"; const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"; export function BadgeSizes() { const sizes = ["sm", "md", "lg"] as const; return ( <div className="flex items-center gap-6"> {sizes.map((size) => ( <Badge.Anchor key={size}> <Avatar size={size}> <Avatar.Image alt="头像" src={AVATAR_URL} /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Badge color="danger" size={size}> 5 </Badge> </Badge.Anchor> ))} </div> ); } ``` ### 颜色 ```tsx import {Avatar, Badge} from "@heroui/react"; const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"; export function BadgeColors() { const colors = ["default", "accent", "success", "warning", "danger"] as const; return ( <div className="flex items-center gap-6"> {colors.map((color) => ( <Badge.Anchor key={color}> <Avatar> <Avatar.Image alt="头像" src={AVATAR_URL} /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Badge color={color} size="sm" /> </Badge.Anchor> ))} </div> ); } ``` ### 徽章位置 ```tsx import {Avatar, Badge} from "@heroui/react"; const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"; const placements = ["top-right", "top-left", "bottom-right", "bottom-left"] as const; const PLACEMENT_LABELS: Record<(typeof placements)[number], string> = { "bottom-left": "左下", "bottom-right": "右下", "top-left": "左上", "top-right": "右上", }; export function BadgePlacements() { return ( <div className="flex items-center gap-8"> {placements.map((placement) => ( <div key={placement} className="flex flex-col items-center gap-2"> <Badge.Anchor> <Avatar> <Avatar.Image alt="头像" src={AVATAR_URL} /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Badge color="accent" placement={placement} size="sm" /> </Badge.Anchor> <span className="text-xs text-muted">{PLACEMENT_LABELS[placement]}</span> </div> ))} </div> ); } ``` ### 点状徽标 空徽章作为状态指示器，适用于在线/离线或活动信号。 ```tsx import {Avatar, Badge} from "@heroui/react"; const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"; export function BadgeDot() { const colors = ["accent", "success", "warning", "danger"] as const; return ( <div className="flex items-center gap-6"> {colors.map((color) => ( <Badge.Anchor key={color}> <Avatar> <Avatar.Image alt="头像" src={AVATAR_URL} /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Badge color={color} placement="bottom-right" size="sm" /> </Badge.Anchor> ))} </div> ); } ``` ### 带内容 Badge 支持文本、数字与图标。无子节点时渲染为点状指示器。 ```tsx import {Bell} from "@gravity-ui/icons"; import {Avatar, Badge} from "@heroui/react"; const AVATAR_URL = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg"; export function BadgeWithContent() { return ( <div className="flex items-center gap-6"> <Badge.Anchor> <Avatar> <Avatar.Image alt="头像" src={AVATAR_URL} /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Badge color="danger" size="sm"> 5 </Badge> </Badge.Anchor> <Badge.Anchor> <Avatar> <Avatar.Image alt="头像" src={AVATAR_URL} /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Badge color="danger" size="sm"> 新 </Badge> </Badge.Anchor> <Badge.Anchor> <Avatar> <Avatar.Image alt="头像" src={AVATAR_URL} /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Badge color="danger" size="sm"> 99+ </Badge> </Badge.Anchor> <Badge.Anchor> <Avatar> <Avatar.Image alt="头像" src={AVATAR_URL} /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Badge color="accent" size="sm"> <Bell className="size-2.5" /> </Badge> </Badge.Anchor> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Avatar, Badge} from "@heroui/react"; export function CustomStyles() { return ( <Badge.Anchor> <Avatar> <Avatar.Image alt="凯特·威尔逊" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>KW</Avatar.Fallback> </Avatar> <Badge className="min-w-5 font-semibold tabular-nums" color="accent" size="sm" variant="soft"> 5 </Badge> </Badge.Anchor> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Badge 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .badge { @apply rounded-full text-xs; } .badge__label { @apply font-semibold; } .badge--accent { @apply shadow-sm; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Badge 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/badge.css)）： #### 基础类 \[!toc] * `.badge` - 基础徽章容器样式 * `.badge__label` - 标签文本 slot 样式 * `.badge-anchor` - 锚定元素的定位包装器 #### 颜色类 \[!toc] * `.badge--accent` - 强调色变体 * `.badge--danger` - 危险色变体 * `.badge--default` - 默认色变体 * `.badge--success` - 成功色变体 * `.badge--warning` - 警告色变体 #### 变体类 \[!toc] * `.badge--primary` - 填充背景的主变体 * `.badge--secondary` - 默认背景的次变体 * `.badge--soft` - 浅色背景的 soft 变体 #### 尺寸类 \[!toc] * `.badge--sm` - 小尺寸 * `.badge--md` - 中尺寸（默认） * `.badge--lg` - 大尺寸 #### 位置类 \[!toc] * `.badge--top-right` - 右上角（默认） * `.badge--top-left` - 左上角 * `.badge--bottom-right` - 右下角 * `.badge--bottom-left` - 左下角 #### 复合变体类 \[!toc] Badge 支持组合变体与颜色类（如 `.badge--primary.badge--accent`）。以下组合有默认样式： **Primary Variants:** * `.badge--primary.badge--accent` - 填充背景的 primary accent * `.badge--primary.badge--default` - 填充背景的 primary default * `.badge--primary.badge--success` - 填充背景的 primary success * `.badge--primary.badge--warning` - 填充背景的 primary warning * `.badge--primary.badge--danger` - 填充背景的 primary danger **Soft Variants:** * `.badge--soft.badge--accent` - 浅色背景的 soft accent * `.badge--soft.badge--default` - 浅色背景的 soft default * `.badge--soft.badge--success` - 浅色背景的 soft success * `.badge--soft.badge--warning` - 浅色背景的 soft warning * `.badge--soft.badge--danger` - 浅色背景的 soft danger ## API 参考 ### Badge | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------------------------------------------- | ------------- | ---------------------- | | `children` | `React.ReactNode` | - | 徽章内容（文本、数字或图标）。省略时渲染为点 | | `className` | `string` | - | 根元素附加 CSS 类 | | `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | 徽章颜色变体 | | `variant` | `"primary" \| "secondary" \| "soft"` | `"primary"` | 视觉样式变体 | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | 徽章尺寸 | | `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | 相对锚点的位置 | ### Badge.Anchor | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | -------------- | | `children` | `React.ReactNode` | - | 锚定元素及 Badge 本身 | | `className` | `string` | - | 锚点包装器附加 CSS 类 | ### Badge.Label | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ---------------- | | `children` | `React.ReactNode` | - | 标签文本内容 | | `className` | `string` | - | 标签 slot 附加 CSS 类 | ## 相关组件 ## Related Components * **Avatar**: Display user profile images * **Chip**: Compact elements for tags and filters </page> <page url="/cn/docs/react/components/chip"> # Chip 标签 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/chip **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(data-display)/chip.mdx > 用于显示标签、状态与分类的小型信息徽章 ## 用法 ```tsx import { Chip } from '@heroui/react'; ``` ```tsx import {Chip} from "@heroui/react"; export function ChipBasic() { return ( <div className="flex flex-wrap items-center gap-3"> <Chip>默认</Chip> <Chip color="accent">强调</Chip> <Chip color="success">成功</Chip> <Chip color="warning">警告</Chip> <Chip color="danger">危险</Chip> </div> ); } ``` ## 组件结构 > 纯文本子节点会自动包裹在 `<Chip.Label>` 中。 ```tsx <Chip> Label text </Chip> ``` ## 示例 ### 变体 ```tsx import {CircleDashed} from "@gravity-ui/icons"; import {Chip, Separator} from "@heroui/react"; import React from "react"; const sizes = ["lg", "md", "sm"] as const; const SIZE_LABELS: Record<(typeof sizes)[number], string> = { lg: "大", md: "中", sm: "小", }; const variants = ["primary", "secondary", "tertiary", "soft"] as const; const VARIANT_LABELS: Record<(typeof variants)[number], string> = { primary: "主要", secondary: "次要", soft: "柔和", tertiary: "第三", }; const colors = ["accent", "default", "success", "warning", "danger"] as const; const COLOR_LABELS: Record<(typeof colors)[number], string> = { accent: "强调", danger: "危险", default: "默认", success: "成功", warning: "警告", }; export function ChipVariants() { return ( <div className="flex flex-col gap-8 overflow-x-auto"> {sizes.map((size, index) => ( <React.Fragment key={size}> <div className="flex flex-col gap-4"> <h3 className="text-sm font-semibold text-muted">{SIZE_LABELS[size]}</h3> <div className="flex items-center gap-3"> <div className="w-24 shrink-0" /> {colors.map((color) => ( <div key={color} className="flex shrink-0 items-center justify-center" style={{width: "130px"}} > <span className="text-xs text-muted">{COLOR_LABELS[color]}</span> </div> ))} </div> <div className="flex flex-col gap-3"> {variants.map((variant) => ( <div key={variant} className="flex items-center gap-3"> <div className="w-24 shrink-0 text-sm text-muted">{VARIANT_LABELS[variant]}</div> {colors.map((color) => ( <div key={color} className="flex shrink-0 items-center justify-center" style={{width: "130px"}} > <Chip color={color} size={size} variant={variant}> <CircleDashed /> <Chip.Label>标签</Chip.Label> <CircleDashed /> </Chip> </div> ))} </div> ))} </div> </div> {index < sizes.length - 1 && <Separator />} </React.Fragment> ))} </div> ); } ``` ### 状态类型 ```tsx import {Ban, Check, CircleFill, CircleInfo, TriangleExclamation} from "@gravity-ui/icons"; import {Chip} from "@heroui/react"; export function ChipStatuses() { return ( <div className="flex flex-col gap-4"> <div className="flex flex-wrap items-center gap-3"> <Chip variant="primary"> <CircleFill width={6} /> <Chip.Label>默认</Chip.Label> </Chip> <Chip color="success" variant="primary"> <CircleFill width={6} /> <Chip.Label>活跃</Chip.Label> </Chip> <Chip color="warning" variant="primary"> <CircleFill width={6} /> <Chip.Label>待处理</Chip.Label> </Chip> <Chip color="danger" variant="primary"> <CircleFill width={6} /> <Chip.Label>未激活</Chip.Label> </Chip> </div> <div className="flex flex-wrap items-center gap-3"> <Chip> <CircleInfo width={12} /> <Chip.Label>新功能</Chip.Label> </Chip> <Chip color="success"> <Check width={12} /> <Chip.Label>可用</Chip.Label> </Chip> <Chip color="warning"> <TriangleExclamation width={12} /> <Chip.Label>测试版</Chip.Label> </Chip> <Chip color="danger"> <Ban width={12} /> <Chip.Label>已弃用</Chip.Label> </Chip> </div> </div> ); } ``` ### 带图标 ```tsx import {ChevronDown, CircleCheckFill, CircleFill, Clock, Xmark} from "@gravity-ui/icons"; import {Chip} from "@heroui/react"; export function ChipWithIcon() { return ( <div className="flex flex-wrap items-center gap-3"> <Chip> <CircleFill width={6} /> <Chip.Label>信息</Chip.Label> </Chip> <Chip color="success"> <CircleCheckFill width={12} /> <Chip.Label>已完成</Chip.Label> </Chip> <Chip color="warning"> <Clock width={12} /> <Chip.Label>待处理</Chip.Label> </Chip> <Chip color="danger"> <Xmark width={12} /> <Chip.Label>失败</Chip.Label> </Chip> <Chip color="accent"> <Chip.Label>标签</Chip.Label> <ChevronDown width={12} /> </Chip> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Chip} from "@heroui/react"; export function CustomStyles() { return ( <div className="flex flex-wrap items-center gap-2"> <Chip className="rounded-full bg-default-soft px-3 text-default-soft-foreground">草稿</Chip> <Chip className="rounded-full bg-warning-soft px-3 text-warning-soft-foreground">审核中</Chip> <Chip className="rounded-full bg-success-soft px-3 text-success-soft-foreground">已发布</Chip> </div> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Chip 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .chip { @apply rounded-full text-xs; } .chip__label { @apply font-medium; } .chip--accent { @apply border-accent/20; } .chip--accent .chip__label { @apply text-accent; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Chip 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/chip.css)）： #### 基础类 \[!toc] * `.chip` - 基础标签容器样式 * `.chip__label` - 标签文本 slot 样式 #### 颜色类 \[!toc] * `.chip--accent` - 强调色变体 * `.chip--danger` - 危险色变体 * `.chip--default` - 默认色变体 * `.chip--success` - 成功色变体 * `.chip--warning` - 警告色变体 #### 变体类 \[!toc] * `.chip--primary` - 填充背景的主变体 * `.chip--secondary` - 带边框的次变体 * `.chip--tertiary` - 透明背景的三级变体 * `.chip--soft` - 浅色背景的 soft 变体 #### 尺寸类 \[!toc] * `.chip--sm` - 小尺寸 * `.chip--md` - 中尺寸（默认） * `.chip--lg` - 大尺寸 #### 复合变体类 \[!toc] Chip 支持组合变体与颜色类（如 `.chip--secondary.chip--accent`）。以下组合有默认样式： **Primary Variants:** * `.chip--primary.chip--accent` - 填充背景的 primary accent 组合 * `.chip--primary.chip--success` - 填充背景的 primary success 组合 * `.chip--primary.chip--warning` - 填充背景的 primary warning 组合 * `.chip--primary.chip--danger` - 填充背景的 primary danger 组合 **Soft Variants:** * `.chip--accent.chip--soft` - 浅色背景的 soft accent 组合 * `.chip--success.chip--soft` - 浅色背景的 soft success 组合 * `.chip--warning.chip--soft` - 浅色背景的 soft warning 组合 * `.chip--danger.chip--soft` - 浅色背景的 soft danger 组合 **Note:** 可使用 CSS 中的 `@layer components` 指令为任意变体-颜色组合（如 `.chip--secondary.chip--accent`、`.chip--tertiary.chip--success`）应用自定义样式。 ## API 参考 ### Chip | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------- | ------------- | ----------- | | `children` | `React.ReactNode` | - | 标签内显示的内容 | | `className` | `string` | - | 根元素附加 CSS 类 | | `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | 标签颜色变体 | | `variant` | `"primary" \| "secondary" \| "tertiary" \| "soft"` | `"secondary"` | 视觉样式变体 | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | 标签尺寸 | ### Chip.Label | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ---------------- | | `children` | `React.ReactNode` | - | 标签文本内容 | | `className` | `string` | - | 标签 slot 附加 CSS 类 | ## 相关组件 ## Related Components * **Avatar**: Display user profile images * **CloseButton**: Button for dismissing overlays * **Separator**: Visual divider between content </page> <page url="/cn/docs/react/components/table"> # Table 表格 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/table **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(data-display)/table.mdx > 表格以行和列展示结构化数据，支持排序、选择、列宽调整与无限滚动。 ## 用法 ```tsx import { Table } from '@heroui/react'; ``` ```tsx import {Table} from "@heroui/react"; export function Basic() { return ( <Table> <Table.ScrollContainer> <Table.Content aria-label="团队成员" className="min-w-[600px]"> <Table.Header> <Table.Column isRowHeader>姓名</Table.Column> <Table.Column>角色</Table.Column> <Table.Column>状态</Table.Column> <Table.Column>邮箱</Table.Column> </Table.Header> <Table.Body> <Table.Row> <Table.Cell>Kate Moore</Table.Cell> <Table.Cell>首席执行官</Table.Cell> <Table.Cell>在职</Table.Cell> <Table.Cell>kate@acme.com</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>John Smith</Table.Cell> <Table.Cell>首席技术官</Table.Cell> <Table.Cell>在职</Table.Cell> <Table.Cell>john@acme.com</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>Sara Johnson</Table.Cell> <Table.Cell>首席营销官</Table.Cell> <Table.Cell>休假</Table.Cell> <Table.Cell>sara@acme.com</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>Michael Brown</Table.Cell> <Table.Cell>首席财务官</Table.Cell> <Table.Cell>在职</Table.Cell> <Table.Cell>michael@acme.com</Table.Cell> </Table.Row> </Table.Body> </Table.Content> </Table.ScrollContainer> </Table> ); } ``` ## 组件结构 ```tsx import { Table } from '@heroui/react'; export default () => ( <Table> <Table.ScrollContainer> <Table.Content aria-label="Example table"> <Table.Header> <Table.Column allowsSorting> {({ sortDirection }) => ( <Table.SortableColumnHeader sortDirection={sortDirection}> Name </Table.SortableColumnHeader> )} </Table.Column> <Table.Column>Role</Table.Column> </Table.Header> <Table.Body> <Table.Row> <Table.Cell>Kate Moore</Table.Cell> <Table.Cell>CEO</Table.Cell> </Table.Row> </Table.Body> </Table.Content> </Table.ScrollContainer> <Table.Footer>{/* Optional footer content */}</Table.Footer> </Table> ); ``` ## 示例 ### 次要变体 ```tsx import {Table} from "@heroui/react"; export function SecondaryVariant() { return ( <Table variant="secondary"> <Table.ScrollContainer> <Table.Content aria-label="团队成员" className="min-w-[600px]"> <Table.Header> <Table.Column isRowHeader>姓名</Table.Column> <Table.Column>角色</Table.Column> <Table.Column>状态</Table.Column> <Table.Column>邮箱</Table.Column> </Table.Header> <Table.Body> <Table.Row> <Table.Cell>Kate Moore</Table.Cell> <Table.Cell>首席执行官</Table.Cell> <Table.Cell>在职</Table.Cell> <Table.Cell>kate@acme.com</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>John Smith</Table.Cell> <Table.Cell>首席技术官</Table.Cell> <Table.Cell>在职</Table.Cell> <Table.Cell>john@acme.com</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>Sara Johnson</Table.Cell> <Table.Cell>首席营销官</Table.Cell> <Table.Cell>休假</Table.Cell> <Table.Cell>sara@acme.com</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>Michael Brown</Table.Cell> <Table.Cell>首席财务官</Table.Cell> <Table.Cell>在职</Table.Cell> <Table.Cell>michael@acme.com</Table.Cell> </Table.Row> </Table.Body> </Table.Content> </Table.ScrollContainer> </Table> ); } ``` ### 异步加载 使用 `Table.LoadMore` 实现无限滚动。它会渲染一个哨兵行，滚动到视口时触发 `onLoadMore`。 ```tsx "use client"; import {Chip, Spinner, Table} from "@heroui/react"; import {useCallback, useRef, useState} from "react"; interface User { id: number; name: string; role: string; status: string; email: string; } const statusColorMap: Record<string, "success" | "danger" | "warning"> = { 休假: "warning", 在职: "success", 未激活: "danger", }; const allUsers: User[] = [ {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "首席执行官", status: "在职"}, {email: "john@acme.com", id: 2, name: "John Smith", role: "首席技术官", status: "在职"}, {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "首席营销官", status: "休假"}, {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "首席财务官", status: "在职"}, { email: "emily@acme.com", id: 5, name: "Emily Davis", role: "产品经理", status: "未激活", }, {email: "davis@acme.com", id: 6, name: "Davis Wilson", role: "首席设计师", status: "在职"}, { email: "olivia@acme.com", id: 7, name: "Olivia Martinez", role: "前端工程师", status: "在职", }, { email: "james@acme.com", id: 8, name: "James Taylor", role: "后端工程师", status: "在职", }, { email: "sophia@acme.com", id: 9, name: "Sophia Anderson", role: "测试工程师", status: "休假", }, {email: "liam@acme.com", id: 10, name: "Liam Thomas", role: "DevOps 工程师", status: "在职"}, { email: "lucas@acme.com", id: 11, name: "Lucas Martinez", role: "产品经理", status: "在职", }, { email: "emma@acme.com", id: 12, name: "Emma Johnson", role: "前端工程师", status: "在职", }, {email: "noah@acme.com", id: 13, name: "Noah Davis", role: "后端工程师", status: "在职"}, {email: "ava@acme.com", id: 14, name: "Ava Wilson", role: "首席设计师", status: "在职"}, { email: "oliver@acme.com", id: 15, name: "Oliver Martinez", role: "前端工程师", status: "在职", }, { email: "isabella@acme.com", id: 16, name: "Isabella Johnson", role: "后端工程师", status: "在职", }, {email: "mia@acme.com", id: 17, name: "Mia Davis", role: "首席设计师", status: "在职"}, { email: "william@acme.com", id: 18, name: "William Wilson", role: "前端工程师", status: "在职", }, ]; const ITEMS_PER_PAGE = 6; const columns = [ {id: "name", name: "姓名"}, {id: "role", name: "角色"}, {id: "status", name: "状态"}, {id: "email", name: "邮箱"}, ]; export function AsyncLoading() { const [items, setItems] = useState<User[]>(() => allUsers.slice(0, ITEMS_PER_PAGE)); const [isLoading, setIsLoading] = useState(false); const isLoadingRef = useRef(false); const hasMore = items.length < allUsers.length; const loadMore = useCallback(() => { if (!hasMore || isLoadingRef.current) return; isLoadingRef.current = true; setIsLoading(true); setTimeout(() => { setItems((prev) => allUsers.slice(0, prev.length + ITEMS_PER_PAGE)); setIsLoading(false); requestAnimationFrame(() => { isLoadingRef.current = false; }); }, 1500); }, [hasMore]); return ( <Table> <Table.ScrollContainer className="h-[280px] overflow-y-auto"> <Table.Content aria-label="异步加载表格" className="min-w-[600px]"> <Table.Header className="sticky top-0 z-10 bg-surface-secondary"> {columns.map((col) => ( <Table.Column key={col.id} id={col.id} isRowHeader={col.id === "name"}> {col.name} </Table.Column> ))} </Table.Header> <Table.Body> <Table.Collection items={items}> {(user) => ( <Table.Row> <Table.Cell>{user.name}</Table.Cell> <Table.Cell>{user.role}</Table.Cell> <Table.Cell> <Chip color={statusColorMap[user.status]} size="sm" variant="soft"> {user.status} </Chip> </Table.Cell> <Table.Cell>{user.email}</Table.Cell> </Table.Row> )} </Table.Collection> {!!hasMore && ( <Table.LoadMore isLoading={isLoading} scrollOffset={0} onLoadMore={loadMore}> <Table.LoadMoreContent> <Spinner size="md" /> </Table.LoadMoreContent> </Table.LoadMore> )} </Table.Body> </Table.Content> </Table.ScrollContainer> </Table> ); } ``` ### 排序 在 `Table.Column` 上使用 `allowsSorting` 属性可启用列排序。在 `Table.Content` 上使用 `sortDescriptor` 与 `onSortChange` 管理排序状态。将标签包裹在 `Table.SortableColumnHeader` 中，并将列 render prop 的 `sortDirection` 转发以渲染默认升序/降序指示器。 ```tsx "use client"; import type {SortDescriptor} from "@heroui/react"; import {Table} from "@heroui/react"; import {useMemo, useState} from "react"; interface User { id: number; name: string; role: string; status: string; email: string; } const users: User[] = [ {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "首席执行官", status: "在职"}, {email: "john@acme.com", id: 2, name: "John Smith", role: "首席技术官", status: "在职"}, {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "首席营销官", status: "休假"}, {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "首席财务官", status: "在职"}, { email: "emily@acme.com", id: 5, name: "Emily Davis", role: "产品经理", status: "未激活", }, ]; export function Sorting() { const [sortDescriptor, setSortDescriptor] = useState<SortDescriptor>({ column: "name", direction: "ascending", }); const sortedUsers = useMemo(() => { return [...users].sort((a, b) => { const col = sortDescriptor.column as keyof User; const first = String(a[col]); const second = String(b[col]); let cmp = first.localeCompare(second); if (sortDescriptor.direction === "descending") { cmp *= -1; } return cmp; }); }, [sortDescriptor]); return ( <Table> <Table.ScrollContainer> <Table.Content aria-label="可排序表格" className="min-w-[600px]" sortDescriptor={sortDescriptor} onSortChange={setSortDescriptor} > <Table.Header> <Table.Column allowsSorting isRowHeader id="name"> {({sortDirection}) => ( <Table.SortableColumnHeader sortDirection={sortDirection}> 姓名 </Table.SortableColumnHeader> )} </Table.Column> <Table.Column allowsSorting id="role"> {({sortDirection}) => ( <Table.SortableColumnHeader sortDirection={sortDirection}> 角色 </Table.SortableColumnHeader> )} </Table.Column> <Table.Column allowsSorting id="status"> {({sortDirection}) => ( <Table.SortableColumnHeader sortDirection={sortDirection}> 状态 </Table.SortableColumnHeader> )} </Table.Column> <Table.Column allowsSorting id="email"> {({sortDirection}) => ( <Table.SortableColumnHeader sortDirection={sortDirection}> 邮箱 </Table.SortableColumnHeader> )} </Table.Column> </Table.Header> <Table.Body> {sortedUsers.map((user) => ( <Table.Row key={user.id} id={user.id}> <Table.Cell>{user.name}</Table.Cell> <Table.Cell>{user.role}</Table.Cell> <Table.Cell>{user.status}</Table.Cell> <Table.Cell>{user.email}</Table.Cell> </Table.Row> ))} </Table.Body> </Table.Content> </Table.ScrollContainer> </Table> ); } ``` ### 选择 在 `Table.Content` 上使用 `selectionMode` 启用行选择。使用 `slot="selection"` 的 `Checkbox` 实现全选与逐行勾选。 ```tsx "use client"; import type {Selection} from "@heroui/react"; import {Checkbox, Table} from "@heroui/react"; import {useState} from "react"; const users = [ {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "首席执行官", status: "在职"}, {email: "john@acme.com", id: 2, name: "John Smith", role: "首席技术官", status: "在职"}, {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "首席营销官", status: "休假"}, {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "首席财务官", status: "在职"}, ]; export function SelectionDemo() { const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set()); return ( <div className="flex flex-col gap-3"> <Table> <Table.ScrollContainer> <Table.Content aria-label="带选择的表格" className="min-w-[600px]" selectedKeys={selectedKeys} selectionMode="multiple" onSelectionChange={setSelectedKeys} > <Table.Header> <Table.Column className="pe-0"> <Checkbox aria-label="全选" slot="selection"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> </Checkbox.Content> </Checkbox> </Table.Column> <Table.Column isRowHeader>姓名</Table.Column> <Table.Column>角色</Table.Column> <Table.Column>状态</Table.Column> <Table.Column>邮箱</Table.Column> </Table.Header> <Table.Body> {users.map((user) => ( <Table.Row key={user.id} id={user.id}> <Table.Cell className="pe-0"> <Checkbox aria-label={`选择 ${user.name}`} slot="selection" variant="secondary"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> </Checkbox.Content> </Checkbox> </Table.Cell> <Table.Cell>{user.name}</Table.Cell> <Table.Cell>{user.role}</Table.Cell> <Table.Cell>{user.status}</Table.Cell> <Table.Cell>{user.email}</Table.Cell> </Table.Row> ))} </Table.Body> </Table.Content> </Table.ScrollContainer> </Table> <p className="text-sm text-muted"> 已选：{" "} <span className="font-medium"> {selectedKeys === "all" ? "全部" : selectedKeys.size > 0 ? Array.from(selectedKeys).join(", ") : "无"} </span> </p> </div> ); } ``` ### 可展开行 行可嵌套以展示层级数据。使用 `treeColumn` 指定列，并在该列单元格中渲染 `slot="chevron"` 的 `Button`，供用户展开/收起行。使用 `expandedKeys` 控制哪些行处于展开状态。 ```tsx "use client"; import type {Selection} from "@heroui/react"; import {Button, Table, cn} from "@heroui/react"; import {Icon} from "@iconify/react"; import {useState} from "react"; export function ExpandableRows() { type Row = { children: Row[]; date: string; id: string; title: string; type: string; }; const data: Row[] = [ { children: [ { children: [ {children: [], date: "7/10/2025", id: "3", title: "周报", type: "文件"}, {children: [], date: "8/20/2025", id: "4", title: "预算", type: "文件"}, ], date: "8/2/2025", id: "2", title: "项目", type: "文件夹", }, ], date: "10/20/2025", id: "1", title: "文档", type: "文件夹", }, { children: [ {children: [], date: "1/23/2026", id: "6", title: "图片 1", type: "文件"}, {children: [], date: "2/3/2026", id: "7", title: "图片 2", type: "文件"}, ], date: "2/3/2026", id: "5", title: "照片", type: "文件夹", }, ]; const [expandedKeys, setExpandedKeys] = useState<Selection>(() => new Set(["1"])); const renderExpandableRow = (item: Row) => { return ( <Table.Row id={item.id} textValue={item.title}> <Table.Cell textValue={item.title}> {({hasChildItems, isDisabled, isExpanded, isTreeColumn}) => ( <span className="flex items-center gap-1"> {hasChildItems && isTreeColumn ? ( <Button isIconOnly aria-label="切换行" isDisabled={isDisabled} size="sm" slot="chevron" variant="ghost" > <Icon aria-hidden icon="gravity-ui:chevron-right" className={cn( "size-4 text-muted transition-transform duration-150", isExpanded ? "rotate-90" : "rtl:rotate-180", )} /> </Button> ) : null} <span>{item.title}</span> </span> )} </Table.Cell> <Table.Cell>{item.type}</Table.Cell> <Table.Cell>{item.date}</Table.Cell> <Table.Collection items={item.children}>{renderExpandableRow}</Table.Collection> </Table.Row> ); }; return ( <Table> <Table.ScrollContainer> <Table.Content aria-label="文件" className="min-w-[520px]" expandedKeys={expandedKeys} treeColumn="name" onExpandedChange={setExpandedKeys} > <Table.Header> <Table.Column isRowHeader id="name"> 姓名 </Table.Column> <Table.Column id="type">类型</Table.Column> <Table.Column id="date">修改日期</Table.Column> </Table.Header> <Table.Body items={data}>{renderExpandableRow}</Table.Body> </Table.Content> </Table.ScrollContainer> </Table> ); } ``` ### 分页 使用 `Table.Footer` 在表格下方添加分页组件。 ```tsx "use client"; import {Pagination, Table} from "@heroui/react"; import {useMemo, useState} from "react"; const columns = [ {id: "name", name: "姓名"}, {id: "role", name: "角色"}, {id: "status", name: "状态"}, {id: "email", name: "邮箱"}, ]; const users = [ {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "首席执行官", status: "在职"}, {email: "john@acme.com", id: 2, name: "John Smith", role: "首席技术官", status: "在职"}, {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "首席营销官", status: "休假"}, {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "首席财务官", status: "在职"}, { email: "emily@acme.com", id: 5, name: "Emily Davis", role: "产品经理", status: "未激活", }, {email: "davis@acme.com", id: 6, name: "Davis Wilson", role: "首席设计师", status: "在职"}, { email: "olivia@acme.com", id: 7, name: "Olivia Martinez", role: "前端工程师", status: "在职", }, { email: "james@acme.com", id: 8, name: "James Taylor", role: "后端工程师", status: "在职", }, ]; const ROWS_PER_PAGE = 4; export function PaginationDemo() { const [page, setPage] = useState(1); const totalPages = Math.ceil(users.length / ROWS_PER_PAGE); const pages = Array.from({length: totalPages}, (_, i) => i + 1); const paginatedItems = useMemo(() => { const start = (page - 1) * ROWS_PER_PAGE; return users.slice(start, start + ROWS_PER_PAGE); }, [page]); const start = (page - 1) * ROWS_PER_PAGE + 1; const end = Math.min(page * ROWS_PER_PAGE, users.length); return ( <Table> <Table.ScrollContainer> <Table.Content aria-label="带分页的表格" className="min-w-[600px]"> <Table.Header columns={columns}> {(column) => ( <Table.Column isRowHeader={column.id === "name"}>{column.name}</Table.Column> )} </Table.Header> <Table.Body items={paginatedItems}> {(user) => ( <Table.Row> <Table.Collection items={columns}> {(column) => <Table.Cell>{user[column.id as keyof typeof user]}</Table.Cell>} </Table.Collection> </Table.Row> )} </Table.Body> </Table.Content> </Table.ScrollContainer> <Table.Footer> <Pagination size="sm"> <Pagination.Summary> {start}–{end} / 共 {users.length} 条 </Pagination.Summary> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => Math.max(1, p - 1))} > <Pagination.PreviousIcon /> 上一页 </Pagination.Previous> </Pagination.Item> {pages.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) => Math.min(totalPages, p + 1))} > 下一页 <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> </Table.Footer> </Table> ); } ``` ### 列宽调整 将表格包裹在 `Table.ResizableContainer` 中，并在每个可调整宽度的列内添加 `Table.ColumnResizer`。 ```tsx import {Chip, Table} from "@heroui/react"; export function ColumnResizing() { return ( <Table> <Table.ResizableContainer> <Table.Content aria-label="可调整列宽的表格" className="min-w-[700px]"> <Table.Header> <Table.Column isRowHeader defaultWidth="1fr" id="name" minWidth={160}> 姓名 <Table.ColumnResizer /> </Table.Column> <Table.Column defaultWidth="1fr" id="role" minWidth={220}> 角色 <Table.ColumnResizer /> </Table.Column> <Table.Column defaultWidth="1fr" id="status" minWidth={100}> 状态 <Table.ColumnResizer /> </Table.Column> <Table.Column defaultWidth="1fr" id="email" minWidth={200}> 邮箱 </Table.Column> </Table.Header> <Table.Body> <Table.Row> <Table.Cell>Kate Moore</Table.Cell> <Table.Cell>首席执行官</Table.Cell> <Table.Cell> <Chip color="success" size="sm" variant="soft"> Active </Chip> </Table.Cell> <Table.Cell>kate@acme.com</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>John Smith</Table.Cell> <Table.Cell>首席技术官</Table.Cell> <Table.Cell> <Chip color="success" size="sm" variant="soft"> Active </Chip> </Table.Cell> <Table.Cell>john@acme.com</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>Sara Johnson</Table.Cell> <Table.Cell>首席营销官</Table.Cell> <Table.Cell> <Chip color="warning" size="sm" variant="soft"> On Leave </Chip> </Table.Cell> <Table.Cell>sara@acme.com</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>Michael Brown</Table.Cell> <Table.Cell>首席财务官</Table.Cell> <Table.Cell> <Chip color="success" size="sm" variant="soft"> Active </Chip> </Table.Cell> <Table.Cell>michael@acme.com</Table.Cell> </Table.Row> <Table.Row> <Table.Cell>Emily Davis</Table.Cell> <Table.Cell>产品经理</Table.Cell> <Table.Cell> <Chip color="danger" size="sm" variant="soft"> Inactive </Chip> </Table.Cell> <Table.Cell>emily@acme.com</Table.Cell> </Table.Row> </Table.Body> </Table.Content> </Table.ResizableContainer> </Table> ); } ``` ### 空状态 在 `Table.Body` 上使用 `renderEmptyState`，在表格无数据时展示自定义消息。 ```tsx "use client"; import {EmptyState, Table} from "@heroui/react"; import {Icon} from "@iconify/react"; export function EmptyStateDemo() { return ( <Table className="min-h-[200px]"> <Table.ScrollContainer> <Table.Content aria-label="空表格" className="h-full min-w-[600px]"> <Table.Header> <Table.Column isRowHeader>姓名</Table.Column> <Table.Column>角色</Table.Column> <Table.Column>状态</Table.Column> <Table.Column>邮箱</Table.Column> </Table.Header> <Table.Body renderEmptyState={() => ( <EmptyState className="flex h-full w-full flex-col items-center justify-center gap-4 text-center"> <Icon className="size-6 text-muted" icon="gravity-ui:tray" /> <span className="text-sm text-muted">未找到结果</span> </EmptyState> )} > {[]} </Table.Body> </Table.Content> </Table.ScrollContainer> </Table> ); } ``` ### 虚拟滚动 Table 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见行，从而高效展示大数据集。 ```tsx "use client"; import {Table, TableLayout, Virtualizer} from "@heroui/react"; interface User { id: number; name: string; role: string; email: string; } export function Virtualization() { const roles = [ "软件工程师", "高级工程师", "资深工程师", "产品经理", "设计师", "数据分析师", "测试工程师", "DevOps 工程师", "营销经理", "销售代表", ]; const firstNames = [ "Emma", "Liam", "Olivia", "Noah", "Ava", "James", "Sophia", "Oliver", "Isabella", "Lucas", "Mia", "Ethan", "Charlotte", "Mason", "Amelia", "Logan", "Harper", "Alexander", "Ella", "Benjamin", ]; const lastNames = [ "Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller", "Davis", "Rodriguez", "Martinez", "Anderson", "Taylor", "Thomas", "Jackson", "White", "Harris", "Clark", "Lewis", "Robinson", "Walker", ]; function generateUsers(count: number): User[] { const users: User[] = []; for (let i = 0; i < count; i++) { const firstName = firstNames[i % firstNames.length]; const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length]; const name = `${firstName} ${lastName}`; users.push({ email: `${firstName?.toLowerCase()}.${lastName?.toLowerCase()}@acme.com`, id: i + 1, name, role: roles[i % roles.length] || "", }); } return users; } const virtualizedUsers = generateUsers(1000); return ( <Virtualizer layout={TableLayout} layoutOptions={{ headingHeight: 42, rowHeight: 42, }} > <Table> <Table.ScrollContainer> <Table.Content aria-label="1000 行虚拟化表格" className="h-[300px] min-w-[700px] overflow-auto" > <Table.Header className="h-full w-full"> <Table.Column isRowHeader id="name" minWidth={160}> 姓名 </Table.Column> <Table.Column id="role" minWidth={220}> 角色 </Table.Column> <Table.Column id="email" minWidth={240}> 邮箱 </Table.Column> </Table.Header> <Table.Body items={virtualizedUsers}> {(user) => ( <Table.Row> <Table.Cell>{user.name}</Table.Cell> <Table.Cell>{user.role}</Table.Cell> <Table.Cell>{user.email}</Table.Cell> </Table.Row> )} </Table.Body> </Table.Content> </Table.ScrollContainer> </Table> </Virtualizer> ); } ``` ### TanStack Table HeroUI 的 Table 作为无头表格库之上的渲染层。 本示例使用 [TanStack Table](https://tanstack.com/table) 处理列定义、排序与分页，而 HeroUI 负责样式与无障碍。 ```tsx "use client"; import type {SortDescriptor} from "@heroui/react"; import type {SortingState} from "@tanstack/react-table"; import {Chip, Pagination, Table} from "@heroui/react"; import { createColumnHelper, createPaginatedRowModel, createSortedRowModel, flexRender, rowPaginationFeature, rowSortingFeature, sortFn_alphanumeric, tableFeatures, useTable, } from "@tanstack/react-table"; import {useMemo, useState} from "react"; // --- Data ----------------------------------------------------------------- interface User { id: number; name: string; role: string; status: "在职" | "未激活" | "休假"; email: string; } const statusColorMap: Record<string, "success" | "danger" | "warning"> = { 休假: "warning", 在职: "success", 未激活: "danger", }; const users: User[] = [ {email: "kate@acme.com", id: 1, name: "Kate Moore", role: "首席执行官", status: "在职"}, {email: "john@acme.com", id: 2, name: "John Smith", role: "首席技术官", status: "在职"}, {email: "sara@acme.com", id: 3, name: "Sara Johnson", role: "首席营销官", status: "休假"}, {email: "michael@acme.com", id: 4, name: "Michael Brown", role: "首席财务官", status: "在职"}, { email: "emily@acme.com", id: 5, name: "Emily Davis", role: "产品经理", status: "未激活", }, {email: "davis@acme.com", id: 6, name: "Davis Wilson", role: "首席设计师", status: "在职"}, { email: "olivia@acme.com", id: 7, name: "Olivia Martinez", role: "前端工程师", status: "在职", }, { email: "james@acme.com", id: 8, name: "James Taylor", role: "后端工程师", status: "在职", }, ]; // --- TanStack Features & Column Definitions ------------------------------- const features = tableFeatures({ paginatedRowModel: createPaginatedRowModel(), rowPaginationFeature, rowSortingFeature, sortFns: { alphanumeric: sortFn_alphanumeric, }, sortedRowModel: createSortedRowModel(), }); const columnHelper = createColumnHelper<typeof features, User>(); const columns = columnHelper.columns([ columnHelper.accessor("name", {header: "姓名"}), columnHelper.accessor("role", {header: "角色"}), columnHelper.accessor("status", { cell: (info) => ( <Chip color={statusColorMap[info.getValue()]} size="sm" variant="soft"> {info.getValue()} </Chip> ), header: "状态", }), columnHelper.accessor("email", {header: "邮箱"}), ]); // --- Sorting Bridge ------------------------------------------------------- // Convert TanStack SortingState → React Aria SortDescriptor function toSortDescriptor(sorting: SortingState): SortDescriptor | undefined { const first = sorting[0]; if (!first) return undefined; return { column: first.id, direction: first.desc ? "descending" : "ascending", }; } // Convert React Aria SortDescriptor → TanStack SortingState function toSortingState(descriptor: SortDescriptor): SortingState { return [{desc: descriptor.direction === "descending", id: descriptor.column as string}]; } // --- Component ------------------------------------------------------------ const PAGE_SIZE = 4; export function TanstackTable() { const [sorting, setSorting] = useState<SortingState>([]); const table = useTable({ columns, data: users, features, initialState: {pagination: {pageIndex: 0, pageSize: PAGE_SIZE}}, onSortingChange: setSorting, state: {sorting}, }); const sortDescriptor = useMemo(() => toSortDescriptor(sorting), [sorting]); const {pageIndex} = table.state.pagination; const pageCount = table.getPageCount(); const pages = Array.from({length: pageCount}, (_, i) => i + 1); const start = pageIndex * PAGE_SIZE + 1; const end = Math.min((pageIndex + 1) * PAGE_SIZE, users.length); return ( <Table> <Table.ScrollContainer> <Table.Content aria-label="TanStack 表格示例" className="min-w-[600px]" sortDescriptor={sortDescriptor} onSortChange={(d) => setSorting(toSortingState(d))} > <Table.Header> {table.getHeaderGroups()[0]?.headers.map((header) => ( <Table.Column key={header.id} allowsSorting={header.column.getCanSort()} id={header.id} isRowHeader={header.id === "name"} > {({sortDirection}) => ( <Table.SortableColumnHeader sortDirection={sortDirection}> {flexRender(header.column.columnDef.header, header.getContext())} </Table.SortableColumnHeader> )} </Table.Column> ))} </Table.Header> <Table.Body> {table.getRowModel().rows.map((row) => ( <Table.Row key={row.id} id={row.id}> {row.getAllCells().map((cell) => ( <Table.Cell key={cell.id}> {flexRender(cell.column.columnDef.cell, cell.getContext())} </Table.Cell> ))} </Table.Row> ))} </Table.Body> </Table.Content> </Table.ScrollContainer> <Table.Footer> <Pagination size="sm"> <Pagination.Summary> {start}–{end} / 共 {users.length} 条 </Pagination.Summary> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={!table.getCanPreviousPage()} onPress={() => table.previousPage()} > <Pagination.PreviousIcon /> 上一页 </Pagination.Previous> </Pagination.Item> {pages.map((p) => ( <Pagination.Item key={p}> <Pagination.Link isActive={p === pageIndex + 1} onPress={() => table.setPageIndex(p - 1)} > {p} </Pagination.Link> </Pagination.Item> ))} <Pagination.Item> <Pagination.Next isDisabled={!table.getCanNextPage()} onPress={() => table.nextPage()} > 下一页 <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> </Table.Footer> </Table> ); } ``` ### 自定义单元格 ```tsx "use client"; import type {Selection, SortDescriptor} from "@heroui/react"; import {Avatar, Button, Checkbox, Chip, Table} from "@heroui/react"; import {Icon} from "@iconify/react"; import {useMemo, useState} from "react"; interface User { id: number; name: string; image_url: string; role: string; status: "在职" | "未激活" | "休假"; email: string; } const statusColorMap: Record<string, "success" | "danger" | "warning"> = { 休假: "warning", 在职: "success", 未激活: "danger", }; const users: User[] = [ { email: "kate@acme.com", id: 4586932, image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", name: "Kate Moore", role: "首席执行官", status: "在职", }, { email: "john@acme.com", id: 5273849, image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", name: "John Smith", role: "首席技术官", status: "在职", }, { email: "sara@acme.com", id: 7492836, image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", name: "Sara Johnson", role: "首席营销官", status: "休假", }, { email: "michael@acme.com", id: 8293746, image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", name: "Michael Brown", role: "首席财务官", status: "在职", }, { email: "emily@acme.com", id: 1234567, image_url: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", name: "Emily Davis", role: "产品经理", status: "未激活", }, ]; export function CustomCells() { const [selectedKeys, setSelectedKeys] = useState<Selection>(new Set()); const [sortDescriptor, setSortDescriptor] = useState<SortDescriptor>({ column: "name", direction: "ascending", }); const sortedUsers = useMemo(() => { return [...users].sort((a, b) => { const col = sortDescriptor.column as keyof User; const first = String(a[col]); const second = String(b[col]); let cmp = first.localeCompare(second); if (sortDescriptor.direction === "descending") { cmp *= -1; } return cmp; }); }, [sortDescriptor]); return ( <Table> <Table.ScrollContainer> <Table.Content aria-label="自定义单元格表格" className="min-w-[800px]" selectedKeys={selectedKeys} selectionMode="multiple" sortDescriptor={sortDescriptor} onSelectionChange={setSelectedKeys} onSortChange={setSortDescriptor} > <Table.Header> <Table.Column className="pe-0"> <Checkbox aria-label="全选" slot="selection"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> </Checkbox.Content> </Checkbox> </Table.Column> <Table.Column allowsSorting isRowHeader className="after:hidden" id="id"> {({sortDirection}) => ( <Table.SortableColumnHeader sortDirection={sortDirection}> 员工 ID </Table.SortableColumnHeader> )} </Table.Column> <Table.Column allowsSorting id="name"> {({sortDirection}) => ( <Table.SortableColumnHeader sortDirection={sortDirection}> 成员 </Table.SortableColumnHeader> )} </Table.Column> <Table.Column allowsSorting id="role"> {({sortDirection}) => ( <Table.SortableColumnHeader sortDirection={sortDirection}> 角色 </Table.SortableColumnHeader> )} </Table.Column> <Table.Column allowsSorting id="status"> {({sortDirection}) => ( <Table.SortableColumnHeader sortDirection={sortDirection}> 状态 </Table.SortableColumnHeader> )} </Table.Column> <Table.Column className="text-end">操作</Table.Column> </Table.Header> <Table.Body> {sortedUsers.map((user) => ( <Table.Row key={user.id} id={user.id}> <Table.Cell className="pe-0"> <Checkbox aria-label={`选择 ${user.name}`} slot="selection" variant="secondary"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> </Checkbox.Content> </Checkbox> </Table.Cell> <Table.Cell className="font-medium"> <div className="flex items-center gap-2"> #{user.id.toString()}{" "} <Button isIconOnly aria-label={`复制 ID #${user.id}`} size="sm" variant="ghost"> <Icon className="size-4 text-muted" icon="gravity-ui:copy" /> </Button> </div> </Table.Cell> <Table.Cell> <div className="flex items-center gap-3"> <Avatar size="sm"> <Avatar.Image src={user.image_url} /> <Avatar.Fallback> {user.name .split(" ") .map((n) => n[0]) .join("")} </Avatar.Fallback> </Avatar> <div className="flex flex-col"> <span className="text-xs">{user.name}</span> <span className="text-xs text-muted">{user.email}</span> </div> </div> </Table.Cell> <Table.Cell className="min-w-52">{user.role}</Table.Cell> <Table.Cell className="min-w-25"> <Chip color={statusColorMap[user.status]} size="sm" variant="soft"> {user.status} </Chip> </Table.Cell> <Table.Cell> <div className="flex items-center gap-1"> <Button isIconOnly aria-label={`查看 ${user.name}`} size="sm" variant="tertiary" > <Icon className="size-4" icon="gravity-ui:eye" /> </Button> <Button isIconOnly aria-label={`编辑 ${user.name}`} size="sm" variant="tertiary" > <Icon className="size-4" icon="gravity-ui:pencil" /> </Button> <Button isIconOnly aria-label={`删除 ${user.name}`} size="sm" variant="danger-soft" > <Icon className="size-4" icon="gravity-ui:trash-bin" /> </Button> </div> </Table.Cell> </Table.Row> ))} </Table.Body> </Table.Content> </Table.ScrollContainer> </Table> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Table} from "@heroui/react"; const headerCell = "text-xs font-semibold uppercase tracking-wide text-muted"; const rowClass = "border-t border-border/60 transition-colors hover:bg-default even:bg-surface-secondary"; export function CustomStyles() { return ( <Table className="w-full max-w-2xl overflow-hidden rounded-xl border border-border/80 shadow-sm"> <Table.ScrollContainer> <Table.Content aria-label="团队成员" className="min-w-[600px]"> <Table.Header className="bg-surface-secondary"> <Table.Column isRowHeader className={headerCell}> 姓名 </Table.Column> <Table.Column className={headerCell}>角色</Table.Column> <Table.Column className={headerCell}>状态</Table.Column> </Table.Header> <Table.Body> <Table.Row className={rowClass}> <Table.Cell className="font-medium text-foreground">Kate Moore</Table.Cell> <Table.Cell>CEO</Table.Cell> <Table.Cell>在职</Table.Cell> </Table.Row> <Table.Row className={rowClass}> <Table.Cell className="font-medium text-foreground">John Smith</Table.Cell> <Table.Cell>CTO</Table.Cell> <Table.Cell>在职</Table.Cell> </Table.Row> <Table.Row className={rowClass}> <Table.Cell className="font-medium text-foreground">Sara Johnson</Table.Cell> <Table.Cell>CMO</Table.Cell> <Table.Cell>休假中</Table.Cell> </Table.Row> </Table.Body> </Table.Content> </Table.ScrollContainer> </Table> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .table-root { @apply relative grid w-full overflow-clip; } .table__header { @apply bg-gray-100; } .table__column { @apply px-4 py-2.5 text-left text-xs font-medium text-gray-600; } .table__row { @apply bg-white border-b border-gray-200; } .table__cell { @apply px-4 py-3 text-sm; } .table__footer { @apply flex items-center px-4 py-2.5; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Table 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/table.css)）： #### 基础类 \[!toc] * `.table-root` - 根容器（命名为 `table-root` 而非 `table`，因为 `table` 是 Tailwind CSS 内置的 `display: table` 工具类） * `.table__scroll-container` - 横向滚动包裹层与自定义滚动条 * `.table__content` - `<table>` 元素 * `.table__header` - 表头行（`<thead>`） * `.table__column` - 列表头单元格（`<th>`） * `.table__body` - 表体（`<tbody>`） * `.table__row` - 行（`<tr>`） * `.table__cell` - 数据单元格（`<td>`） * `.table__footer` - 表底容器（位于 table 外部） #### 进阶类 \[!toc] * `.table__column-resizer` - 列宽拖拽手柄 * `.table__resizable-container` - 启用列宽调整的包裹层 * `.table__load-more` - 无限滚动的哨兵行 * `.table__load-more-content` - 加载指示器的样式容器 * `.table__sortable-column-header` - 可排序列标签与指示器的包裹层 * `.table__sortable-column-indicator` - 排序方向 chevron（通过 `[data-direction="descending"]` 翻转） #### 变体类 \[!toc] * `.table-root--primary` - 灰色背景容器与卡片式表体（默认） * `.table-root--secondary` - 无背景，独立圆角表头 ### 交互状态 Table 同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制： * **悬停**：`:hover` 或 `[data-hovered="true"]`（行背景变化） * **已选中**：`[data-selected="true"]`（行高亮） * **聚焦**：`:focus-visible` 或 `[data-focus-visible="true"]`（行、列与单元格的内嵌焦点环） * **禁用**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度） * **可排序**：`[data-allows-sorting="true"]`（列上的交互指针样式） * **拖动中**：`[data-dragging="true"]`（降低透明度） * **放置目标**：`[data-drop-target="true"]`（强调色背景） ## API 参考 ### Table | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------- | ----------- | -------------------------------------- | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。Primary 为灰色背景容器；Secondary 为扁平透明行。 | | `className` | `string` | - | 根容器的额外 CSS 类。 | | `children` | `React.ReactNode` | - | 表格内容（ScrollContainer、Footer 等）。 | ### Table.ScrollContainer | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ------------------- | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `React.ReactNode` | - | `Table.Content` 元素。 | ### Table.Content 继承自 [React Aria Table](https://react-spectrum.adobe.com/react-aria/Table.html)。 | Prop | 类型 | 默认值 | 描述 | | ------------------- | -------------------------------------- | -------- | ------------- | | `aria-label` | `string` | - | 表格的无障碍标签。 | | `selectionMode` | `"none" \| "single" \| "multiple"` | `"none"` | 选择行为。 | | `selectedKeys` | `Selection` | - | 受控的已选中 key。 | | `onSelectionChange` | `(keys: Selection) => void` | - | 选择变化时的事件处理函数。 | | `sortDescriptor` | `SortDescriptor` | - | 当前排序状态。 | | `onSortChange` | `(descriptor: SortDescriptor) => void` | - | 排序变化时的事件处理函数。 | | `className` | `string` | - | 额外的 CSS 类。 | ### Table.Header 继承自 [React Aria TableHeader](https://react-spectrum.adobe.com/react-aria/Table.html#tableheader)。 | Prop | 类型 | 默认值 | 描述 | | ---------- | --------------------------------------------------- | --- | -------------- | | `columns` | `T[]` | - | 渲染函数模式下的动态列数据。 | | `children` | `React.ReactNode \| (column: T) => React.ReactNode` | - | 静态列或渲染函数。 | ### Table.Column 继承自 [React Aria Column](https://react-spectrum.adobe.com/react-aria/Table.html#column)。 | Prop | 类型 | 默认值 | 描述 | | --------------- | ------------------------------------------------------------------- | ------- | --------------- | | `id` | `string` | - | 列标识符。 | | `allowsSorting` | `boolean` | `false` | 列是否可排序。 | | `isRowHeader` | `boolean` | `false` | 该列是否作为行表头。 | | `defaultWidth` | `string \| number` | - | 可调整列的默认宽度。 | | `minWidth` | `number` | - | 可调整列的最小宽度。 | | `children` | `React.ReactNode \| (values: ColumnRenderProps) => React.ReactNode` | - | 列内容或带排序方向的渲染函数。 | ### Table.Body 继承自 [React Aria TableBody](https://react-spectrum.adobe.com/react-aria/Table.html#tablebody)。 | Prop | 类型 | 默认值 | 描述 | | ------------------ | ------------------------------------------------- | --- | -------------- | | `items` | `T[]` | - | 渲染函数模式下的动态行数据。 | | `renderEmptyState` | `() => React.ReactNode` | - | 表格为空时展示的内容。 | | `children` | `React.ReactNode \| (item: T) => React.ReactNode` | - | 静态行或渲染函数。 | ### Table.Row 继承自 [React Aria Row](https://react-spectrum.adobe.com/react-aria/Table.html#row)。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------ | --- | ---------- | | `id` | `string \| number` | - | 行标识符。 | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `React.ReactNode` | - | 行单元格。 | ### Table.Cell 继承自 [React Aria Cell](https://react-spectrum.adobe.com/react-aria/Table.html#cell)。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ---------- | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `React.ReactNode` | - | 单元格内容。 | ### Table.SortableColumnHeader 渲染可排序列的标签与升序 / 降序指示器。请在 `Table.Column` 的渲染函数回调中使用，并将 `sortDirection` 透传进来。 | Prop | 类型 | 默认值 | 描述 | | --------------- | ----------------------------- | ------ | ---------------------------------------------------- | | `sortDirection` | `"ascending" \| "descending"` | - | 当前排序方向。请从 `Table.Column` 的渲染函数中透传。 | | `showIndicator` | `boolean` | `true` | 当存在排序方向时是否渲染指示器图标。 | | `indicator` | `React.ReactNode` | - | 自定义指示器元素。会覆盖默认的 chevron，并会被自动注入 `data-direction` 属性。 | | `className` | `string` | - | 包裹元素的额外 CSS 类。 | | `children` | `React.ReactNode` | - | 列标签内容。 | ### Table.Footer | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ----------- | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `React.ReactNode` | - | 表底内容（例如分页）。 | ### Table.ColumnResizer 继承自 [React Aria ColumnResizer](https://react-spectrum.adobe.com/react-aria/Table.html#columnresizer)。 | Prop | 类型 | 默认值 | 描述 | | ----------- | -------- | --- | ---------- | | `className` | `string` | - | 额外的 CSS 类。 | ### Table.ResizableContainer 继承自 [React Aria ResizableTableContainer](https://react-spectrum.adobe.com/react-aria/Table.html#resizabletablecontainer)。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ------------------- | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `React.ReactNode` | - | `Table.Content` 元素。 | ### Table.LoadMore 继承自 [React Aria TableLoadMoreItem](https://react-spectrum.adobe.com/react-aria/Table.html)。 | Prop | 类型 | 默认值 | 描述 | | ------------ | ----------------- | ------- | -------------- | | `isLoading` | `boolean` | `false` | 数据是否正在加载。 | | `onLoadMore` | `() => void` | - | 哨兵行可见时的事件处理函数。 | | `children` | `React.ReactNode` | - | 加载指示器内容。 | ### Table.LoadMoreContent | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | -------------------- | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `React.ReactNode` | - | 加载指示器内容（例如 Spinner）。 | ### Table.Collection 由 React Aria `Collection` 重新导出。用于在行内与静态单元格并存时渲染动态单元格（例如复选框）。 | Prop | 类型 | 默认值 | 描述 | | ---------- | ------------------------------ | --- | ---------- | | `items` | `T[]` | - | 集合条目。 | | `children` | `(item: T) => React.ReactNode` | - | 每个条目的渲染函数。 | ### TableLayout | Name | 类型 | 默认值 | 描述 | | ------------------------ | --------------------- | --- | --------------------------------------------- | | `rowHeight` | `number \| undefined` | 48 | 行的固定高度（px）。 | | `estimatedRowHeight` | `number \| undefined` | — | 行高可变时的估算高度。 | | `headingHeight` | `number \| undefined` | 48 | 分区表头的固定高度（px）。 | | `estimatedHeadingHeight` | `number \| undefined` | — | 表头高度可变时的估算高度。 | | `loaderHeight` | `number \| undefined` | 48 | 加载器元素的固定高度（px）。该加载器用于在根级或嵌套行/分区中渲染「加载更多」等加载行。 | | `dropIndicatorThickness` | `number \| undefined` | 2 | 放置指示器的线条粗细。 | | `gap` | `number \| undefined` | 0 | 条目之间的间距。 | | `padding` | `number \| undefined` | 0 | 列表的内边距。 | ## 相关组件 ## Related Components * **Pagination**: Page navigation with composable page links and controls * **Checkbox**: Binary choice input control * **Chip**: Compact elements for tags and filters </page> <page url="/cn/docs/react/components/calendar"> # Calendar 日历 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/calendar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(date-and-time)/calendar.mdx > 基于 React Aria Calendar 的可组合日期选择器，支持月网格、导航与年份选择 ## 用法 ```tsx import { Calendar } from '@heroui/react'; ``` ```tsx "use client"; import {Calendar} from "@heroui/react"; export function Basic() { return ( <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> ); } ``` ## 组件结构 ```tsx import {Calendar} from '@heroui/react'; export default () => ( <Calendar aria-label="Event date"> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody> {(date) => <Calendar.Cell date={date} />} </Calendar.GridBody> </Calendar.Grid> </Calendar> ) ``` ## 示例 ### 禁用 ```tsx "use client"; import {Calendar, Description} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function Disabled() { return ( <div className="flex flex-col items-center gap-4"> <Calendar isDisabled aria-label="活动日期" defaultValue={today(getLocalTimeZone())}> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> <Description className="text-center">日历已禁用</Description> </div> ); } ``` ### 只读 ```tsx "use client"; import {Calendar, Description} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function ReadOnly() { return ( <div className="flex flex-col items-center gap-4"> <Calendar isReadOnly aria-label="活动日期" defaultValue={today(getLocalTimeZone())}> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> <Description className="text-center">日历为只读</Description> </div> ); } ``` ### 默认值 ```tsx "use client"; import {Calendar} from "@heroui/react"; import {parseDate} from "@internationalized/date"; export function DefaultValue() { return ( <Calendar aria-label="活动日期" defaultValue={parseDate("2025-02-14")}> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> ); } ``` ### 年份选择 `Calendar.YearPickerTrigger`、`Calendar.YearPickerGrid` 及其 body/cell 子组件提供集成的年份导航模式。 ```tsx "use client"; import {Calendar} from "@heroui/react"; export function YearPicker() { return ( <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> <Calendar.YearPickerGrid> <Calendar.YearPickerGridBody> {({year}) => <Calendar.YearPickerCell year={year} />} </Calendar.YearPickerGridBody> </Calendar.YearPickerGrid> </Calendar> ); } ``` ### 受控组件 使用受控的 `value` 与 `focusedValue` 进行外部状态协调与自定义快捷操作。 ```tsx "use client"; import type {CalendarDate} from "@internationalized/date"; import {Button, ButtonGroup, Calendar, Description} from "@heroui/react"; import { getLocalTimeZone, parseDate, startOfMonth, startOfWeek, today, } from "@internationalized/date"; import {useState} from "react"; import {useLocale} from "react-aria-components"; export function Controlled() { const [value, setValue] = useState<CalendarDate | null>(null); const [focusedDate, setFocusedDate] = useState<CalendarDate>(parseDate("2025-12-25")); const {locale} = useLocale(); return ( <div className="flex flex-col items-center gap-4"> <ButtonGroup fullWidth size="sm" variant="tertiary"> <Button onPress={() => { const todayDate = today(getLocalTimeZone()); setValue(todayDate); setFocusedDate(todayDate); }} > 今天 </Button> <Button onPress={() => { const nextWeekStart = startOfWeek(today(getLocalTimeZone()), locale); setValue(nextWeekStart); setFocusedDate(nextWeekStart); }} > 本周 </Button> <Button onPress={() => { const nextMonthStart = startOfMonth(today(getLocalTimeZone())); setValue(nextMonthStart); setFocusedDate(nextMonthStart); }} > 本月 </Button> </ButtonGroup> <Calendar aria-label="活动日期" focusedValue={focusedDate} value={value} onChange={setValue} onFocusChange={setFocusedDate} > <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> <Description className="text-center"> 已选日期：{value ? value.toString() : "（未选）"} </Description> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={() => { const todayDate = today(getLocalTimeZone()); setValue(todayDate); setFocusedDate(todayDate); }} > 设为今天 </Button> <Button size="sm" variant="secondary" onPress={() => { const christmasDate = parseDate("2025-12-25"); setValue(christmasDate); setFocusedDate(christmasDate); }} > 设为圣诞节 </Button> <Button size="sm" variant="tertiary" onPress={() => setValue(null)}> 清空 </Button> </div> </div> ); } ``` ### 日期范围限制 ```tsx "use client"; import {Calendar, Description} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function MinMaxDates() { const now = today(getLocalTimeZone()); const minDate = now; const maxDate = now.add({months: 3}); return ( <div className="flex flex-col items-center gap-4"> <Calendar aria-label="预约日期" maxValue={maxDate} minValue={minDate}> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> <Description className="text-center"> 请在今天与 {maxDate.toString()} 之间选择日期。 </Description> </div> ); } ``` ### 不可用日期 使用 `isDateUnavailable` 阻止周末、节假日或已预订时段等日期。 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Calendar, Description} from "@heroui/react"; import {isWeekend} from "@internationalized/date"; import {useLocale} from "react-aria-components"; export function UnavailableDates() { const {locale} = useLocale(); const isDateUnavailable = (date: DateValue) => isWeekend(date, locale); return ( <div className="flex flex-col items-center gap-4"> <Calendar aria-label="预约日期" isDateUnavailable={isDateUnavailable}> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> <Description className="text-center">周末不可选</Description> </div> ); } ``` ### 月份周数 将 `weeksInMonth` 设为固定值（如 `6`）可在月份切换时保持网格高度稳定。在非公历 locale 中请谨慎使用，类似 `firstDayOfWeek`。 ```tsx "use client"; import {Calendar, Description} from "@heroui/react"; export function WeeksInMonth() { return ( <div className="flex flex-col items-center gap-4"> <Calendar aria-label="活动日期" weeksInMonth={6}> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> <Description className="text-center">每月固定显示 6 周，切换月份时避免布局跳动</Description> </div> ); } ``` ### 周视图 设置 `visibleDuration={{ weeks: n }}` 可一次显示一周或多周。导航按可见周范围前进。显示多周时使用 `pageBehavior="single"` 可每次移动一周。 ```tsx "use client"; import {Calendar, Label, ListBox, Select} from "@heroui/react"; import {useState} from "react"; const weekOptions = [ {id: "1", name: "1 周"}, {id: "2", name: "2 周"}, {id: "3", name: "3 周"}, {id: "4", name: "4 周"}, {id: "5", name: "5 周"}, {id: "6", name: "6 周"}, {id: "8", name: "8 周"}, ] as const; export function WeekView() { const [weeks, setWeeks] = useState(1); return ( <div className="flex flex-col items-center gap-6"> <Select className="w-40" value={String(weeks)} onChange={(value) => value && setWeeks(Number(value))} > <Label>可见周数</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {weekOptions.map((option) => ( <ListBox.Item key={option.id} id={option.id} textValue={option.name}> {option.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> <Calendar aria-label="周视图" visibleDuration={{weeks}}> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> </div> ); } ``` ### 日视图 设置 `visibleDuration={{ days: n }}` 可显示连续日期的滚动窗口。导航按可见日范围前进。显示多天时使用 `pageBehavior="single"` 可每次移动一天。 ```tsx "use client"; import {Calendar, Label, ListBox, Select} from "@heroui/react"; import {useState} from "react"; const dayOptions = [ {id: "1", name: "1 天"}, {id: "5", name: "5 天"}, {id: "7", name: "7 天"}, {id: "8", name: "8 天"}, {id: "10", name: "10 天"}, {id: "14", name: "14 天"}, {id: "21", name: "21 天"}, ] as const; export function DayView() { const [days, setDays] = useState(5); return ( <div className="flex flex-col items-center gap-6"> <Select className="w-40" value={String(days)} onChange={(value) => value && setDays(Number(value))} > <Label>可见天数</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {dayOptions.map((option) => ( <ListBox.Item key={option.id} id={option.id} textValue={option.name}> {option.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> <Calendar aria-label="日视图" visibleDuration={{days}}> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> </div> ); } ``` ### 多选 设置 `selectionMode="multiple"` 允许选择多个日期。`value`、`defaultValue` 与 `onChange` 使用日期数组。 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Calendar, Description} from "@heroui/react"; import {useState} from "react"; export function MultipleSelection() { const [value, setValue] = useState<readonly DateValue[]>([]); return ( <div className="flex flex-col items-center gap-4"> <Calendar aria-label="活动日期" selectionMode="multiple" value={value} onChange={setValue}> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> <Description className="text-center"> {value?.length ? `已选择 ${value.length} 个日期` : "可选择多个日期"} </Description> </div> ); } ``` ### 聚焦值 使用 `focusedValue` 与 `onFocusChange` 以编程方式控制聚焦日期。 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Button, Calendar, Description} from "@heroui/react"; import {parseDate} from "@internationalized/date"; import {useState} from "react"; export function FocusedValue() { const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-06-15")); return ( <div className="flex flex-col items-center gap-4"> <Calendar aria-label="活动日期" focusedValue={focusedDate} onFocusChange={setFocusedDate}> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> <Description className="text-center">聚焦：{focusedDate.toString()}</Description> <div className="flex flex-wrap justify-center gap-2"> <Button size="sm" variant="secondary" onPress={() => setFocusedDate(parseDate("2025-01-01"))} > 跳转到一月 </Button> <Button size="sm" variant="secondary" onPress={() => setFocusedDate(parseDate("2025-06-15"))} > 跳转到六月 </Button> <Button size="sm" variant="secondary" onPress={() => setFocusedDate(parseDate("2025-12-25"))} > 跳转到圣诞节 </Button> </div> </div> ); } ``` ### 单元格标记 可自定义 `Calendar.Cell` 子节点，并使用 `Calendar.CellIndicator` 显示事件等元数据。 ```tsx "use client"; import {Calendar} from "@heroui/react"; import {getLocalTimeZone, isToday} from "@internationalized/date"; const datesWithEvents = [3, 7, 12, 15, 21, 28]; export function WithIndicators() { return ( <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody> {(date) => ( <Calendar.Cell date={date}> {({formattedDate}) => ( <> {formattedDate} {(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && ( <Calendar.CellIndicator /> )} </> )} </Calendar.Cell> )} </Calendar.GridBody> </Calendar.Grid> </Calendar> ); } ``` ### 自定义导航图标 向 `Calendar.NavButton` 传入子节点以替换默认 chevron 图标。 ```tsx "use client"; import {Calendar} from "@heroui/react"; export function CustomIcons() { return ( <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous"> <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg"> <path d="M15.41 16.59L10.83 12l4.58-4.59L14 6l-6 6l6 6z" fill="currentColor" /> </svg> </Calendar.NavButton> <Calendar.NavButton slot="next"> <svg height={24} viewBox="0 0 24 24" width={24} xmlns="http://www.w3.org/2000/svg"> <path d="M8.59 16.59L13.17 12L8.59 7.41L10 6l6 6l-6 6z" fill="currentColor" /> </svg> </Calendar.NavButton> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> ); } ``` ### 多月份展示 使用 `visibleDuration` 与 `offset` 渲染多个月份网格，适用于预订与规划场景。 ```tsx "use client"; import {Calendar} from "@heroui/react"; export function MultipleMonths() { return ( <Calendar aria-label="行程日期" className="@container-normal w-full max-w-none overflow-x-auto" visibleDuration={{months: 2}} > <div className="mx-auto flex w-max gap-8"> <div className="w-64"> <Calendar.Header> <Calendar.NavButton slot="previous" /> <Calendar.Heading className="flex-none" /> <div className="size-6" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </div> <div className="w-64"> <Calendar.Header> <div className="size-6" /> <Calendar.Heading className="flex-none" offset={{months: 1}} /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid offset={{months: 1}}> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </div> </div> </Calendar> ); } ``` ### 典型场景 ```tsx "use client"; import type {CalendarDate, DateValue} from "@internationalized/date"; import {Button, Calendar} from "@heroui/react"; import {getLocalTimeZone, isWeekend, today} from "@internationalized/date"; import {useState} from "react"; import {useLocale} from "react-aria-components"; export function BookingCalendar() { const [selectedDate, setSelectedDate] = useState<CalendarDate | null>(null); const {locale} = useLocale(); const bookedDates = [5, 6, 12, 13, 14, 20]; const isDateUnavailable = (date: DateValue) => { return isWeekend(date, locale) || bookedDates.includes(date.day); }; return ( <div className="flex flex-col items-center gap-4"> <Calendar aria-label="预订日期" isDateUnavailable={isDateUnavailable} minValue={today(getLocalTimeZone())} value={selectedDate} onChange={setSelectedDate} > <Calendar.Header> <Calendar.Heading /> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody> {(date) => ( <Calendar.Cell date={date}> {({formattedDate, isUnavailable}) => ( <> {formattedDate} {!isUnavailable && !isWeekend(date, locale) && bookedDates.includes(date.day) && <Calendar.CellIndicator />} </> )} </Calendar.Cell> )} </Calendar.GridBody> </Calendar.Grid> </Calendar> <div className="flex flex-col gap-2 text-center"> <div className="flex items-center justify-center gap-4 text-xs text-muted"> <span className="flex items-center gap-1"> <span className="size-2 rounded-full bg-muted" /> 已有预订 </span> <span className="flex items-center gap-1"> <span className="size-2 rounded-full bg-default" /> 周末/不可用 </span> </div> {selectedDate ? ( <Button size="sm" variant="primary"> 预订 {selectedDate.toString()} </Button> ) : null} </div> </div> ); } ``` ### 国际化日历 默认情况下，Calendar 使用用户 locale 的历法系统显示日期。可用 `I18nProvider` 包裹 Calendar 并设置 [Unicode 历法 locale 扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 来覆盖。 以下示例展示印度历法系统： ```tsx "use client"; import {Calendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {I18nProvider} from "react-aria-components"; export function InternationalCalendar() { return ( <I18nProvider locale="hi-IN-u-ca-indian"> <Calendar aria-label="活动日期" defaultValue={today(getLocalTimeZone())}> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> <Calendar.YearPickerGrid> <Calendar.YearPickerGridBody> {({year}) => <Calendar.YearPickerCell year={year} />} </Calendar.YearPickerGridBody> </Calendar.YearPickerGrid> </Calendar> </I18nProvider> ); } ``` **Note:** `onChange` 事件始终返回与 `value` 或 `defaultValue` 相同历法系统的日期（未提供 value 时为公历），无论显示 locale 如何。这确保应用逻辑在单一历法系统下一致运行，同时仍以用户偏好的格式显示日期。 ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {Calendar} from "@heroui/react"; export function CustomStyles() { return ( <Calendar aria-label="自定义样式日历" className="w-63 rounded-2xl border border-border/80 bg-surface p-3 shadow-sm ring-1 ring-accent/5 dark:border-border/90 dark:ring-accent/10" > <Calendar.Header className="px-0.5 pb-4"> <Calendar.Heading className="text-sm font-medium text-foreground" /> <Calendar.NavButton className="text-accent-soft-foreground hover:bg-default hover:text-accent-soft-foreground active:scale-95" slot="previous" /> <Calendar.NavButton className="text-accent-soft-foreground hover:bg-default hover:text-accent-soft-foreground active:scale-95" slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => ( <Calendar.HeaderCell className="pb-2 text-xs font-medium text-muted"> {day} </Calendar.HeaderCell> )} </Calendar.GridHeader> <Calendar.GridBody> {(date) => ( <Calendar.Cell className="rounded-3xl hover:bg-default data-[hovered=true]:bg-default data-[outside-month=true]:text-muted data-[outside-month=true]:opacity-50 data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground data-[selected=true]:hover:bg-accent-hover data-[selected=true]:data-[hovered=true]:bg-accent-hover data-[selected=true]:data-[outside-month=true]:bg-default data-[today=true]:bg-accent-soft data-[today=true]:text-accent-soft-foreground data-[today=true]:hover:bg-accent-soft-hover data-[today=true]:data-[hovered=true]:bg-accent-soft-hover data-[selected=true]:data-[today=true]:bg-accent data-[selected=true]:data-[today=true]:hover:bg-accent-hover" date={date} /> )} </Calendar.GridBody> </Calendar.Grid> </Calendar> ); } ``` ### 全局 CSS ```css @layer components { .calendar { @apply w-72 rounded-2xl border border-border bg-surface p-3 shadow-sm; } .calendar__heading { @apply text-sm font-semibold text-default-700; } .calendar__cell[data-selected="true"] { @apply bg-accent text-accent-foreground; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Calendar 在 `packages/styles/components/calendar.css` 与 `packages/styles/components/calendar-year-picker.css` 中使用以下类： * `.calendar` - 根容器 * `.calendar__header` - 包含导航按钮与标题的头部行 * `.calendar__heading` - 当前月份标签 * `.calendar__nav-button` - 上/下月导航控件 * `.calendar__grid` - 主日期网格 * `.calendar__grid-header` - 星期标题行包装器 * `.calendar__grid-body` - 日期行包装器 * `.calendar__header-cell` - 星期标题单元格 * `.calendar__cell` - 可交互的日期单元格 * `.calendar__cell-indicator` - 日期单元格内的点指示器 * `.calendar-year-picker__trigger` - 年份选择器切换按钮 * `.calendar-year-picker__trigger-heading` - 年份选择器触发器内的标题文本 * `.calendar-year-picker__trigger-indicator` - 年份选择器触发器内的指示图标 * `.calendar-year-picker__year-grid` - 可选年份的覆盖网格 * `.calendar-year-picker__year-cell` - 单个年份选项 ### 交互状态 Calendar 同时支持伪类与 React Aria data 属性： * **Selected**：`[data-selected="true"]` * **Today**：`[data-today="true"]` * **Unavailable**：`[data-unavailable="true"]` * **Outside month**：`[data-outside-month="true"]` * **Hovered**：`:hover` 或 `[data-hovered="true"]` * **Pressed**：`:active` 或 `[data-pressed="true"]` * **Focus visible**：`:focus-visible` 或 `[data-focus-visible="true"]` * **Disabled**：`:disabled` 或 `[data-disabled="true"]` ## API 参考 ### Calendar Calendar 继承 React Aria [Calendar](https://react-spectrum.adobe.com/react-aria/Calendar.html) 的所有属性。 | Prop | 类型 | 默认值 | 描述 | | ------------------------ | --------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------ | | `selectionMode` | `'single' \| 'multiple'` | `'single'` | 是否可选择单个或多个日期 | | `value` | `DateValue \| null` 或 `DateValue[] \| null` | - | 受控选中日期。`selectionMode` 为 `multiple` 时使用数组 | | `defaultValue` | `DateValue \| null` 或 `DateValue[] \| null` | - | 初始选中日期（非受控） | | `onChange` | `(value: DateValue \| null)` 或 `(value: DateValue[] \| null) => void` | - | 选择变化时调用 | | `focusedValue` | `DateValue` | - | 受控聚焦日期 | | `onFocusChange` | `(value: DateValue) => void` | - | 焦点移至其他日期时调用 | | `minValue` | `DateValue` | 历法感知的 `1900-01-01` | 最早可选日期 | | `maxValue` | `DateValue` | 历法感知的 `2099-12-31` | 最晚可选日期 | | `weeksInMonth` | `number` | - | 月份中的周数，覆盖 locale 默认值 | | `isDateUnavailable` | `(date: DateValue) => boolean` | - | 标记日期为不可用 | | `firstDayOfWeek` | `'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'` | - | 覆盖 locale 默认的一周起始日 | | `pageBehavior` | `'visible' \| 'single'` | `'visible'` | 翻页按可见时长还是单个单位前进 | | `selectionAlignment` | `'start' \| 'center' \| 'end'` | `'center'` | 初始渲染时可见范围与选择的对齐方式 | | `isDisabled` | `boolean` | `false` | 禁用交互与选择 | | `isReadOnly` | `boolean` | `false` | 内容可读但不可更改选择 | | `isInvalid` | `boolean` | `false` | 标记日历为无效以显示验证 UI | | `visibleDuration` | `{months?: number; weeks?: number; days?: number}` | `{months: 1}` | 可见时间范围。月视图用 `{ months: n }`，周视图用 `{ weeks: n }`，日视图用 `{ days: n }` | | `defaultYearPickerOpen` | `boolean` | `false` | 内部年份选择器初始打开状态 | | `isYearPickerOpen` | `boolean` | - | 受控年份选择器打开状态 | | `onYearPickerOpenChange` | `(isOpen: boolean) => void` | - | 年份选择器打开状态变化时调用 | ### Composition Parts | Component | Description | | ------------------------------------- | ----------------------------------------------- | | `Calendar.Header` | 导航与标题的头部容器 | | `Calendar.Heading` | 可见范围的格式化标题。支持 `offset`（多月布局）与 `format`（月/年/日选项） | | `Calendar.NavButton` | 上/下月导航控件（`slot="previous"` 或 `slot="next"`） | | `Calendar.Grid` | 单个月份的日期网格（多月布局支持 `offset`） | | `Calendar.GridHeader` | 星期标题容器 | | `Calendar.GridBody` | 日期单元格 body 容器 | | `Calendar.HeaderCell` | 星期标签单元格 | | `Calendar.Cell` | 单个日期单元格 | | `Calendar.CellIndicator` | 自定义元数据的可选指示元素 | | `Calendar.YearPickerTrigger` | 切换年份选择器模式的触发器 | | `Calendar.YearPickerTriggerHeading` | 年份选择器触发器内的本地化标题内容 | | `Calendar.YearPickerTriggerIndicator` | 年份选择器触发器内的切换图标 | | `Calendar.YearPickerGrid` | 覆盖式年份选择网格容器 | | `Calendar.YearPickerGridBody` | 年份网格单元格的 body 渲染器 | | `Calendar.YearPickerCell` | 单个年份选项单元格 | ### Year Picker Parts 年份选择器子组件继承 React Aria [`useCalendarHeading`](https://react-aria.adobe.com/useCalendar#usecalendarheading) 与 [`useCalendarYearPicker`](https://react-aria.adobe.com/useCalendar#usecalendaryearpicker) 的格式化属性。 | Component | Prop | 类型 | 默认值 | 描述 | | ----------------------------------- | -------------- | ---------------------- | ------------------- | ------------------------------------------------- | | `Calendar.YearPickerTriggerHeading` | `format` | `DateFormatterOptions` | - | 自定义月/年标签（如 `{month: 'short'}`） | | `Calendar.YearPickerTriggerHeading` | `offset` | `{months?: number}` | - | 相对聚焦日期偏移标题（多月布局） | | `Calendar.YearPickerGrid` | `format` | `DateFormatterOptions` | `{year: 'numeric'}` | 自定义年份单元格标签（纪元、历法等） | | `Calendar.YearPickerGrid` | `visibleYears` | `number` | min–max 跨度或 `20` | 滑动窗口中显示的年份数。同时设置 `minValue` 与 `maxValue` 时默认为完整范围 | ### Calendar.Cell Render `Calendar.Cell` 子节点为函数时，可使用 React Aria render props： | Prop | 类型 | 描述 | | ---------------- | --------- | ----------- | | `formattedDate` | `string` | 单元格的本地化日期标签 | | `isSelected` | `boolean` | 日期是否选中 | | `isUnavailable` | `boolean` | 日期是否不可用 | | `isDisabled` | `boolean` | 单元格是否禁用 | | `isOutsideMonth` | `boolean` | 日期是否属于相邻月份 | 有关支持的历法系统及其标识符的完整列表，请参阅： * [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/) — 所有日期组件使用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具 * [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 覆盖子树的 locale * [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前 locale 与布局方向 ## 相关组件 ## Related Components * **RangeCalendar**: Interactive month grid for selecting date ranges * **DateField**: Date input field with labels, descriptions, and validation * **DatePicker**: Composable date picker with date field trigger and calendar popover </page> <page url="/cn/docs/react/components/date-field"> # DateField 日期字段 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/date-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(date-and-time)/date-field.mdx > 基于 React Aria DateField 的日期输入字段，包含标签、说明与校验 ## 用法 ```tsx import { DateField } from '@heroui/react'; ``` ```tsx "use client"; import {DateField, Label} from "@heroui/react"; export function Basic() { return ( <DateField className="w-[256px]" name="date"> <Label>日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> </DateField> ); } ``` ## 组件结构 ```tsx import {DateField, Label, Description, FieldError} from '@heroui/react'; export default () => ( <DateField> <Label /> <DateField.Group> <DateField.Input> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> </DateField.Group> <Description /> <FieldError /> </DateField> ) ``` > **DateField** 将标签、日期输入、说明与错误信息组合为单个无障碍组件。 ## 示例 ### 带图标 通过前缀或后缀图标增强日期输入。 ```tsx "use client"; import {Calendar} from "@gravity-ui/icons"; import {DateField, Label} from "@heroui/react"; export function WithPrefixIcon() { return ( <DateField className="w-[256px]" name="date"> <Label>日期</Label> <DateField.Group> <DateField.Prefix> <Calendar className="size-4 text-muted" /> </DateField.Prefix> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> </DateField> ); } ``` ```tsx "use client"; import {Calendar} from "@gravity-ui/icons"; import {DateField, Label} from "@heroui/react"; export function WithSuffixIcon() { return ( <DateField className="w-[256px]" name="date"> <Label>日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> <DateField.Suffix> <Calendar className="size-4 text-muted" /> </DateField.Suffix> </DateField.Group> </DateField> ); } ``` ```tsx "use client"; import {Calendar, ChevronDown} from "@gravity-ui/icons"; import {DateField, Description, Label} from "@heroui/react"; export function WithPrefixAndSuffix() { return ( <DateField className="w-[256px]" name="date"> <Label>日期</Label> <DateField.Group> <DateField.Prefix> <Calendar className="size-4 text-muted" /> </DateField.Prefix> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> <DateField.Suffix> <ChevronDown className="size-4 text-muted" /> </DateField.Suffix> </DateField.Group> <Description>输入日期</Description> </DateField> ); } ``` ### 变体 DateField.Group 组件支持两种视觉变体： * **`primary`**（默认）- 标准样式带阴影，适用于大多数场景 * **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内 ```tsx "use client"; import {DateField, Label} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-4"> <DateField className="w-[256px]" name="primary-date"> <Label>主要变体</Label> <DateField.Group variant="primary"> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> </DateField> <DateField className="w-[256px]" name="secondary-date"> <Label>次要变体</Label> <DateField.Group variant="secondary"> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> </DateField> </div> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请在 DateField.Group 上使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。 ```tsx "use client"; import {Calendar} from "@gravity-ui/icons"; import {DateField, Description, Label, Surface} from "@heroui/react"; export function OnSurface() { return ( <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6"> <DateField className="w-full" name="date"> <Label>日期</Label> <DateField.Group variant="secondary"> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> <Description>输入日期</Description> </DateField> <DateField className="w-full" name="date-2"> <Label>预约日期</Label> <DateField.Group variant="secondary"> <DateField.Prefix> <Calendar className="size-4 text-muted" /> </DateField.Prefix> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> <Description>输入预约日期</Description> </DateField> </Surface> ); } ``` ### 带描述 ```tsx "use client"; import {DateField, Description, Label} from "@heroui/react"; export function WithDescription() { return ( <div className="flex flex-col gap-4"> <DateField className="w-[256px]" name="date"> <Label>出生日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> <Description>输入出生日期</Description> </DateField> <DateField className="w-[256px]" name="appointment-date"> <Label>预约日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> <Description>输入预约日期</Description> </DateField> </div> ); } ``` ### 必填字段 ```tsx "use client"; import {DateField, Description, Label} from "@heroui/react"; export function Required() { return ( <div className="flex flex-col gap-4"> <DateField isRequired className="w-[256px]" name="date"> <Label>日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> </DateField> <DateField isRequired className="w-[256px]" name="start-date"> <Label>开始日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> <Description>必填项</Description> </DateField> </div> ); } ``` ### 禁用 ```tsx "use client"; import {DateField, Description, Label} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function Disabled() { return ( <div className="flex flex-col gap-4"> <DateField isDisabled className="w-[256px]" name="date" value={today(getLocalTimeZone())}> <Label>日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> <Description>该日期字段已禁用</Description> </DateField> <DateField isDisabled className="w-[256px]" name="date-empty"> <Label>日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> <Description>该日期字段已禁用</Description> </DateField> </div> ); } ``` ### 宽度充满 ```tsx "use client"; import {Calendar, ChevronDown} from "@gravity-ui/icons"; import {DateField, Label} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <DateField fullWidth name="date"> <Label>日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> </DateField> <DateField fullWidth name="date-icons"> <Label>日期</Label> <DateField.Group> <DateField.Prefix> <Calendar className="size-4 text-muted" /> </DateField.Prefix> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> <DateField.Suffix> <ChevronDown className="size-4 text-muted" /> </DateField.Suffix> </DateField.Group> </DateField> </div> ); } ``` ### 表单校验 配合 `FieldError` 使用 `isInvalid` 展示校验消息。 ```tsx "use client"; import {DateField, FieldError, Label} from "@heroui/react"; export function Invalid() { return ( <div className="flex flex-col gap-4"> <DateField isInvalid isRequired className="w-[256px]" name="date"> <Label>日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> <FieldError>请输入有效日期</FieldError> </DateField> <DateField isInvalid className="w-[256px]" name="invalid-date"> <Label>日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> <FieldError>日期须为将来</FieldError> </DateField> </div> ); } ``` ### 时间粒度 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {CircleQuestion} from "@gravity-ui/icons"; import {DateField, Label, ListBox, Select, Tooltip} from "@heroui/react"; import {parseDate, parseZonedDateTime} from "@internationalized/date"; import {useState} from "react"; export function Granularity() { const granularityOptions = [ {id: "day", label: "日"}, {id: "hour", label: "时"}, {id: "minute", label: "分"}, {id: "second", label: "秒"}, ] as const; const [granularity, setGranularity] = useState<"day" | "hour" | "minute" | "second">("day"); // Determine appropriate default value based on granularity let defaultValue: DateValue; if (granularity === "day") { defaultValue = parseDate("2025-02-03"); } else { // hour, minute, second defaultValue = parseZonedDateTime("2025-02-03T08:45:00[America/Los_Angeles]"); } return ( <div className="flex gap-4"> <DateField className="w-[256px]" defaultValue={defaultValue} granularity={granularity} name="granularity-date" > <Label>预约日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> </DateField> <div className="flex flex-col gap-1"> <div className="flex items-center gap-2"> <Label>粒度</Label> <Tooltip delay={0}> <Tooltip.Trigger aria-label="粒度说明"> <CircleQuestion className="size-4 text-muted" /> </Tooltip.Trigger> <Tooltip.Content placement="bottom start"> <p>决定日期选择器显示的最小单位。默认情况下，日期为「日」，时间为「分」。</p> </Tooltip.Content> </Tooltip> </div> <Select className="w-[110px]" placeholder="选择粒度" value={granularity} variant="secondary" onChange={(value) => setGranularity(value as typeof granularity)} > <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {granularityOptions.map((option) => ( <ListBox.Item key={option.id} id={option.id} textValue={option.label}> {option.label} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> </div> </div> ); } ``` ### 受控组件 控制 value 以与其他组件或状态管理同步。 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Button, DateField, Description, Label} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; export function Controlled() { const [value, setValue] = useState<DateValue | null>(null); return ( <div className="flex flex-col gap-4"> <DateField className="w-[256px]" name="date" value={value} onChange={setValue}> <Label>日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> <Description>当前值：{value ? value.toString() : "（空）"}</Description> </DateField> <div className="flex gap-2"> <Button variant="tertiary" onPress={() => setValue(today(getLocalTimeZone()))}> 设为今天 </Button> <Button variant="tertiary" onPress={() => setValue(null)}> 清空 </Button> </div> </div> ); } ``` ### 表单示例 包含校验与提交的完整表单示例。 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Calendar} from "@gravity-ui/icons"; import {Button, DateField, Description, FieldError, Form, Label} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; export function FormExample() { const [value, setValue] = useState<DateValue | null>(null); const [isSubmitting, setIsSubmitting] = useState(false); const todayDate = today(getLocalTimeZone()); const isInvalid = value !== null && value.compare(todayDate) < 0; const handleSubmit = (e: React.SyntheticEvent<HTMLFormElement>) => { e.preventDefault(); if (!value || isInvalid) { return; } setIsSubmitting(true); // Simulate API call setTimeout(() => { console.log("已提交日期：", {date: value}); setValue(null); setIsSubmitting(false); }, 1500); }; return ( <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}> <DateField isRequired className="w-full" isInvalid={isInvalid} minValue={todayDate} name="date" value={value} onChange={setValue} > <Label>预约日期</Label> <DateField.Group> <DateField.Prefix> <Calendar className="size-4 text-muted" /> </DateField.Prefix> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> {isInvalid ? ( <FieldError>日期须为今天或将来</FieldError> ) : ( <Description>输入日期 from today onwards</Description> )} </DateField> <Button className="w-full" isDisabled={!value || isInvalid} isPending={isSubmitting} type="submit" variant="primary" > {isSubmitting ? "提交中…" : "Submit"} </Button> </Form> ); } ``` ### 带校验 DateField 支持 `minValue`、`maxValue` 与自定义校验逻辑。 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {DateField, Description, FieldError, Label} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; export function WithValidation() { const [value, setValue] = useState<DateValue | null>(null); const todayDate = today(getLocalTimeZone()); const isInvalid = value !== null && value.compare(todayDate) < 0; return ( <div className="flex flex-col gap-4"> <DateField isRequired className="w-[256px]" isInvalid={isInvalid} minValue={todayDate} name="date" value={value} onChange={setValue} > <Label>日期</Label> <DateField.Group> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> {isInvalid ? ( <FieldError>日期须为今天或将来</FieldError> ) : ( <Description>输入日期 from today onwards</Description> )} </DateField> </div> ); } ``` ### 渲染函数 ```tsx "use client"; import {DateField, Label} from "@heroui/react"; export function RenderFunction() { return ( <DateField className="w-[256px]" name="date" render={(props) => <div {...props} data-custom="date-field" />} > <Label render={(props) => <span {...props} data-custom="date-field-label" />}>日期</Label> <DateField.Group render={(props) => <div {...props} data-custom="date-field-group" />}> <DateField.Input render={(props) => <div {...props} data-custom="date-field-input" />}> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> </DateField.Group> </DateField> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {DateField, Label} from "@heroui/react"; export function CustomStyles() { return ( <DateField className="w-64" name="due-date"> <Label>截止日期</Label> <DateField.Group className="rounded-xl border border-border/80 bg-default shadow-sm" variant="secondary" > <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> </DateField.Group> </DateField> ); } ``` ### 全局 CSS DateField 默认样式较轻量。覆盖 `.date-field` 类可自定义容器样式。 ```css @layer components { .date-field { @apply flex flex-col gap-1; &[data-invalid="true"], &[aria-invalid="true"] { [data-slot="description"] { @apply hidden; } } [data-slot="label"] { @apply w-fit; } [data-slot="description"] { @apply px-1; } } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 * `.date-field` – 轻量样式的根容器（`flex flex-col gap-1`） > **Note：** 子组件（[Label](/docs/react/components/label)、[Description](/docs/react/components/description)、[FieldError](/docs/react/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参阅对应文档。DateField.Group 样式见下文 API 参考。 ### 交互状态 DateField 会根据状态自动设置以下 data 属性： * **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` - 无效时自动隐藏 description slot * **Required**：`[data-required="true"]` - 当 `isRequired` 为 true 时应用 * **Disabled**：`[data-disabled="true"]` - 当 `isDisabled` 为 true 时应用 * **Focus Within**：`[data-focus-within="true"]` - 任一子输入聚焦时应用 ## API 参考 ### DateField DateField 继承 React Aria [DateField](https://react-aria.adobe.com/DateField.md) 的全部 props。 #### Base Props | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------ | ------- | ---------------------------------- | | `children` | `React.ReactNode \| (values: DateFieldRenderProps) => React.ReactNode` | - | 子组件（Label、DateField.Group 等）或渲染函数。 | | `className` | `string \| (values: DateFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 | | `style` | `React.CSSProperties \| (values: DateFieldRenderProps) => React.CSSProperties` | - | 内联样式，支持渲染 prop。 | | `fullWidth` | `boolean` | `false` | 日期字段是否占满容器宽度。 | | `id` | `string` | - | 元素的唯一 id。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DateFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | #### Value Props | Prop | 类型 | 默认值 | 描述 | | ------------------ | ------------------------------------ | --- | ----------------------------------------------------------------------------------------------- | | `value` | `DateValue \| null` | - | 当前值（受控）。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 | | `defaultValue` | `DateValue \| null` | - | 默认值（非受控）。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 | | `onChange` | `(value: DateValue \| null) => void` | - | 值变化时触发的事件处理函数。 | | `placeholderValue` | `DateValue \| null` | - | 影响占位符格式的占位日期。 | #### Validation Props | Prop | 类型 | 默认值 | 描述 | | -------------------- | -------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------ | | `isRequired` | `boolean` | `false` | 是否在提交表单前要求用户输入。 | | `isInvalid` | `boolean` | - | 值是否无效。 | | `minValue` | `DateValue \| null` | - | 用户可选择最早日期。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 | | `maxValue` | `DateValue \| null` | - | 用户可选择最晚日期。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 | | `isDateUnavailable` | `(date: DateValue) => boolean` | - | 针对每个日期调用；返回 true 表示该日期不可用。 | | `validate` | `(value: DateValue) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验还是 ARIA 属性。 | #### Format Props | Prop | 类型 | 默认值 | 描述 | | ------------------------- | ------------- | ------- | --------------------------------------- | | `granularity` | `Granularity` | - | 显示的最小单位。日期默认为 `"day"`，时间默认为 `"minute"`。 | | `hourCycle` | `12 \| 24` | - | 以 12 或 24 小时制显示时间；默认由语言环境决定。 | | `hideTimeZone` | `boolean` | `false` | 是否隐藏时区缩写。 | | `shouldForceLeadingZeros` | `boolean` | - | 是否始终为月、日、小时等显示前导零。 | #### State Props | Prop | 类型 | 默认值 | 描述 | | ------------ | --------- | --- | ----------- | | `isDisabled` | `boolean` | - | 是否禁用输入。 | | `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 | #### Form Props | Prop | 类型 | 默认值 | 描述 | | -------------- | --------- | --- | ----------------------------------------- | | `name` | `string` | - | 输入元素的 name，用于 HTML 表单提交；以 ISO 8601 字符串提交。 | | `autoFocus` | `boolean` | - | 是否在渲染后自动聚焦该元素。 | | `autoComplete` | `string` | - | 输入应提供的自动完成类型。 | #### Accessibility Props | Prop | 类型 | 默认值 | 描述 | | ------------------ | -------- | --- | ------------- | | `aria-label` | `string` | - | 无可见标签时的无障碍标签。 | | `aria-labelledby` | `string` | - | 标注该字段的元素 id。 | | `aria-describedby` | `string` | - | 描述该字段的元素 id。 | | `aria-details` | `string` | - | 包含额外详情的元素 id。 | ### Composition Components DateField 与以下独立组件配合使用，请分别导入并直接使用： * **Label** – 来自 `@heroui/react` 的字段标签 * **DateField.Group** – 日期输入分组（详见下文） * **DateField.Input** – 来自 `@heroui/react` 的分段位编辑输入 * **DateField.InputContainer** – 可横向滚动的容器，用于组合多个输入（例如开始/结束范围） * **DateField.Segment** – 单个日期段位（年、月、日等） * **DateField.Prefix** / **DateField.Suffix** – 输入组的前缀与后缀插槽 * **Description** – 来自 `@heroui/react` 的辅助说明 * **FieldError** – 来自 `@heroui/react` 的校验错误信息 这些组件各自有独立的 props API。在 DateField 中直接组合使用： ```tsx import {parseDate} from '@internationalized/date'; import {DateField, Label, Description, FieldError} from '@heroui/react'; <DateField isRequired isInvalid={hasError} minValue={today(getLocalTimeZone())} value={date} onChange={setDate} > <Label>Appointment Date</Label> <DateField.Group> <DateField.Input> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> </DateField.Group> <Description>Select a date from today onwards.</Description> <FieldError>Please select a valid date.</FieldError> </DateField> ``` ### DateValue Types DateField 使用 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) 中的类型： * `CalendarDate` – 不含时间与时区的日期 * `CalendarDateTime` – 含时间、不含时区 * `ZonedDateTime` – 含时间与时区 * `Time` – 仅时间 示例： ```tsx import {parseDate, today, getLocalTimeZone} from '@internationalized/date'; // Parse from string const date = parseDate('2024-01-15'); // Today's date const todayDate = today(getLocalTimeZone()); // Use in DateField <DateField value={date} onChange={setDate}> {/* ... */} </DateField> ``` > **说明：** DateField 依赖 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) 进行解析、运算与类型定义。更多类型与函数见 [Internationalized Date 文档](https://react-aria.adobe.com/internationalized/date/)。 ### Render Props 对 `className`、`style` 或 `children` 使用渲染 prop 时，可使用以下值： | Prop | 类型 | 描述 | | ---------------- | --------- | ------------- | | `isDisabled` | `boolean` | 字段是否禁用。 | | `isInvalid` | `boolean` | 字段当前是否无效。 | | `isReadOnly` | `boolean` | 字段是否只读。 | | `isRequired` | `boolean` | 字段是否必填。 | | `isFocused` | `boolean` | 字段是否聚焦。 | | `isFocusWithin` | `boolean` | 是否有子元素聚焦。 | | `isFocusVisible` | `boolean` | 焦点是否可见（键盘导航）。 | ### DateField.Group DateField.Group 继承 React Aria `Group` 的全部 props，并额外支持： | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------- | ----------- | ---------------------------------------------------------- | | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 | | `fullWidth` | `boolean` | `false` | 日期输入组是否占满容器宽度。 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 | ### DateField.Input DateField.Input 继承 React Aria `DateInput` 的全部 props，并额外支持： | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------- | ----------- | ------------------------------------------------------------- | | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 输入的视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 | `DateField.Input` 接受渲染函数作为子节点，函数参数为日期段位；每个段位对应日期的一部分（年、月、日等）。 ### DateField.Segment DateField.Segment 继承 React Aria `DateSegment` 的全部 props： | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------- | --- | ------------------------------------------ | | `segment` | `DateSegment` | - | 来自 DateField.Input 渲染函数的 `DateSegment` 对象。 | | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 | ### DateField.InputContainer DateField.InputContainer 接受标准 HTML `div` 属性： | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ---------------------------------- | | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 滚动容器中的内容（通常为多个 `DateField.Input`）。 | ### DateField.Prefix DateField.Prefix 接受标准 HTML `div` 属性： | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------------ | | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 前缀插槽中要显示的内容。 | ### DateField.Suffix DateField.Suffix 接受标准 HTML `div` 属性： | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------------ | | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 后缀插槽中要显示的内容。 | ## DateField.Group Styling ### Customizing the component classes 基础类作用于所有实例，可通过 `@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__input-container { @apply flex flex-1 items-center; overflow-x: auto; overflow-y: clip; scrollbar-width: none; } .date-input-group__prefix, .date-input-group__suffix { @apply pointer-events-none shrink-0 text-field-placeholder flex items-center; } } ``` ### DateField.Group CSS Classes * `.date-input-group` – 根容器样式 * `.date-input-group__input` – 输入包裹层样式 * `.date-input-group__input-container` – 用于组合多个输入的滚动容器 * `.date-input-group__segment` – 单个日期段位样式 * `.date-input-group__prefix` – 前缀元素样式 * `.date-input-group__suffix` – 后缀元素样式 ### DateField.Group Interactive States * **Hover**：`:hover` 或 `[data-hovered="true"]` * **Focus Within**：`[data-focus-within="true"]` 或 `:focus-within` * **Invalid**：`[data-invalid="true"]`（与 `aria-invalid` 同步） * **Disabled**：`[data-disabled="true"]` 或 `[aria-disabled="true"]` * **Segment Focus**：段位上 `:focus` 或 `[data-focused="true"]` * **Segment Placeholder**：段位上 `[data-placeholder="true"]` ## 相关组件 ## Related Components * **DatePicker**: Composable date picker with date field trigger and calendar popover * **Calendar**: Interactive month grid for selecting dates * **Label**: Accessible label for form controls </page> <page url="/cn/docs/react/components/date-picker"> # DatePicker 日期选择器 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/date-picker **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(date-and-time)/date-picker.mdx > 基于 React Aria DatePicker，通过 DateField 与 Calendar 组合的可组合日期选择器 ## 用法 ```tsx import { DatePicker, DateField, Calendar, Label } from '@heroui/react'; ``` ```tsx "use client"; import {Calendar, DateField, DatePicker, Label} from "@heroui/react"; export function Basic() { return ( <DatePicker className="w-72" name="date"> <Label>日期</Label> <DateField.Group fullWidth> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> <DateField.Suffix> <DatePicker.Trigger> <DatePicker.TriggerIndicator /> </DatePicker.Trigger> </DateField.Suffix> </DateField.Group> <DatePicker.Popover> <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> <Calendar.YearPickerGrid> <Calendar.YearPickerGridBody> {({year}) => <Calendar.YearPickerCell year={year} />} </Calendar.YearPickerGridBody> </Calendar.YearPickerGrid> </Calendar> </DatePicker.Popover> </DatePicker> ); } ``` ## 组件结构 `DatePicker` 采用组合优先 API。显式组合 `DateField` 与 `Calendar` 以控制结构与样式。 ```tsx import {Calendar, DateField, DatePicker, Label} from '@heroui/react'; export default () => ( <DatePicker> <Label /> <DateField.Group> <DateField.Input> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateField.Suffix> <DatePicker.Trigger> <DatePicker.TriggerIndicator /> </DatePicker.Trigger> </DateField.Suffix> </DateField.Group> <DatePicker.Popover> <Calendar aria-label="Choose date"> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> </Calendar> </DatePicker.Popover> </DatePicker> ) ``` ## 示例 ### 禁用 ```tsx "use client"; import {Calendar, DateField, DatePicker, Description, Label} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function Disabled() { return ( <DatePicker isDisabled className="w-72" name="date" value={today(getLocalTimeZone())}> <Label>日期</Label> <DateField.Group fullWidth> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> <DateField.Suffix> <DatePicker.Trigger> <DatePicker.TriggerIndicator /> </DatePicker.Trigger> </DateField.Suffix> </DateField.Group> <Description>该日期选择器已禁用。</Description> <DatePicker.Popover> <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> <Calendar.YearPickerGrid> <Calendar.YearPickerGridBody> {({year}) => <Calendar.YearPickerCell year={year} />} </Calendar.YearPickerGridBody> </Calendar.YearPickerGrid> </Calendar> </DatePicker.Popover> </DatePicker> ); } ``` ### 受控组件 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Button, Calendar, DateField, DatePicker, Description, Label} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; export function Controlled() { const [value, setValue] = useState<DateValue | null>(today(getLocalTimeZone())); return ( <div className="flex w-72 flex-col gap-4"> <DatePicker name="date" value={value} onChange={setValue}> <Label>日期</Label> <DateField.Group fullWidth> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> <DateField.Suffix> <DatePicker.Trigger> <DatePicker.TriggerIndicator /> </DatePicker.Trigger> </DateField.Suffix> </DateField.Group> <DatePicker.Popover> <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> <Calendar.YearPickerGrid> <Calendar.YearPickerGridBody> {({year}) => <Calendar.YearPickerCell year={year} />} </Calendar.YearPickerGridBody> </Calendar.YearPickerGrid> </Calendar> </DatePicker.Popover> </DatePicker> <Description>当前值：{value ? value.toString() : "（空）"}</Description> <div className="flex gap-2"> <Button variant="tertiary" onPress={() => setValue(today(getLocalTimeZone()))}> 设为今天 </Button> <Button variant="tertiary" onPress={() => setValue(null)}> 清空 </Button> </div> </div> ); } ``` ### 表单校验 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Calendar, DateField, DatePicker, FieldError, Label} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; export function WithValidation() { const [value, setValue] = useState<DateValue | null>(null); const currentDate = today(getLocalTimeZone()); const isInvalid = value != null && value.compare(currentDate) < 0; return ( <DatePicker isRequired className="w-72" isInvalid={isInvalid} minValue={currentDate} name="date" value={value} onChange={setValue} > <Label>预约日期</Label> <DateField.Group fullWidth> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> <DateField.Suffix> <DatePicker.Trigger> <DatePicker.TriggerIndicator /> </DatePicker.Trigger> </DateField.Suffix> </DateField.Group> <FieldError>日期须为今天或将来。</FieldError> <DatePicker.Popover> <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> <Calendar.YearPickerGrid> <Calendar.YearPickerGridBody> {({year}) => <Calendar.YearPickerCell year={year} />} </Calendar.YearPickerGridBody> </Calendar.YearPickerGrid> </Calendar> </DatePicker.Popover> </DatePicker> ); } ``` ### 格式选项 使用 `granularity`、`hourCycle`、`hideTimeZone`、`shouldForceLeadingZeros` 等 props 控制 DatePicker 值的显示方式。 ```tsx "use client"; import type {TimeValue} from "@heroui/react"; import type {DateValue} from "@internationalized/date"; import { Calendar, DateField, DatePicker, Label, ListBox, Select, Switch, TimeField, } from "@heroui/react"; import {getLocalTimeZone, parseDate, parseZonedDateTime} from "@internationalized/date"; import {useMemo, useState} from "react"; type Granularity = "day" | "hour" | "minute" | "second"; type HourCycle = 12 | 24; const granularityOptions: {label: string; value: Granularity}[] = [ {label: "日", value: "day"}, {label: "时", value: "hour"}, {label: "分", value: "minute"}, {label: "秒", value: "second"}, ]; const hourCycleOptions: {label: string; value: HourCycle}[] = [ {label: "12 小时制", value: 12}, {label: "24 小时制", value: 24}, ]; export function FormatOptions() { const [granularity, setGranularity] = useState<Granularity>("minute"); const [hourCycle, setHourCycle] = useState<HourCycle>(12); const [hideTimeZone, setHideTimeZone] = useState(false); const [shouldForceLeadingZeros, setShouldForceLeadingZeros] = useState(false); const timeGranularity = granularity !== "day" ? granularity : undefined; const showTimeField = !!timeGranularity; const defaultValue = useMemo<DateValue>(() => { const localTimeZone = getLocalTimeZone(); if (granularity === "day") { return parseDate("2026-02-03"); } return parseZonedDateTime(`2026-02-03T08:45:00[${localTimeZone}]`); }, [granularity]); return ( <div className="flex flex-col gap-4"> <DatePicker key={granularity} className="w-fit min-w-72" defaultValue={defaultValue} granularity={granularity} hideTimeZone={hideTimeZone} hourCycle={hourCycle} name="date" shouldForceLeadingZeros={shouldForceLeadingZeros} > {({state}) => ( <> <Label>日期和时间</Label> <DateField.Group fullWidth> <DateField.Input> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateField.Suffix> <DatePicker.Trigger> <DatePicker.TriggerIndicator /> </DatePicker.Trigger> </DateField.Suffix> </DateField.Group> <DatePicker.Popover className="flex flex-col gap-3"> <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> <Calendar.YearPickerGrid> <Calendar.YearPickerGridBody> {({year}) => <Calendar.YearPickerCell year={year} />} </Calendar.YearPickerGridBody> </Calendar.YearPickerGrid> </Calendar> {!!showTimeField && ( <div className="flex items-center justify-between"> <Label>时间</Label> <TimeField aria-label="时间" granularity={timeGranularity} hideTimeZone={hideTimeZone} hourCycle={hourCycle} name="time" shouldForceLeadingZeros={shouldForceLeadingZeros} value={state.timeValue} onChange={(v) => state.setTimeValue(v as TimeValue)} > <TimeField.Group variant="secondary"> <TimeField.Input> {(segment) => <TimeField.Segment segment={segment} />} </TimeField.Input> </TimeField.Group> </TimeField> </div> )} </DatePicker.Popover> </> )} </DatePicker> <div className="flex flex-wrap gap-4"> <div className="flex flex-col gap-1"> <Select className="w-[120px]" value={granularity} variant="secondary" onChange={(value) => setGranularity(value as Granularity)} > <Label>粒度</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {granularityOptions.map((option) => ( <ListBox.Item key={option.value} id={option.value} textValue={option.label}> {option.label} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> </div> <div className="flex flex-col gap-1"> <Select className="w-[120px]" value={hourCycle} variant="secondary" onChange={(value) => setHourCycle(Number(value) as HourCycle)} > <Label>小时制</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {hourCycleOptions.map((option) => ( <ListBox.Item key={option.value} id={option.value} textValue={option.label}> {option.label} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> </div> </div> <div className="flex min-w-80 flex-col gap-2"> <Switch isSelected={hideTimeZone} onChange={setHideTimeZone}> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 隐藏时区 </Switch.Content> </Switch> <Switch isSelected={shouldForceLeadingZeros} onChange={setShouldForceLeadingZeros}> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 强制前导零 </Switch.Content> </Switch> </div> </div> ); } ``` ### 表单示例 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import { Button, Calendar, DateField, DatePicker, Description, FieldError, Form, Label, } from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; export function FormExample() { const [value, setValue] = useState<DateValue | null>(null); const [isSubmitting, setIsSubmitting] = useState(false); const currentDate = today(getLocalTimeZone()); const isInvalid = value != null && value.compare(currentDate) < 0; const handleSubmit = (event: React.SyntheticEvent<HTMLFormElement>) => { event.preventDefault(); if (!value || isInvalid) { return; } setIsSubmitting(true); setTimeout(() => { setValue(null); setIsSubmitting(false); }, 1200); }; return ( <Form className="flex w-72 flex-col gap-3" onSubmit={handleSubmit}> <DatePicker isRequired isInvalid={isInvalid} minValue={currentDate} name="appointmentDate" value={value} onChange={setValue} > <Label>预约日期</Label> <DateField.Group fullWidth> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> <DateField.Suffix> <DatePicker.Trigger> <DatePicker.TriggerIndicator /> </DatePicker.Trigger> </DateField.Suffix> </DateField.Group> {isInvalid ? ( <FieldError>日期须为今天或将来。</FieldError> ) : ( <Description>请选择有效的预约日期。</Description> )} <DatePicker.Popover> <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> <Calendar.YearPickerGrid> <Calendar.YearPickerGridBody> {({year}) => <Calendar.YearPickerCell year={year} />} </Calendar.YearPickerGridBody> </Calendar.YearPickerGrid> </Calendar> </DatePicker.Popover> </DatePicker> <Button className="w-full" isDisabled={!value || isInvalid} isPending={isSubmitting} type="submit" > {isSubmitting ? "提交中…" : "提交"} </Button> </Form> ); } ``` ### 自定义指示器 未提供 children 时，`DatePicker.TriggerIndicator` 渲染默认 `IconCalendar`。传入 children 可替换。 ```tsx "use client"; import {Calendar, DateField, DatePicker, Description, Label} from "@heroui/react"; import {Icon} from "@iconify/react"; export function WithCustomIndicator() { return ( <DatePicker className="w-72" name="date"> <Label>日期</Label> <DateField.Group fullWidth> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> <DateField.Suffix> <DatePicker.Trigger> <DatePicker.TriggerIndicator> <Icon className="size-4" icon="gravity-ui:chevron-down" /> </DatePicker.TriggerIndicator> </DatePicker.Trigger> </DateField.Suffix> </DateField.Group> <Description>通过传入自定义子元素替换默认日历图标。</Description> <DatePicker.Popover> <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> <Calendar.YearPickerGrid> <Calendar.YearPickerGridBody> {({year}) => <Calendar.YearPickerCell year={year} />} </Calendar.YearPickerGridBody> </Calendar.YearPickerGrid> </Calendar> </DatePicker.Popover> </DatePicker> ); } ``` ### 渲染函数 ```tsx "use client"; import {Calendar, DateField, DatePicker, Label} from "@heroui/react"; export function RenderFunction() { return ( <DatePicker className="w-72" name="date" render={(props) => <div {...props} data-custom="date-picker" />} > <Label render={(props) => <span {...props} data-custom="date-picker-label" />}>日期</Label> <DateField.Group fullWidth render={(props) => <div {...props} data-custom="date-field-group" />} > <DateField.Input render={(props) => <div {...props} data-custom="date-field-input" />}> {(segment) => ( <DateField.Segment render={(props) => <span {...props} data-custom="date-field-segment" />} segment={segment} /> )} </DateField.Input> <DateField.Suffix> <DatePicker.Trigger render={(props) => <button {...props} data-custom="date-picker-trigger" />} > <DatePicker.TriggerIndicator /> </DatePicker.Trigger> </DateField.Suffix> </DateField.Group> <DatePicker.Popover> <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> <Calendar.YearPickerGrid> <Calendar.YearPickerGridBody> {({year}) => <Calendar.YearPickerCell year={year} />} </Calendar.YearPickerGridBody> </Calendar.YearPickerGrid> </Calendar> </DatePicker.Popover> </DatePicker> ); } ``` ### 国际化日历 默认情况下，DatePicker 使用用户 locale 的日历系统显示日期。可用 `I18nProvider` 包裹并设置 [Unicode 日历 locale 扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。 以下示例展示印度日历系统： ```tsx "use client"; import {Calendar, DateField, DatePicker, Label} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {I18nProvider} from "react-aria-components"; export function InternationalCalendar() { return ( <I18nProvider locale="hi-IN-u-ca-indian"> <DatePicker className="w-72" defaultValue={today(getLocalTimeZone())} name="international-date" > <Label>活动日期</Label> <DateField.Group fullWidth> <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> <DateField.Suffix> <DatePicker.Trigger> <DatePicker.TriggerIndicator /> </DatePicker.Trigger> </DateField.Suffix> </DateField.Group> <DatePicker.Popover> <Calendar aria-label="活动日期"> <Calendar.Header> <Calendar.YearPickerTrigger> <Calendar.YearPickerTriggerHeading /> <Calendar.YearPickerTriggerIndicator /> </Calendar.YearPickerTrigger> <Calendar.NavButton slot="previous" /> <Calendar.NavButton slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>} </Calendar.GridHeader> <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody> </Calendar.Grid> <Calendar.YearPickerGrid> <Calendar.YearPickerGridBody> {({year}) => <Calendar.YearPickerCell year={year} />} </Calendar.YearPickerGridBody> </Calendar.YearPickerGrid> </Calendar> </DatePicker.Popover> </DatePicker> </I18nProvider> ); } ``` **Note：** 无论显示的 locale 如何，`onChange` 事件始终返回与 `value` 或 `defaultValue` 相同日历系统的日期（未提供 value 时为 Gregorian）。这确保应用逻辑在单一日历系统下一致运行，同时仍可按用户偏好格式显示日期。 完整支持的日历系统及其标识符列表请参阅： * [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) ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {Calendar, DateField, DatePicker, Label} from "@heroui/react"; export function CustomStyles() { return ( <DatePicker className="w-72" name="event-date"> <Label>活动日期</Label> <DateField.Group fullWidth className="rounded-xl border border-border/80 bg-default shadow-sm" variant="secondary" > <DateField.Input>{(segment) => <DateField.Segment segment={segment} />}</DateField.Input> <DateField.Suffix> <DatePicker.Trigger className="text-muted"> <DatePicker.TriggerIndicator /> </DatePicker.Trigger> </DateField.Suffix> </DateField.Group> <DatePicker.Popover className="border border-border/80 shadow-sm"> <Calendar aria-label="活动日期" className="rounded-2xl bg-surface p-2"> <Calendar.Header> <Calendar.Heading className="font-medium text-foreground" /> <Calendar.NavButton className="text-muted hover:bg-default" slot="previous" /> <Calendar.NavButton className="text-muted hover:bg-default" slot="next" /> </Calendar.Header> <Calendar.Grid> <Calendar.GridHeader> {(day) => ( <Calendar.HeaderCell className="text-xs text-muted">{day}</Calendar.HeaderCell> )} </Calendar.GridHeader> <Calendar.GridBody> {(date) => ( <Calendar.Cell className="rounded-lg data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground" date={date} /> )} </Calendar.GridBody> </Calendar.Grid> </Calendar> </DatePicker.Popover> </DatePicker> ); } ``` ### 全局 CSS 使用 `@layer components` 自定义 DatePicker 基础类。 ```css @layer components { .date-picker { @apply inline-flex flex-col gap-1; } .date-picker__trigger { @apply inline-flex items-center justify-between; } .date-picker__trigger-indicator { @apply text-muted; } .date-picker__popover { @apply min-w-[var(--trigger-width)] p-0; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 命名以便复用自定义。 ### CSS 类 DatePicker 在 `packages/styles/components/date-picker.css` 中使用以下类： * `.date-picker` - 根包裹层 * `.date-picker__trigger` - 打开 popover 的触发器部分 * `.date-picker__trigger-indicator` - 默认/自定义指示器 slot * `.date-picker__popover` - Popover 内容包裹层 ### 交互状态 DatePicker 支持 React Aria data 属性与伪状态： * **Open**：触发器上 `[data-open="true"]` * **Disabled**：触发器上 `[data-disabled="true"]` 或 `[aria-disabled="true"]` * **Focus visible**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]` * **Hover**：触发器上 `:hover` 或 `[data-hovered="true"]` ## API 参考 ### DatePicker DatePicker 继承 React Aria [DatePicker](https://react-aria.adobe.com/DatePicker.md) 的所有 props。 | Prop | 类型 | 默认值 | 描述 | | -------------- | ----------------------------------------------------------------------------- | ------- | -------------------------- | | `value` | `DateValue \| null` | - | 受控选中日期值 | | `defaultValue` | `DateValue \| null` | - | 非受控模式下的默认选中值 | | `onChange` | `(value: DateValue \| null) => void` | - | 选中日期变化时调用 | | `isOpen` | `boolean` | - | 受控 popover 打开状态 | | `defaultOpen` | `boolean` | `false` | 初始 popover 打开状态 | | `onOpenChange` | `(isOpen: boolean) => void` | - | popover 打开状态变化时调用 | | `isDisabled` | `boolean` | `false` | 禁用日期选择与触发器交互 | | `isInvalid` | `boolean` | - | 标记字段为无效以显示校验状态 | | `minValue` | `DateValue` | - | 最小可选日期 | | `maxValue` | `DateValue` | - | 最大可选日期 | | `name` | `string` | - | HTML 表单提交时使用的 name | | `children` | `ReactNode \| (values: DatePickerRenderProps) => ReactNode` | - | 组合内容或 render 函数 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DatePickerRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Composition Parts | Component | Description | | ----------------------------- | ------------------------------- | | `DatePicker.Root` | 根 date picker 容器与状态所有者 | | `DatePicker.Trigger` | 触发按钮，通常渲染在 `DateField.Suffix` 内 | | `DatePicker.TriggerIndicator` | 带默认日历图标的指示器 slot | | `DatePicker.Popover` | `Calendar` 内容的 Popover 包裹层 | ### Related packages * [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 所有日期组件使用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具 * [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖 locale * [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前 locale 与布局方向 ## 相关组件 ## Related Components * **Calendar**: Interactive month grid for selecting dates * **RangeCalendar**: Interactive month grid for selecting date ranges * **DateField**: Date input field with labels, descriptions, and validation </page> <page url="/cn/docs/react/components/date-range-picker"> # DateRangePicker 日期范围选择器 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/date-range-picker **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(date-and-time)/date-range-picker.mdx > 基于 React Aria DateRangePicker，通过 DateField 与 RangeCalendar 组合的可组合日期范围选择器 ## 用法 ```tsx import { DateField, DateRangePicker, Label, RangeCalendar } from '@heroui/react'; ``` ```tsx "use client"; import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react"; export function Basic() { return ( <DateRangePicker className="w-80" endName="endDate" startName="startDate"> <Label>出行日期</Label> <DateField.Group fullWidth> <DateField.Input slot="start"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateRangePicker.RangeSeparator /> <DateField.Input slot="end"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateField.Suffix> <DateRangePicker.Trigger> <DateRangePicker.TriggerIndicator /> </DateRangePicker.Trigger> </DateField.Suffix> </DateField.Group> <DateRangePicker.Popover> <RangeCalendar aria-label="出行日期"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> <RangeCalendar.YearPickerGrid> <RangeCalendar.YearPickerGridBody> {({year}) => <RangeCalendar.YearPickerCell year={year} />} </RangeCalendar.YearPickerGridBody> </RangeCalendar.YearPickerGrid> </RangeCalendar> </DateRangePicker.Popover> </DateRangePicker> ); } ``` ## 组件结构 `DateRangePicker` 采用组合优先 API。显式组合 `DateField` 与 `RangeCalendar` 以控制结构与样式。 ```tsx import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react'; export default () => ( <DateRangePicker> <Label /> <DateField.Group> <DateField.InputContainer> <DateField.Input slot="start"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateRangePicker.RangeSeparator /> <DateField.Input slot="end"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> </DateField.InputContainer> <DateField.Suffix> <DateRangePicker.Trigger> <DateRangePicker.TriggerIndicator /> </DateRangePicker.Trigger> </DateField.Suffix> </DateField.Group> <DateRangePicker.Popover> <RangeCalendar aria-label="Choose trip dates"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody>{(date) => <RangeCalendar.Cell date={date} />}</RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> </DateRangePicker.Popover> </DateRangePicker> ) ``` ## 示例 ### 禁用 ```tsx "use client"; import {DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function Disabled() { const start = today(getLocalTimeZone()); return ( <DateRangePicker isDisabled className="w-80" endName="endDate" startName="startDate" value={{end: start.add({days: 4}), start}} > <Label>出行日期</Label> <DateField.Group fullWidth> <DateField.Input slot="start"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateRangePicker.RangeSeparator /> <DateField.Input slot="end"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateField.Suffix> <DateRangePicker.Trigger> <DateRangePicker.TriggerIndicator /> </DateRangePicker.Trigger> </DateField.Suffix> </DateField.Group> <Description>该日期范围选择器已禁用。</Description> <DateRangePicker.Popover> <RangeCalendar aria-label="出行日期"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> <RangeCalendar.YearPickerGrid> <RangeCalendar.YearPickerGridBody> {({year}) => <RangeCalendar.YearPickerCell year={year} />} </RangeCalendar.YearPickerGridBody> </RangeCalendar.YearPickerGrid> </RangeCalendar> </DateRangePicker.Popover> </DateRangePicker> ); } ``` ### 受控组件 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {Button, DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; type DateRange = { start: DateValue; end: DateValue; }; export function Controlled() { const start = today(getLocalTimeZone()); const [value, setValue] = useState<DateRange | null>({end: start.add({days: 4}), start}); return ( <div className="flex w-80 flex-col gap-4"> <DateRangePicker endName="endDate" startName="startDate" value={value} onChange={setValue}> <Label>出行日期</Label> <DateField.Group fullWidth> <DateField.Input slot="start"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateRangePicker.RangeSeparator /> <DateField.Input slot="end"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateField.Suffix> <DateRangePicker.Trigger> <DateRangePicker.TriggerIndicator /> </DateRangePicker.Trigger> </DateField.Suffix> </DateField.Group> <DateRangePicker.Popover> <RangeCalendar aria-label="出行日期"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> <RangeCalendar.YearPickerGrid> <RangeCalendar.YearPickerGridBody> {({year}) => <RangeCalendar.YearPickerCell year={year} />} </RangeCalendar.YearPickerGridBody> </RangeCalendar.YearPickerGrid> </RangeCalendar> </DateRangePicker.Popover> </DateRangePicker> <Description> 当前值：{value ? `${value.start.toString()} 至 ${value.end.toString()}` : "（空）"} </Description> <div className="flex gap-2"> <Button variant="tertiary" onPress={() => { const nextStart = today(getLocalTimeZone()); setValue({end: nextStart.add({days: 6}), start: nextStart}); }} > 设为一周 </Button> <Button variant="tertiary" onPress={() => setValue(null)}> 清空 </Button> </div> </div> ); } ``` ### 表单校验 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import {DateField, DateRangePicker, FieldError, Label, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; type DateRange = { start: DateValue; end: DateValue; }; export function WithValidation() { const [value, setValue] = useState<DateRange | null>(null); const currentDate = today(getLocalTimeZone()); const isInvalid = value != null && (value.start.compare(currentDate) < 0 || value.end.compare(value.start) < 0); return ( <DateRangePicker isRequired className="w-80" endName="endDate" isInvalid={isInvalid} minValue={currentDate} startName="startDate" value={value} onChange={setValue} > <Label>预订时段</Label> <DateField.Group fullWidth> <DateField.Input slot="start"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateRangePicker.RangeSeparator /> <DateField.Input slot="end"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateField.Suffix> <DateRangePicker.Trigger> <DateRangePicker.TriggerIndicator /> </DateRangePicker.Trigger> </DateField.Suffix> </DateField.Group> <FieldError>请选择从今天起的有效日期范围。</FieldError> <DateRangePicker.Popover> <RangeCalendar aria-label="预订时段"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> <RangeCalendar.YearPickerGrid> <RangeCalendar.YearPickerGridBody> {({year}) => <RangeCalendar.YearPickerCell year={year} />} </RangeCalendar.YearPickerGridBody> </RangeCalendar.YearPickerGrid> </RangeCalendar> </DateRangePicker.Popover> </DateRangePicker> ); } ``` ### 格式选项 使用 `granularity`、`hourCycle`、`hideTimeZone`、`shouldForceLeadingZeros` 等 props 控制 DateRangePicker 值的显示方式。 ```tsx "use client"; import type {TimeValue} from "@heroui/react"; import type {DateValue} from "@internationalized/date"; import { DateField, DateRangePicker, Label, ListBox, RangeCalendar, Select, Separator, Switch, TimeField, useLocale, } from "@heroui/react"; import { DateFormatter, getLocalTimeZone, parseDate, parseZonedDateTime, } from "@internationalized/date"; import {useMemo, useState} from "react"; type Granularity = "day" | "hour" | "minute" | "second"; type HourCycle = 12 | 24; type DateRange = { start: DateValue; end: DateValue; }; const granularityOptions: {label: string; value: Granularity}[] = [ {label: "日", value: "day"}, {label: "时", value: "hour"}, {label: "分", value: "minute"}, {label: "秒", value: "second"}, ]; const hourCycleOptions: {label: string; value: HourCycle}[] = [ {label: "12 小时制", value: 12}, {label: "24 小时制", value: 24}, ]; export function FormatOptions() { const [granularity, setGranularity] = useState<Granularity>("minute"); const [hourCycle, setHourCycle] = useState<HourCycle>(12); const [hideTimeZone, setHideTimeZone] = useState(false); const [shouldForceLeadingZeros, setShouldForceLeadingZeros] = useState(false); const {locale} = useLocale(); const dateFormatter = new DateFormatter(locale, { day: "numeric", month: "short", year: "numeric", }); const formatDate = (date: DateRange) => { const localTimeZone = getLocalTimeZone(); const start = date.start.toDate(localTimeZone); const end = date.end.toDate(localTimeZone); return dateFormatter.formatRange(start, end); }; const defaultValue = useMemo<DateRange>(() => { const localTimeZone = getLocalTimeZone(); if (granularity === "day") { return { end: parseDate("2025-02-10"), start: parseDate("2025-02-03"), }; } return { end: parseZonedDateTime(`2026-02-10T18:45:00[${localTimeZone}]`), start: parseZonedDateTime(`2026-02-03T08:45:00[${localTimeZone}]`), }; }, [granularity]); const timeGranularity = granularity !== "day" ? granularity : undefined; const showTimeField = !!timeGranularity; return ( <div className="flex w-full flex-col gap-4"> <DateRangePicker key={granularity} className="w-max min-w-80" defaultValue={defaultValue} endName="endDate" granularity={granularity} hideTimeZone={hideTimeZone} hourCycle={hourCycle} shouldForceLeadingZeros={shouldForceLeadingZeros} startName="startDate" > {({state}) => ( <> <Label>日期范围</Label> <DateField.Group> <DateField.InputContainer> <DateField.Input slot="start"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateRangePicker.RangeSeparator /> <DateField.Input slot="end"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> </DateField.InputContainer> <DateField.Suffix> <DateRangePicker.Trigger> <DateRangePicker.TriggerIndicator /> </DateRangePicker.Trigger> </DateField.Suffix> </DateField.Group> <DateRangePicker.Popover className="flex w-full flex-col gap-3"> <RangeCalendar aria-label="出行日期" className="w-full"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> <RangeCalendar.YearPickerGrid> <RangeCalendar.YearPickerGridBody> {({year}) => <RangeCalendar.YearPickerCell year={year} />} </RangeCalendar.YearPickerGridBody> </RangeCalendar.YearPickerGrid> </RangeCalendar> {!!showTimeField && ( <div className="flex flex-col gap-3"> <div className="flex items-center justify-between"> <Label>开始时间</Label> <TimeField aria-label="开始时间" granularity={timeGranularity} hideTimeZone={hideTimeZone} hourCycle={hourCycle} name="startTime" shouldForceLeadingZeros={shouldForceLeadingZeros} value={state.timeRange?.start ?? null} onChange={(v) => state.setTimeRange({ end: state.timeRange?.end as TimeValue, start: v as TimeValue, }) } > <TimeField.Group variant="secondary"> <TimeField.Input> {(segment) => <TimeField.Segment segment={segment} />} </TimeField.Input> </TimeField.Group> </TimeField> </div> <div className="flex items-center justify-between"> <Label>结束时间</Label> <TimeField aria-label="结束时间" granularity={timeGranularity} hideTimeZone={hideTimeZone} hourCycle={hourCycle} name="endTime" shouldForceLeadingZeros={shouldForceLeadingZeros} value={state.timeRange?.end ?? null} onChange={(v) => state.setTimeRange({ end: v as TimeValue, start: state.timeRange?.start as TimeValue, }) } > <TimeField.Group variant="secondary"> <TimeField.Input> {(segment) => <TimeField.Segment segment={segment} />} </TimeField.Input> </TimeField.Group> </TimeField> </div> </div> )} <span className="mt-1 text-xs text-muted"> 已选：{" "} {state.value && state.value.start && state.value.end ? formatDate({end: state.value.end, start: state.value.start}) : "未选择日期"} </span> </DateRangePicker.Popover> </> )} </DateRangePicker> <Separator className="my-5" /> <Label className="text-xs font-medium text-muted">格式选项</Label> <div className="flex flex-wrap gap-4"> <div className="flex flex-col gap-1"> <Select className="w-[120px]" name="granularity" value={granularity} variant="secondary" onChange={(value) => setGranularity(value as Granularity)} > <Label>粒度</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {granularityOptions.map((option) => ( <ListBox.Item key={option.value} id={option.value} textValue={option.label}> {option.label} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> </div> <div className="flex flex-col gap-1"> <Select className="w-[120px]" value={hourCycle} variant="secondary" onChange={(value) => setHourCycle(Number(value) as HourCycle)} > <Label>小时制</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {hourCycleOptions.map((option) => ( <ListBox.Item key={option.value} id={option.value} textValue={option.label}> {option.label} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> </div> </div> <div className="flex min-w-[529px] flex-col gap-2"> <Switch isSelected={hideTimeZone} onChange={setHideTimeZone}> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 隐藏时区 </Switch.Content> </Switch> <Switch isSelected={shouldForceLeadingZeros} onChange={setShouldForceLeadingZeros}> <Switch.Content> <Switch.Control> <Switch.Thumb /> </Switch.Control> 强制前导零 </Switch.Content> </Switch> </div> </div> ); } ``` ### 表单示例 ```tsx "use client"; import type {DateValue} from "@internationalized/date"; import { Button, DateField, DateRangePicker, Description, FieldError, Form, Label, RangeCalendar, } from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {useState} from "react"; type DateRange = { start: DateValue; end: DateValue; }; export function FormExample() { const [value, setValue] = useState<DateRange | null>(null); const [isSubmitting, setIsSubmitting] = useState(false); const currentDate = today(getLocalTimeZone()); const isInvalid = value != null && (value.start.compare(currentDate) < 0 || value.end.compare(value.start) < 0); const handleSubmit = (event: React.SyntheticEvent<HTMLFormElement>) => { event.preventDefault(); if (!value || isInvalid) return; setIsSubmitting(true); setTimeout(() => { setValue(null); setIsSubmitting(false); }, 1200); }; return ( <Form className="flex w-80 flex-col gap-3" onSubmit={handleSubmit}> <DateRangePicker isRequired endName="tripEndDate" isInvalid={isInvalid} minValue={currentDate} startName="tripStartDate" value={value} onChange={setValue} > <Label>出行日期</Label> <DateField.Group fullWidth> <DateField.Input slot="start"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateRangePicker.RangeSeparator /> <DateField.Input slot="end"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateField.Suffix> <DateRangePicker.Trigger> <DateRangePicker.TriggerIndicator /> </DateRangePicker.Trigger> </DateField.Suffix> </DateField.Group> {isInvalid ? ( <FieldError>请选择从今天起的有效日期范围。</FieldError> ) : ( <Description>选择入住与退房日期。</Description> )} <DateRangePicker.Popover> <RangeCalendar aria-label="出行日期"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> <RangeCalendar.YearPickerGrid> <RangeCalendar.YearPickerGridBody> {({year}) => <RangeCalendar.YearPickerCell year={year} />} </RangeCalendar.YearPickerGridBody> </RangeCalendar.YearPickerGrid> </RangeCalendar> </DateRangePicker.Popover> </DateRangePicker> <Button className="w-full" isDisabled={!value || isInvalid} isPending={isSubmitting} type="submit" > {isSubmitting ? "提交中…" : "提交"} </Button> </Form> ); } ``` ### 自定义指示器 未提供 children 时，`DateRangePicker.TriggerIndicator` 渲染默认 `IconCalendar`。传入 children 可替换。 ```tsx "use client"; import {DateField, DateRangePicker, Description, Label, RangeCalendar} from "@heroui/react"; import {Icon} from "@iconify/react"; export function WithCustomIndicator() { return ( <DateRangePicker className="w-80" endName="endDate" startName="startDate"> <Label>出行日期</Label> <DateField.Group fullWidth> <DateField.Input slot="start"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateRangePicker.RangeSeparator /> <DateField.Input slot="end"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateField.Suffix> <DateRangePicker.Trigger> <DateRangePicker.TriggerIndicator> <Icon className="size-4" icon="gravity-ui:chevron-down" /> </DateRangePicker.TriggerIndicator> </DateRangePicker.Trigger> </DateField.Suffix> </DateField.Group> <Description>通过传入自定义子元素替换默认日历图标。</Description> <DateRangePicker.Popover> <RangeCalendar aria-label="出行日期"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> <RangeCalendar.YearPickerGrid> <RangeCalendar.YearPickerGridBody> {({year}) => <RangeCalendar.YearPickerCell year={year} />} </RangeCalendar.YearPickerGridBody> </RangeCalendar.YearPickerGrid> </RangeCalendar> </DateRangePicker.Popover> </DateRangePicker> ); } ``` ### 渲染函数 ```tsx "use client"; import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react"; export function RenderFunction() { return ( <DateRangePicker className="w-80" endName="endDate" render={(props) => <div data-custom="foo" {...props} />} startName="startDate" > <Label>出行日期</Label> <DateField.Group fullWidth> <DateField.Input slot="start"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateRangePicker.RangeSeparator /> <DateField.Input slot="end"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateField.Suffix> <DateRangePicker.Trigger> <DateRangePicker.TriggerIndicator /> </DateRangePicker.Trigger> </DateField.Suffix> </DateField.Group> <DateRangePicker.Popover> <RangeCalendar aria-label="出行日期"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> <RangeCalendar.YearPickerGrid> <RangeCalendar.YearPickerGridBody> {({year}) => <RangeCalendar.YearPickerCell year={year} />} </RangeCalendar.YearPickerGridBody> </RangeCalendar.YearPickerGrid> </RangeCalendar> </DateRangePicker.Popover> </DateRangePicker> ); } ``` ### 国际化日历 默认情况下，DateRangePicker 使用用户 locale 的日历系统显示日期。可用 `I18nProvider` 包裹并设置 [Unicode 日历 locale 扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。 以下示例展示印度日历系统： ```tsx "use client"; import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; import {I18nProvider} from "react-aria-components"; export function InternationalCalendar() { const start = today(getLocalTimeZone()); return ( <I18nProvider locale="hi-IN-u-ca-indian"> <DateRangePicker className="w-80" defaultValue={{end: start.add({days: 7}), start}} endName="endDate" startName="startDate" > <Label>出行日期</Label> <DateField.Group fullWidth> <DateField.Input slot="start"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateRangePicker.RangeSeparator /> <DateField.Input slot="end"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateField.Suffix> <DateRangePicker.Trigger> <DateRangePicker.TriggerIndicator /> </DateRangePicker.Trigger> </DateField.Suffix> </DateField.Group> <DateRangePicker.Popover> <RangeCalendar aria-label="出行日期"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> <RangeCalendar.YearPickerGrid> <RangeCalendar.YearPickerGridBody> {({year}) => <RangeCalendar.YearPickerCell year={year} />} </RangeCalendar.YearPickerGridBody> </RangeCalendar.YearPickerGrid> </RangeCalendar> </DateRangePicker.Popover> </DateRangePicker> </I18nProvider> ); } ``` **Note：** 无论显示的 locale 如何，`onChange` 事件始终返回与 `value` 或 `defaultValue` 相同日历系统的日期（未提供 value 时为 Gregorian）。 完整支持的日历系统及其标识符列表请参阅： * [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) ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {DateField, DateRangePicker, Label, RangeCalendar} from "@heroui/react"; export function CustomStyles() { return ( <DateRangePicker className="w-80" endName="checkout" startName="checkin"> <Label>入住日期</Label> <DateField.Group fullWidth className="rounded-xl border border-border/80 bg-default shadow-sm" variant="secondary" > <DateField.Input slot="start"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateRangePicker.RangeSeparator className="text-muted" /> <DateField.Input slot="end"> {(segment) => <DateField.Segment segment={segment} />} </DateField.Input> <DateField.Suffix> <DateRangePicker.Trigger className="text-muted"> <DateRangePicker.TriggerIndicator /> </DateRangePicker.Trigger> </DateField.Suffix> </DateField.Group> <DateRangePicker.Popover className="border border-border/80 shadow-sm"> <RangeCalendar aria-label="入住日期" className="rounded-2xl bg-surface p-2"> <RangeCalendar.Header> <RangeCalendar.Heading className="font-medium text-foreground" /> <RangeCalendar.NavButton className="text-muted hover:bg-default" slot="previous" /> <RangeCalendar.NavButton className="text-muted hover:bg-default" slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => ( <RangeCalendar.HeaderCell className="text-xs text-muted"> {day} </RangeCalendar.HeaderCell> )} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> </DateRangePicker.Popover> </DateRangePicker> ); } ``` ### 全局 CSS 使用 `@layer components` 自定义 DateRangePicker 基础类。 ```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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 DateRangePicker 在 `packages/styles/components/date-range-picker.css` 中使用以下类： * `.date-range-picker` - 根包裹层 * `.date-range-picker__trigger` - 打开 popover 的触发器部分 * `.date-range-picker__trigger-indicator` - 默认/自定义指示器 slot * `.date-range-picker__range-separator` - 开始与结束日期输入之间的分隔符 * `.date-range-picker__popover` - Popover 内容包裹层 ### 交互状态 DateRangePicker 支持 React Aria data 属性与伪状态： * **Open**：触发器上 `[data-open="true"]` * **Disabled**：触发器上 `[data-disabled="true"]` 或 `[aria-disabled="true"]` * **Focus visible**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]` * **Hover**：触发器上 `:hover` 或 `[data-hovered="true"]` ## API 参考 ### DateRangePicker DateRangePicker 继承 React Aria [DateRangePicker](https://react-aria.adobe.com/DateRangePicker) 的所有 props。 | Prop | 类型 | 默认值 | 描述 | | -------------- | ---------------------------------------------------------------------------------- | ------- | -------------------------- | | `value` | `{ start: DateValue; end: DateValue } \| null` | - | 受控选中日期范围值 | | `defaultValue` | `{ start: DateValue; end: DateValue } \| null` | - | 非受控模式下的默认选中范围 | | `onChange` | `(value: { start: DateValue; end: DateValue } \| null) => void` | - | 选中范围变化时调用 | | `isOpen` | `boolean` | - | 受控 popover 打开状态 | | `defaultOpen` | `boolean` | `false` | 初始 popover 打开状态 | | `onOpenChange` | `(isOpen: boolean) => void` | - | popover 打开状态变化时调用 | | `isDisabled` | `boolean` | `false` | 禁用范围选择与触发器交互 | | `isInvalid` | `boolean` | - | 标记字段为无效以显示校验状态 | | `minValue` | `DateValue` | - | 最小可选日期 | | `maxValue` | `DateValue` | - | 最大可选日期 | | `startName` | `string` | - | HTML 表单提交时开始日期的 name | | `endName` | `string` | - | HTML 表单提交时结束日期的 name | | `children` | `ReactNode \| (values: DateRangePickerRenderProps) => ReactNode` | - | 组合内容或 render 函数 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DateRangePickerRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Composition Parts | Component | Description | | ---------------------------------- | ------------------------------- | | `DateRangePicker.Root` | 根 date range picker 容器与状态所有者 | | `DateRangePicker.Trigger` | 触发按钮，通常渲染在 `DateField.Suffix` 内 | | `DateRangePicker.TriggerIndicator` | 带默认日历图标的指示器 slot | | `DateRangePicker.RangeSeparator` | 开始与结束日期输入之间的分隔符部分 | | `DateRangePicker.Popover` | `RangeCalendar` 内容的 Popover 包裹层 | ### Related packages * [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) — 所有日期组件使用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具 * [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖 locale * [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前 locale 与布局方向 ## 相关组件 ## 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 </page> <page url="/cn/docs/react/components/range-calendar"> # RangeCalendar 范围日历 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/range-calendar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(date-and-time)/range-calendar.mdx > 基于 React Aria RangeCalendar 的可组合日期范围选择器，包含月份网格、导航与年份选择支持。 ## 用法 ```tsx import { RangeCalendar } from '@heroui/react'; ``` ```tsx "use client"; import {RangeCalendar} from "@heroui/react"; export function Basic() { return ( <RangeCalendar aria-label="行程日期" firstDayOfWeek="mon"> <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> ); } ``` ## 组件结构 ```tsx import {RangeCalendar} from '@heroui/react'; export default () => ( <RangeCalendar aria-label="Trip dates"> <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> ) ``` ## 示例 ### 禁用 ```tsx "use client"; import {Description, RangeCalendar} from "@heroui/react"; export function Disabled() { return ( <div className="flex flex-col items-center gap-4"> <RangeCalendar isDisabled aria-label="行程日期"> <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> <Description className="text-center">区间日历已禁用</Description> </div> ); } ``` ### 年份选择 `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 ( <RangeCalendar aria-label="行程日期"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> <RangeCalendar.YearPickerGrid> <RangeCalendar.YearPickerGridBody> {({year}) => <RangeCalendar.YearPickerCell year={year} />} </RangeCalendar.YearPickerGridBody> </RangeCalendar.YearPickerGrid> </RangeCalendar> ); } ``` ### 默认值 ```tsx "use client"; import {RangeCalendar} from "@heroui/react"; import {parseDate} from "@internationalized/date"; export function DefaultValue() { return ( <RangeCalendar aria-label="行程日期" defaultValue={{end: parseDate("2025-02-12"), start: parseDate("2025-02-03")}} firstDayOfWeek="mon" > <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> ); } ``` ### 受控组件 ```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<DateRange | null>(null); const [focusedDate, setFocusedDate] = useState<DateValue>(parseDate("2025-12-25")); const {locale} = useLocale(); return ( <div className="flex flex-col items-center gap-4"> <ButtonGroup variant="tertiary"> <Button onPress={() => { const start = today(getLocalTimeZone()); setFocusedDate(start); }} > 本周 </Button> <Button onPress={() => { const nextWeekStart = startOfWeek(today(getLocalTimeZone()).add({weeks: 1}), locale); setFocusedDate(nextWeekStart); }} > 下周 </Button> <Button onPress={() => { const nextMonthStart = startOfMonth(today(getLocalTimeZone()).add({months: 1})); setFocusedDate(nextMonthStart); }} > 下月 </Button> </ButtonGroup> <RangeCalendar aria-label="行程日期" firstDayOfWeek="mon" focusedValue={focusedDate} value={value} onChange={setValue} onFocusChange={setFocusedDate} > <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> <Description className="text-center"> 已选区间： {value ? `${value.start.toString()} -> ${value.end.toString()}` : "（无）"} </Description> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={() => { const start = today(getLocalTimeZone()); setValue({end: start.add({days: 6}), start}); setFocusedDate(start); }} > 设为 1 周 </Button> <Button size="sm" variant="secondary" onPress={() => { const start = parseDate("2025-12-20"); setValue({end: parseDate("2025-12-31"), start}); setFocusedDate(start); }} > 设为节假日 </Button> <Button size="sm" variant="tertiary" onPress={() => setValue(null)}> 清空 </Button> </div> </div> ); } ``` ### 日期范围限制 ```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 ( <div className="flex flex-col items-center gap-4"> <RangeCalendar aria-label="行程日期" maxValue={maxDate} minValue={minDate}> <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> <Description className="text-center"> 请在今天与 {maxDate.toString()} 之间选择日期。 </Description> </div> ); } ``` ### 不可用日期 使用 `isDateUnavailable` 屏蔽周末、节假日或已预订等不可用日期。 ```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 ( <div className="flex flex-col items-center gap-4"> <RangeCalendar aria-label="行程日期" defaultValue={{end: now.add({days: 9}), start: now.add({days: 6})}} firstDayOfWeek="mon" isDateUnavailable={isDateUnavailable} > <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> <Description className="text-center">部分日期不可选</Description> </div> ); } ``` ### 基于锚点的不可用日期 选择范围时，`isDateUnavailable` 会收到第二个参数 `anchorDate`（首个选中日期）。可用它限制哪些结束日期有效（例如起始日期后 7 天内）。 ```tsx "use client"; import type {CalendarDate, DateValue} from "@internationalized/date"; import {Description, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function AnchorUnavailableDates() { const now = today(getLocalTimeZone()); const isDateUnavailable = (date: DateValue, anchorDate: CalendarDate | null) => { return anchorDate != null && Math.abs(date.compare(anchorDate)) > 7; }; return ( <div className="flex flex-col items-center gap-4"> <RangeCalendar aria-label="行程日期" isDateUnavailable={isDateUnavailable} minValue={now}> <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> <Description className="text-center">选择开始日期后，仅前后 7 天内的日期可选</Description> </div> ); } ``` ### 月份周数 将 `weeksInMonth` 设为固定值（例如 `6`），在月份切换时保持网格高度稳定。 ```tsx "use client"; import {Description, RangeCalendar} from "@heroui/react"; export function WeeksInMonth() { return ( <div className="flex flex-col items-center gap-4"> <RangeCalendar aria-label="行程日期" weeksInMonth={6}> <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> <Description className="text-center">每月固定显示 6 周，切换月份时避免布局跳动</Description> </div> ); } ``` ### 周视图 设置 `visibleDuration={{ weeks: n }}` 一次显示一个或多个周。导航按可见周范围前进。显示多周时，使用 `pageBehavior="single"` 每次移动一周。 ```tsx "use client"; import {Label, ListBox, RangeCalendar, Select} from "@heroui/react"; import {useState} from "react"; const weekOptions = [ {id: "1", name: "1 周"}, {id: "2", name: "2 周"}, {id: "3", name: "3 周"}, {id: "4", name: "4 周"}, {id: "5", name: "5 周"}, {id: "6", name: "6 周"}, {id: "8", name: "8 周"}, ] as const; export function WeekView() { const [weeks, setWeeks] = useState(1); return ( <div className="flex flex-col items-center gap-6"> <Select className="w-40" value={String(weeks)} onChange={(value) => value && setWeeks(Number(value))} > <Label>可见周数</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {weekOptions.map((option) => ( <ListBox.Item key={option.id} id={option.id} textValue={option.name}> {option.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> <RangeCalendar key={weeks} aria-label="行程日期" visibleDuration={{weeks}}> <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> </div> ); } ``` ### 日视图 设置 `visibleDuration={{ days: n }}` 显示连续日期的滚动窗口。导航按可见日范围前进。显示多天时，使用 `pageBehavior="single"` 每次移动一天。 ```tsx "use client"; import {Label, ListBox, RangeCalendar, Select} from "@heroui/react"; import {useState} from "react"; const dayOptions = [ {id: "1", name: "1 天"}, {id: "5", name: "5 天"}, {id: "7", name: "7 天"}, {id: "8", name: "8 天"}, {id: "10", name: "10 天"}, {id: "14", name: "14 天"}, {id: "21", name: "21 天"}, ] as const; export function DayView() { const [days, setDays] = useState(5); return ( <div className="flex flex-col items-center gap-6"> <Select className="w-40" value={String(days)} onChange={(value) => value && setDays(Number(value))} > <Label>可见天数</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {dayOptions.map((option) => ( <ListBox.Item key={option.id} id={option.id} textValue={option.name}> {option.name} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> <RangeCalendar key={days} aria-label="行程日期" visibleDuration={{days}}> <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> </div> ); } ``` ### 非连续范围 启用 `allowsNonContiguousRanges` 以允许跨越不可用日期进行选择。 ```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 ( <div className="flex flex-col items-center gap-4"> <RangeCalendar allowsNonContiguousRanges aria-label="行程日期" defaultValue={{end: now.add({days: 9}), start: now.add({days: 1})}} firstDayOfWeek="mon" isDateUnavailable={isDateUnavailable} > <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> <Description className="text-center">允许跨不可选日期选择非连续区间</Description> </div> ); } ``` ### 只读 ```tsx "use client"; import {Description, RangeCalendar} from "@heroui/react"; import {getLocalTimeZone, today} from "@internationalized/date"; export function ReadOnly() { return ( <div className="flex flex-col items-center gap-4"> <RangeCalendar isReadOnly aria-label="行程日期" defaultValue={{ end: today(getLocalTimeZone()).add({days: 4}), start: today(getLocalTimeZone()), }} > <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> <Description className="text-center">区间日历为只读</Description> </div> ); } ``` ### 无效状态 ```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<DateRange>({ end: now.add({days: 14}), start: now.add({days: 6}), }); const isInvalid = value.end.compare(value.start) > 7; return ( <div className="flex flex-col items-center gap-4"> <RangeCalendar aria-label="行程日期" firstDayOfWeek="mon" isInvalid={isInvalid} value={value} onChange={setValue} > <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> {isInvalid ? ( <p className="text-sm text-danger">最长入住时间为 1 周</p> ) : ( <Description className="text-center">请选择最多 7 天的入住区间</Description> )} </div> ); } ``` ### 聚焦值 ```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<DateValue>(parseDate("2025-06-15")); return ( <div className="flex flex-col items-center gap-4"> <RangeCalendar aria-label="行程日期" firstDayOfWeek="mon" focusedValue={focusedDate} onFocusChange={setFocusedDate} > <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> <Description className="text-center">聚焦： {focusedDate.toString()}</Description> <div className="flex flex-wrap justify-center gap-2"> <Button size="sm" variant="secondary" onPress={() => setFocusedDate(parseDate("2025-01-01"))} > 跳转到一月 </Button> <Button size="sm" variant="secondary" onPress={() => setFocusedDate(parseDate("2025-06-15"))} > 跳转到六月 </Button> <Button size="sm" variant="secondary" onPress={() => setFocusedDate(parseDate("2025-12-25"))} > 跳转到圣诞节 </Button> </div> </div> ); } ``` ### 单元格标记 可自定义 `RangeCalendar.Cell` 的子内容，并使用 `RangeCalendar.CellIndicator` 展示事件等元数据。 ```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 ( <RangeCalendar aria-label="行程日期"> <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => ( <RangeCalendar.Cell date={date}> {({formattedDate}) => ( <> {formattedDate} {(isToday(date, getLocalTimeZone()) || datesWithEvents.includes(date.day)) && ( <RangeCalendar.CellIndicator /> )} </> )} </RangeCalendar.Cell> )} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> ); } ``` ### 典型场景 ```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<DateRange | null>(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 ( <div className="flex flex-col items-center gap-4"> <RangeCalendar aria-label="预订区间" isDateUnavailable={isDateUnavailable} minValue={today(getLocalTimeZone())} value={selectedRange} onChange={setSelectedRange} > <RangeCalendar.Header> <RangeCalendar.Heading /> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => ( <RangeCalendar.Cell date={date}> {({formattedDate, isUnavailable}) => ( <> {formattedDate} {!isUnavailable && !isWeekend(date, locale) && blockedDates.includes(date.day) && <RangeCalendar.CellIndicator />} </> )} </RangeCalendar.Cell> )} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> <div className="flex flex-col gap-2 text-center"> <div className="flex items-center justify-center gap-4 text-xs text-muted"> <span className="flex items-center gap-1"> <span className="size-2 rounded-full bg-muted" /> 不可订日期 </span> <span className="flex items-center gap-1"> <span className="size-2 rounded-full bg-default" /> 周末/不可用 </span> </div> {selectedRange ? ( <Button size="sm" variant="primary"> 预订 {selectedRange.start.toString()} → {selectedRange.end.toString()} </Button> ) : null} </div> </div> ); } ``` ### 多月份展示 结合 `visibleDuration` 与 `offset` 渲染多个网格，适用于预订与规划场景。 ```tsx "use client"; import {RangeCalendar} from "@heroui/react"; export function MultipleMonths() { return ( <RangeCalendar aria-label="行程日期" className="@container-normal w-full max-w-none overflow-x-auto" visibleDuration={{months: 2}} > <div className="mx-auto flex w-max gap-8"> <div className="w-64"> <RangeCalendar.Header> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.Heading className="flex-none" /> <div className="size-6" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </div> <div className="w-64"> <RangeCalendar.Header> <div className="size-6" /> <RangeCalendar.Heading className="flex-none" offset={{months: 1}} /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid offset={{months: 1}}> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </div> </div> </RangeCalendar> ); } ``` ### 国际化日历 默认情况下，RangeCalendar 使用用户 locale 的历法系统显示日期。可用 `I18nProvider` 包裹组件，并设置 [Unicode 历法 locale 扩展](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/Locale/calendar#adding_a_calendar_in_the_locale_string) 覆盖。 以下示例展示印度历法系统： ```tsx "use client"; import {RangeCalendar} from "@heroui/react"; import {I18nProvider} from "react-aria-components"; export function InternationalCalendar() { return ( <I18nProvider locale="hi-IN-u-ca-indian"> <RangeCalendar aria-label="行程日期"> <RangeCalendar.Header> <RangeCalendar.YearPickerTrigger> <RangeCalendar.YearPickerTriggerHeading /> <RangeCalendar.YearPickerTriggerIndicator /> </RangeCalendar.YearPickerTrigger> <RangeCalendar.NavButton slot="previous" /> <RangeCalendar.NavButton slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> <RangeCalendar.YearPickerGrid> <RangeCalendar.YearPickerGridBody> {({year}) => <RangeCalendar.YearPickerCell year={year} />} </RangeCalendar.YearPickerGridBody> </RangeCalendar.YearPickerGrid> </RangeCalendar> </I18nProvider> ); } ``` **注意：** 无论显示 locale 如何，`onChange` 事件始终返回与 `value` 或 `defaultValue` 相同历法系统的日期（未提供 value 时为公历）。 ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {RangeCalendar} from "@heroui/react"; import {parseDate} from "@internationalized/date"; const cellClassName = [ "rounded-md", "**:data-[slot=range-calendar-cell-button]:rounded-md", "data-[outside-month=true]:text-muted data-[outside-month=true]:opacity-50", "data-[hovered=true]:not-data-[selected=true]:**:data-[slot=range-calendar-cell-button]:bg-default", "data-[today=true]:**:data-[slot=range-calendar-cell-button]:bg-success-soft", "data-[today=true]:**:data-[slot=range-calendar-cell-button]:text-success-soft-foreground", "data-[today=true]:data-[hovered=true]:not-data-[selected=true]:**:data-[slot=range-calendar-cell-button]:bg-success-soft-hover", "data-[selected=true]:rounded-none data-[selected=true]:bg-success-soft", "data-[outside-month=true]:data-[selected=true]:bg-default/20", "data-[selection-start=true]:rounded-tl-md data-[selection-start=true]:rounded-bl-md", "data-[selection-end=true]:rounded-tr-md data-[selection-end=true]:rounded-br-md", "data-[selection-start=true]:**:data-[slot=range-calendar-cell-button]:bg-success", "data-[selection-start=true]:**:data-[slot=range-calendar-cell-button]:text-success-foreground", "data-[selection-start=true]:data-[pressed=true]:**:data-[slot=range-calendar-cell-button]:bg-success-hover", "data-[selection-end=true]:**:data-[slot=range-calendar-cell-button]:bg-success", "data-[selection-end=true]:**:data-[slot=range-calendar-cell-button]:text-success-foreground", "data-[selection-end=true]:data-[pressed=true]:**:data-[slot=range-calendar-cell-button]:bg-success-hover", ].join(" "); export function CustomStyles() { return ( <RangeCalendar aria-label="酒店入住" className="w-63 rounded-xl border border-border/80 bg-surface p-3 shadow-sm ring-1 ring-success/10" defaultValue={{end: parseDate("2025-02-14"), start: parseDate("2025-02-08")}} firstDayOfWeek="mon" > <RangeCalendar.Header className="px-0.5 pb-4"> <RangeCalendar.Heading className="text-sm font-medium text-foreground" /> <RangeCalendar.NavButton className="rounded-md text-success hover:bg-success-soft active:scale-95" slot="previous" /> <RangeCalendar.NavButton className="rounded-md text-success hover:bg-success-soft active:scale-95" slot="next" /> </RangeCalendar.Header> <RangeCalendar.Grid> <RangeCalendar.GridHeader> {(day) => ( <RangeCalendar.HeaderCell className="pb-2 text-xs font-medium text-muted"> {day} </RangeCalendar.HeaderCell> )} </RangeCalendar.GridHeader> <RangeCalendar.GridBody> {(date) => <RangeCalendar.Cell className={cellClassName} date={date} />} </RangeCalendar.GridBody> </RangeCalendar.Grid> </RangeCalendar> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-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; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 RangeCalendar 在 `packages/styles/components/range-calendar.css` 与 `packages/styles/components/calendar-year-picker.css` 中使用以下类： * `.range-calendar` - 根容器。 * `.range-calendar__header` - 含导航按钮与标题的头部行。 * `.range-calendar__heading` - 当前月份标签。 * `.range-calendar__nav-button` - 上一月/下一月导航控件。 * `.range-calendar__grid` - 主体日期网格。 * `.range-calendar__grid-header` - 星期标题行外层。 * `.range-calendar__grid-body` - 日期行外层。 * `.range-calendar__header-cell` - 星期标题单元格。 * `.range-calendar__cell` - 可交互日期单元格外层。 * `.range-calendar__cell-button` - 单元格内的可交互日期按钮。 * `.range-calendar__cell-indicator` - 日期单元格内的圆点指示器。 * `.calendar-year-picker__trigger` - 年份选择器切换按钮。 * `.calendar-year-picker__trigger-heading` - 年份选择触发器内的标题文案。 * `.calendar-year-picker__trigger-indicator` - 年份选择触发器内的指示图标。 * `.calendar-year-picker__year-grid` - 可选年份的覆盖网格。 * `.calendar-year-picker__year-cell` - 单个年份选项。 ### 交互状态 RangeCalendar 同时支持伪类与 React Aria 的 data 属性： * **已选中**：`[data-selected="true"]` * **范围起点**：`[data-selection-start="true"]` * **范围终点**：`[data-selection-end="true"]` * **范围内**：`[data-selection-in-range="true"]` * **今天**：`[data-today="true"]` * **不可用**：`[data-unavailable="true"]` * **跨月**：`[data-outside-month="true"]` * **悬停**：`:hover` 或 `[data-hovered="true"]` * **按下**：`:active` 或 `[data-pressed="true"]` * **焦点可见**：`:focus-visible` 或 `[data-focus-visible="true"]` * **禁用**：`:disabled` 或 `[data-disabled="true"]` ## API 参考 ### RangeCalendar RangeCalendar 继承 React Aria [RangeCalendar](https://react-spectrum.adobe.com/react-aria/RangeCalendar.html) 的全部 props。 | Prop | 类型 | 默认值 | 描述 | | --------------------------- | ---------------------------------------------------------------- | ------------------ | ---------------------------------------------------------------------- | | `value` | `RangeValue<DateValue> \| null` | - | 受控的选中范围。 | | `defaultValue` | `RangeValue<DateValue> \| null` | - | 初始选中范围（非受控）。 | | `onChange` | `(value: RangeValue<DateValue>) => void` | - | 选中变化时调用。 | | `focusedValue` | `DateValue` | - | 受控的焦点日期。 | | `onFocusChange` | `(value: DateValue) => void` | - | 焦点移动到其它日期时调用。 | | `minValue` | `DateValue` | 历法感知的 `1900-01-01` | 可选的最早日期。 | | `maxValue` | `DateValue` | 历法感知的 `2099-12-31` | 可选的最晚日期。 | | `weeksInMonth` | `number` | - | 一个月的周数。该值会覆盖区域设置的默认值。 | | `isDateUnavailable` | `(date: DateValue, anchorDate: CalendarDate \| null) => boolean` | - | 将日期标记为不可用。`anchorDate` 为当前范围选择中的首个日期。 | | `firstDayOfWeek` | `'sun' \| 'mon' \| 'tue' \| 'wed' \| 'thu' \| 'fri' \| 'sat'` | - | 覆盖区域设置的一周起始日。 | | `pageBehavior` | `'visible' \| 'single'` | `'visible'` | 翻页按可见范围或单步前进。 | | `selectionAlignment` | `'start' \| 'center' \| 'end'` | `'center'` | 初始渲染时按选中项对齐可见范围。 | | `allowsNonContiguousRanges` | `boolean` | `false` | 允许范围跨越不可用日期。 | | `isDisabled` | `boolean` | `false` | 禁用交互与选择。 | | `isReadOnly` | `boolean` | `false` | 内容只读，不可更改选中。 | | `isInvalid` | `boolean` | `false` | 标记为无效以配合校验样式。 | | `visibleDuration` | `{months?: number; weeks?: number; days?: number}` | `{months: 1}` | 可见时间范围。使用 `{ months: n }` 为月视图，`{ weeks: n }` 为周视图，`{ days: n }` 为日视图。 | | `defaultYearPickerOpen` | `boolean` | `false` | 内置年份选择器的初始展开状态。 | | `isYearPickerOpen` | `boolean` | - | 受控的年份选择器展开状态。 | | `onYearPickerOpenChange` | `(isOpen: boolean) => void` | - | 年份选择器展开状态变化时调用。 | ### 组合部件 | 组件 | 描述 | | ------------------------------------------ | --------------------------------------------------- | | `RangeCalendar.Header` | 导航与标题的头部容器。 | | `RangeCalendar.Heading` | 可见范围的格式化标题。支持 `offset`（多月份布局）与 `format`（月/年/日格式选项）。 | | `RangeCalendar.NavButton` | 上一页/下一页导航（`slot="previous"` 或 `slot="next"`）。 | | `RangeCalendar.Grid` | 单个月的日期网格（多月份布局支持 `offset`）。 | | `RangeCalendar.GridHeader` | 星期标题容器。 | | `RangeCalendar.GridBody` | 日期单元格主体容器。 | | `RangeCalendar.HeaderCell` | 星期标签单元格。 | | `RangeCalendar.Cell` | 单个日期单元格。 | | `RangeCalendar.CellIndicator` | 用于自定义元数据的可选指示元素。 | | `RangeCalendar.YearPickerTrigger` | 切换年份选择模式的触发器。 | | `RangeCalendar.YearPickerTriggerHeading` | 年份选择触发器内的本地化标题内容。 | | `RangeCalendar.YearPickerTriggerIndicator` | 年份选择触发器内的切换图标。 | | `RangeCalendar.YearPickerGrid` | 年份选择覆盖网格容器。 | | `RangeCalendar.YearPickerGridBody` | 年份网格单元格的 body 渲染器。 | | `RangeCalendar.YearPickerCell` | 单个年份选项单元格。 | ### 年份选择器子组件 年份选择器子组件继承 React Aria [`useCalendarHeading`](https://react-aria.adobe.com/useCalendar#usecalendarheading) 与 [`useCalendarYearPicker`](https://react-aria.adobe.com/useCalendar#usecalendaryearpicker) 的格式化属性。 | 组件 | 属性 | 类型 | 默认值 | 描述 | | ---------------------------------------- | -------------- | ---------------------- | ------------------- | ---------------------------------------------------------- | | `RangeCalendar.YearPickerTriggerHeading` | `format` | `DateFormatterOptions` | - | 自定义月/年标题（如 `{month: 'short'}`）。 | | `RangeCalendar.YearPickerTriggerHeading` | `offset` | `{months?: number}` | - | 相对聚焦日期偏移标题（多月布局）。 | | `RangeCalendar.YearPickerGrid` | `format` | `DateFormatterOptions` | `{year: 'numeric'}` | 自定义年份单元格标签（纪元、历法系统等）。 | | `RangeCalendar.YearPickerGrid` | `visibleYears` | `number` | min–max 跨度或 `20` | 滑动窗口中显示的年份数量。当同时设置 `minValue` 与 `maxValue` 时，默认为二者之间的完整范围。 | ### RangeCalendar.Cell Render 当 `RangeCalendar.Cell` 的 `children` 为函数时，可使用 React Aria 的渲染参数： | Prop | 类型 | 描述 | | ------------------ | --------- | ------------ | | `formattedDate` | `string` | 单元格日期的本地化文案。 | | `isSelected` | `boolean` | 该日期是否已选中。 | | `isSelectionStart` | `boolean` | 是否为选中范围的起点。 | | `isSelectionEnd` | `boolean` | 是否为选中范围的终点。 | | `isUnavailable` | `boolean` | 该日期是否不可用。 | | `isDisabled` | `boolean` | 单元格是否禁用。 | | `isOutsideMonth` | `boolean` | 是否属于相邻月份。 | 支持的历法系统及其标识符完整列表见： * [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/) — 各日期组件共用的日期类型（`CalendarDate`、`CalendarDateTime`、`ZonedDateTime`）与工具函数 * [`I18nProvider`](https://react-aria.adobe.com/I18nProvider) — 为子树覆盖语言环境 * [`useLocale`](https://react-aria.adobe.com/useLocale) — 读取当前语言环境与书写方向 ## 相关组件 ## 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 </page> <page url="/cn/docs/react/components/time-field"> # TimeField 时间字段 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/time-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(date-and-time)/time-field.mdx > 基于 React Aria TimeField 的时间输入字段，包含标签、说明与校验。 ## 用法 ```tsx import { TimeField } from '@heroui/react'; ``` ```tsx "use client"; import {Label, TimeField} from "@heroui/react"; export function Basic() { return ( <TimeField className="w-[256px]" name="time"> <Label>时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> </TimeField> ); } ``` ## 组件结构 ```tsx import {TimeField, Label, Description, FieldError} from '@heroui/react'; export default () => ( <TimeField> <Label /> <TimeField.Group> <TimeField.Input> {(segment) => <TimeField.Segment segment={segment} />} </TimeField.Input> </TimeField.Group> <Description /> <FieldError /> </TimeField> ) ``` > **TimeField** 将标签、时间输入、说明与错误信息组合为单个无障碍组件。 ## 示例 ### 带图标 添加前缀或后缀图标以增强时间字段。 ```tsx "use client"; import {Clock} from "@gravity-ui/icons"; import {Label, TimeField} from "@heroui/react"; export function WithPrefixIcon() { return ( <TimeField className="w-[256px]" name="time"> <Label>时间</Label> <TimeField.Group> <TimeField.Prefix> <Clock className="size-4 text-muted" /> </TimeField.Prefix> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> </TimeField> ); } ``` ```tsx "use client"; import {Clock} from "@gravity-ui/icons"; import {Label, TimeField} from "@heroui/react"; export function WithSuffixIcon() { return ( <TimeField className="w-[256px]" name="time"> <Label>时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> <TimeField.Suffix> <Clock className="size-4 text-muted" /> </TimeField.Suffix> </TimeField.Group> </TimeField> ); } ``` ```tsx "use client"; import {ChevronDown, Clock} from "@gravity-ui/icons"; import {Description, Label, TimeField} from "@heroui/react"; export function WithPrefixAndSuffix() { return ( <TimeField className="w-[256px]" name="time"> <Label>时间</Label> <TimeField.Group> <TimeField.Prefix> <Clock className="size-4 text-muted" /> </TimeField.Prefix> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> <TimeField.Suffix> <ChevronDown className="size-4 text-muted" /> </TimeField.Suffix> </TimeField.Group> <Description>输入时间</Description> </TimeField> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请在 `TimeField.Group` 上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。 ```tsx "use client"; import {Clock} from "@gravity-ui/icons"; import {Description, Label, Surface, TimeField} from "@heroui/react"; export function OnSurface() { return ( <Surface className="flex w-full max-w-sm flex-col gap-4 rounded-3xl p-6"> <TimeField className="w-full" name="time"> <Label>时间</Label> <TimeField.Group variant="secondary"> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> <Description>输入时间</Description> </TimeField> <TimeField className="w-full" name="time-2"> <Label>预约时间</Label> <TimeField.Group variant="secondary"> <TimeField.Prefix> <Clock className="size-4 text-muted" /> </TimeField.Prefix> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> <Description>输入预约时间</Description> </TimeField> </Surface> ); } ``` ### 带描述 ```tsx "use client"; import {Description, Label, TimeField} from "@heroui/react"; export function WithDescription() { return ( <div className="flex flex-col gap-4"> <TimeField className="w-[256px]" name="time"> <Label>开始时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> <Description>输入开始时间</Description> </TimeField> <TimeField className="w-[256px]" name="end-time"> <Label>结束时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> <Description>输入结束时间</Description> </TimeField> </div> ); } ``` ### 必填字段 ```tsx "use client"; import {Description, Label, TimeField} from "@heroui/react"; export function Required() { return ( <div className="flex flex-col gap-4"> <TimeField isRequired className="w-[256px]" name="time"> <Label>时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> </TimeField> <TimeField isRequired className="w-[256px]" name="appointment-time"> <Label>预约时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> <Description>必填项</Description> </TimeField> </div> ); } ``` ### 禁用 ```tsx "use client"; import {Description, Label, TimeField} from "@heroui/react"; import {Time, getLocalTimeZone, now} from "@internationalized/date"; export function Disabled() { const currentTime = now(getLocalTimeZone()); const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second); return ( <div className="flex flex-col gap-4"> <TimeField isDisabled className="w-[256px]" name="time" value={timeValue}> <Label>时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> <Description>此时间字段已禁用</Description> </TimeField> <TimeField isDisabled className="w-[256px]" name="time-empty"> <Label>时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> <Description>此时间字段已禁用</Description> </TimeField> </div> ); } ``` ### 宽度充满 ```tsx "use client"; import {ChevronDown, Clock} from "@gravity-ui/icons"; import {Label, TimeField} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <TimeField fullWidth name="time"> <Label>时间</Label> <TimeField.Group fullWidth> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> </TimeField> <TimeField fullWidth name="time-icons"> <Label>时间</Label> <TimeField.Group fullWidth> <TimeField.Prefix> <Clock className="size-4 text-muted" /> </TimeField.Prefix> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> <TimeField.Suffix> <ChevronDown className="size-4 text-muted" /> </TimeField.Suffix> </TimeField.Group> </TimeField> </div> ); } ``` ### 表单校验 将 `isInvalid` 与 `FieldError` 配合使用，以展示校验消息。 ```tsx "use client"; import {FieldError, Label, TimeField} from "@heroui/react"; export function Invalid() { return ( <div className="flex flex-col gap-4"> <TimeField isInvalid isRequired className="w-[256px]" name="time"> <Label>时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> <FieldError>请输入有效时间</FieldError> </TimeField> <TimeField isInvalid className="w-[256px]" name="invalid-time"> <Label>时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> <FieldError>时间须在工作时间内</FieldError> </TimeField> </div> ); } ``` ### 受控组件 控制 value 以与其他组件或状态管理同步。 ```tsx "use client"; import type {TimeValue} from "@heroui/react"; import {Button, Description, Label, TimeField} from "@heroui/react"; import {Time, getLocalTimeZone, now} from "@internationalized/date"; import {useState} from "react"; export function Controlled() { const [value, setValue] = useState<TimeValue | null>(null); return ( <div className="flex flex-col gap-4"> <TimeField className="w-[256px]" name="time" value={value} onChange={setValue}> <Label>时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> <Description>当前值：{value ? value.toString() : "（空）"}</Description> </TimeField> <div className="flex gap-2"> <Button variant="tertiary" onPress={() => { const currentTime = now(getLocalTimeZone()); setValue(new Time(currentTime.hour, currentTime.minute, currentTime.second)); }} > 设为当前时间 </Button> <Button variant="tertiary" onPress={() => setValue(null)}> 清空 </Button> </div> </div> ); } ``` ### 表单示例 包含校验与提交处理的完整表单示例。 ```tsx "use client"; import type {Time} from "@internationalized/date"; import {Clock} from "@gravity-ui/icons"; import {Button, Description, FieldError, Form, Label, TimeField} from "@heroui/react"; import {parseTime} from "@internationalized/date"; import {useState} from "react"; export function FormExample() { const [value, setValue] = useState<Time | null>(null); const [isSubmitting, setIsSubmitting] = useState(false); const minTime = parseTime("09:00"); const maxTime = parseTime("17:00"); const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0); const handleSubmit = (e: React.SyntheticEvent<HTMLFormElement>) => { e.preventDefault(); if (!value || isInvalid) { return; } setIsSubmitting(true); // Simulate API call setTimeout(() => { console.log("Time submitted:", {time: value}); setValue(null); setIsSubmitting(false); }, 1500); }; return ( <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}> <TimeField isRequired className="w-full" isInvalid={isInvalid} maxValue={maxTime} minValue={minTime} name="time" value={value} onChange={setValue} > <Label>预约时间</Label> <TimeField.Group> <TimeField.Prefix> <Clock className="size-4 text-muted" /> </TimeField.Prefix> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> {isInvalid ? ( <FieldError>时间须在上午 9:00 至下午 5:00 之间</FieldError> ) : ( <Description>输入上午 9:00 至下午 5:00 之间的时间</Description> )} </TimeField> <Button className="w-full" isDisabled={!value || isInvalid} isPending={isSubmitting} type="submit" variant="primary" > {isSubmitting ? "提交中…" : "提交"} </Button> </Form> ); } ``` ### 带校验 TimeField 支持通过 `minValue`、`maxValue` 及自定义校验逻辑进行验证。 ```tsx "use client"; import type {Time} from "@internationalized/date"; import {Description, FieldError, Label, TimeField} from "@heroui/react"; import {parseTime} from "@internationalized/date"; import {useState} from "react"; export function WithValidation() { const [value, setValue] = useState<Time | null>(null); const minTime = parseTime("09:00"); const maxTime = parseTime("17:00"); const isInvalid = value !== null && (value.compare(minTime) < 0 || value.compare(maxTime) > 0); return ( <div className="flex flex-col gap-4"> <TimeField isRequired className="w-[256px]" isInvalid={isInvalid} maxValue={maxTime} minValue={minTime} name="time" value={value} onChange={setValue} > <Label>时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> {isInvalid ? ( <FieldError>时间须在上午 9:00 至下午 5:00 之间</FieldError> ) : ( <Description>输入上午 9:00 至下午 5:00 之间的时间</Description> )} </TimeField> </div> ); } ``` ### 渲染函数 ```tsx "use client"; import {Label, TimeField} from "@heroui/react"; export function RenderFunction() { return ( <TimeField className="w-[256px]" name="time" render={(props) => <div {...props} data-custom="foo" />} > <Label>时间</Label> <TimeField.Group> <TimeField.Input>{(segment) => <TimeField.Segment segment={segment} />}</TimeField.Input> </TimeField.Group> </TimeField> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {Description, Label, TimeField} from "@heroui/react"; export function CustomStyles() { return ( <TimeField className="w-full max-w-48 gap-1.5" name="reminder"> <Label className="font-medium text-foreground">提醒时间</Label> <Description>每日签到通知。</Description> <TimeField.Group className="rounded-xl border border-border/80 bg-surface px-2 py-1 shadow-sm ring-1 ring-accent/5 focus-within:border-accent/25 focus-within:ring-2 focus-within:ring-accent/15"> <TimeField.Input> {(segment) => <TimeField.Segment className="text-foreground" segment={segment} />} </TimeField.Input> </TimeField.Group> </TimeField> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```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; } } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 * `.time-field` – 轻量样式的根容器（`flex flex-col gap-1`） > **说明：** 子组件（[Label](/docs/react/components/label)、[Description](/docs/react/components/description)、[FieldError](/docs/react/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参阅对应文档。`TimeField.Group` 的样式见下文 API 参考。 ### 交互状态 TimeField 会根据状态自动设置以下 data 属性： * **无效**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` – 无效时自动隐藏 description 插槽 * **必填**：`[data-required="true"]` – 当 `isRequired` 为 true 时添加 * **禁用**：`[data-disabled="true"]` – 当 `isDisabled` 为 true 时添加 * **焦点在内**：`[data-focus-within="true"]` – 任一子输入聚焦时添加 ## API 参考 ### TimeField TimeField 继承 React Aria [TimeField](https://react-aria.adobe.com/TimeField) 的全部 props。 #### Base Props | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------ | ------- | ---------------------------------- | | `children` | `React.ReactNode \| (values: TimeFieldRenderProps) => React.ReactNode` | - | 子组件（Label、TimeField.Group 等）或渲染函数。 | | `className` | `string \| (values: TimeFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 | | `style` | `React.CSSProperties \| (values: TimeFieldRenderProps) => React.CSSProperties` | - | 内联样式，支持渲染 prop。 | | `fullWidth` | `boolean` | `false` | 时间字段是否占满容器宽度。 | | `id` | `string` | - | 元素的唯一 id。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TimeFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | #### Value Props | Prop | 类型 | 默认值 | 描述 | | ------------------ | ------------------------------------ | --- | ----------------------------------------------------------------------------------------------- | | `value` | `TimeValue \| null` | - | 当前值（受控）。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 | | `defaultValue` | `TimeValue \| null` | - | 默认值（非受控）。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 | | `onChange` | `(value: TimeValue \| null) => void` | - | 值变化时触发的事件处理函数。 | | `placeholderValue` | `TimeValue \| null` | - | 影响占位符格式的占位时间；默认随小时制为 12:00 AM 或 00:00。 | #### Validation Props | Prop | 类型 | 默认值 | 描述 | | -------------------- | -------------------------------------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------ | | `isRequired` | `boolean` | `false` | 是否在提交表单前要求用户输入。 | | `isInvalid` | `boolean` | - | 值是否无效。 | | `minValue` | `TimeValue \| null` | - | 用户可选择最早时间。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 | | `maxValue` | `TimeValue \| null` | - | 用户可选择最晚时间。类型见 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/)。 | | `validate` | `(value: TimeValue) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验还是 ARIA 属性。 | #### Format Props | Prop | 类型 | 默认值 | 描述 | | ------------------------- | -------------------------------- | ---------- | ---------------------------- | | `granularity` | `'hour' \| 'minute' \| 'second'` | `'minute'` | 时间选择器显示的最小单位。 | | `hourCycle` | `12 \| 24` | - | 以 12 或 24 小时制显示时间；默认由语言环境决定。 | | `hideTimeZone` | `boolean` | `false` | 是否隐藏时区缩写。 | | `shouldForceLeadingZeros` | `boolean` | - | 是否始终为小时字段显示前导零；默认由语言环境决定。 | #### State Props | Prop | 类型 | 默认值 | 描述 | | ------------ | --------- | --- | ----------- | | `isDisabled` | `boolean` | - | 是否禁用输入。 | | `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 | #### Form Props | Prop | 类型 | 默认值 | 描述 | | ----------- | --------- | --- | ----------------------------------------- | | `name` | `string` | - | 输入元素的 name，用于 HTML 表单提交；以 ISO 8601 字符串提交。 | | `autoFocus` | `boolean` | - | 是否在渲染后自动聚焦该元素。 | #### Accessibility Props | Prop | 类型 | 默认值 | 描述 | | ------------------ | -------- | --- | ------------- | | `aria-label` | `string` | - | 无可见标签时的无障碍标签。 | | `aria-labelledby` | `string` | - | 标注该字段的元素 id。 | | `aria-describedby` | `string` | - | 描述该字段的元素 id。 | | `aria-details` | `string` | - | 包含额外详情的元素 id。 | ### 组合组件 TimeField 与以下独立组件配合使用，请分别导入并直接使用： * **Label** – 来自 `@heroui/react` 的字段标签 * **TimeField.Group** – 时间输入分组（详见下文） * **TimeField.Input** – 来自 `@heroui/react` 的分段位编辑输入 * **TimeField.Segment** – 单个时间段位（时、分、秒等） * **TimeField.Prefix** / **TimeField.Suffix** – 输入组的前缀与后缀插槽 * **Description** – 来自 `@heroui/react` 的辅助说明 * **FieldError** – 来自 `@heroui/react` 的校验错误信息 这些组件各自有独立的 props API。在 TimeField 中直接组合使用： ```tsx import {parseTime} from '@internationalized/date'; import {TimeField, Label, Description, FieldError} from '@heroui/react'; <TimeField isRequired isInvalid={hasError} minValue={parseTime('09:00')} maxValue={parseTime('17:00')} value={time} onChange={setTime} > <Label>Appointment Time</Label> <TimeField.Group> <TimeField.Input> {(segment) => <TimeField.Segment segment={segment} />} </TimeField.Input> </TimeField.Group> <Description>Select a time between 9:00 AM and 5:00 PM.</Description> <FieldError>Please select a valid time.</FieldError> </TimeField> ``` ### TimeValue 类型 TimeField 使用 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) 中的类型： * `Time` – 仅时间（时、分、秒） * `CalendarDateTime` – 含日期与时间、不含时区（TimeField 仅展示时间部分） * `ZonedDateTime` – 含日期、时间与时区（TimeField 仅展示时间部分） 示例： ```tsx import {parseTime, Time, getLocalTimeZone, now} from '@internationalized/date'; // Parse from string const time = parseTime('14:30'); // Create from current time const currentTime = now(getLocalTimeZone()); const timeValue = new Time(currentTime.hour, currentTime.minute, currentTime.second); // Use in TimeField <TimeField value={time} onChange={setTime}> {/* ... */} </TimeField> ``` > **说明：** TimeField 使用 [`@internationalized/date`](https://react-aria.adobe.com/internationalized/date/) 进行时间处理、解析与类型定义。更多类型与函数见 [Internationalized Date 文档](https://react-aria.adobe.com/internationalized/date/)。 ### TimeFieldRenderProps 对 `className`、`style` 或 `children` 使用渲染 prop 时，可使用以下值： | Prop | 类型 | 描述 | | ---------------- | --------- | ------------- | | `isDisabled` | `boolean` | 字段是否禁用。 | | `isInvalid` | `boolean` | 字段当前是否无效。 | | `isReadOnly` | `boolean` | 字段是否只读。 | | `isRequired` | `boolean` | 字段是否必填。 | | `isFocused` | `boolean` | 字段是否聚焦。 | | `isFocusWithin` | `boolean` | 是否有子元素聚焦。 | | `isFocusVisible` | `boolean` | 焦点是否可见（键盘导航）。 | ### TimeField.Group TimeField.Group 继承 React Aria `Group` 的全部 props，并额外支持： | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------- | ----------- | ---------------------------------------------------------- | | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 | ### TimeField.Input TimeField.Input 继承 React Aria `DateInput` 的全部 props，并额外支持： | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------- | ----------- | ------------------------------------------------------------- | | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 输入的视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调、无阴影，适合用于 Surface。 | `TimeField.Input` 接受渲染函数作为子节点，函数接收日期段位；每个段位表示时间的一部分（时、分、秒等）。 ### TimeField.Segment TimeField.Segment 继承 React Aria `DateSegment` 的全部 props： | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------- | --- | ------------------------------------------ | | `segment` | `DateSegment` | - | 来自 TimeField.Input 渲染函数的 `DateSegment` 对象。 | | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 | ### TimeField.Prefix TimeField.Prefix 接受标准 HTML `div` 属性： | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------------ | | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 前缀插槽中要显示的内容。 | ### TimeField.Suffix TimeField.Suffix 接受标准 HTML `div` 属性： | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------------ | | `className` | `string` | - | 与组件样式合并的 Tailwind CSS 类。 | | `children` | `ReactNode` | - | 后缀插槽中要显示的内容。 | ## TimeField.Group 样式 ### 全局 CSS 基础类作用于所有实例，可通过 `@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 类 * `.date-input-group` – 根容器样式 * `.date-input-group__input` – 输入包裹层样式 * `.date-input-group__segment` – 单个时间段位样式 * `.date-input-group__prefix` – 前缀元素样式 * `.date-input-group__suffix` – 后缀元素样式 ### TimeField.Group 交互状态 * **悬停**：`:hover` 或 `[data-hovered="true"]` * **焦点在内**：`[data-focus-within="true"]` 或 `:focus-within` * **无效**：`[data-invalid="true"]`（同时与 `aria-invalid` 同步） * **禁用**：`[data-disabled="true"]` 或 `[aria-disabled="true"]` * **段位聚焦**：段位上的 `:focus` 或 `[data-focused="true"]` * **段位占位符**：段位上的 `[data-placeholder="true"]` ## 相关组件 ## Related Components * **Label**: Accessible label for form controls * **FieldError**: Inline validation messages for form fields * **Description**: Helper text for form fields </page> <page url="/cn/docs/react/components/alert"> # Alert 警告 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/alert **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(feedback)/alert.mdx > 向用户展示重要消息与通知，并提供状态指示 ## 用法 ```tsx import { Alert } from '@heroui/react'; ``` ```tsx import {Alert, Button, CloseButton, Spinner} from "@heroui/react"; import React from "react"; export function Basic() { return ( <div className="grid w-full max-w-xl gap-4"> {/* 默认 — 一般信息 */} <Alert> <Alert.Indicator /> <Alert.Content> <Alert.Title>新功能已上线</Alert.Title> <Alert.Description> 查看我们的最新更新，包括深色模式支持与改进的无障碍体验。 </Alert.Description> </Alert.Content> </Alert> {/* 强调 — 重要信息含操作 */} <Alert status="accent"> <Alert.Indicator /> <Alert.Content> <Alert.Title>有可用更新</Alert.Title> <Alert.Description> 应用有新版本可用。请刷新页面以获取最新功能与问题修复。 </Alert.Description> <Button className="mt-2 sm:hidden" size="sm" variant="primary"> 刷新 </Button> </Alert.Content> <Button className="hidden sm:block" size="sm" variant="primary"> 刷新 </Button> </Alert> {/* 危险 — 错误与排查步骤 */} <Alert status="danger"> <Alert.Indicator /> <Alert.Content> <Alert.Title>无法连接到服务器</Alert.Title> <Alert.Description> 当前遇到连接问题，请尝试以下操作： <ul className="mt-2 list-inside list-disc space-y-1 text-sm"> <li>检查网络连接</li> <li>刷新页面</li> <li>清除浏览器缓存</li> </ul> </Alert.Description> <Button className="mt-2 sm:hidden" size="sm" variant="danger"> 重试 </Button> </Alert.Content> <Button className="hidden sm:block" size="sm" variant="danger"> 重试 </Button> </Alert> {/* 无描述 */} <Alert status="success"> <Alert.Indicator /> <Alert.Content> <Alert.Title>个人资料已更新</Alert.Title> </Alert.Content> <CloseButton /> </Alert> {/* 自定义指示器 — 加载中 */} <Alert status="accent"> <Alert.Indicator> <Spinner size="sm" /> </Alert.Indicator> <Alert.Content> <Alert.Title>正在处理你的请求</Alert.Title> <Alert.Description>正在同步你的数据，请稍候，这可能需要一点时间。</Alert.Description> </Alert.Content> </Alert> {/* 无关闭按钮 */} <Alert status="warning"> <Alert.Indicator /> <Alert.Content> <Alert.Title>计划维护</Alert.Title> <Alert.Description> 我们将于 UTC 时间 3 月 15 日（周日）凌晨 2:00 至上午 6:00 进行计划维护，期间服务将暂时不可用。 </Alert.Description> </Alert.Content> </Alert> </div> ); } ``` ## 组件结构 ```tsx import { Alert } from '@heroui/react'; export default () => ( <Alert> <Alert.Indicator /> <Alert.Content> <Alert.Title /> <Alert.Description /> </Alert.Content> </Alert> ) ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Alert, Button, CloseButton} from "@heroui/react"; export function CustomStyles() { return ( <div className="w-full max-w-xl"> <Alert className="relative overflow-hidden rounded-xl border border-warning/20 bg-linear-to-br from-warning/10 via-surface to-surface-secondary shadow-sm dark:border-warning/30 dark:from-warning/15 dark:via-surface dark:to-warning/5" status="warning" > <div aria-hidden="true" className="pointer-events-none absolute -top-8 -right-8 size-28 rounded-full bg-warning/15 blur-2xl dark:bg-warning/25" /> <Alert.Indicator className="relative text-warning" /> <Alert.Content className="relative"> <Alert.Title>支付方式即将过期</Alert.Title> <Alert.Description> 您的 Visa 卡（尾号 4242）将于 3 月 28 日过期。请更新账单信息，以免影响 Pro 订阅。 </Alert.Description> <Button className="mt-3 sm:hidden" size="sm" variant="tertiary"> 更新账单 </Button> </Alert.Content> <Button className="relative hidden shrink-0 sm:inline-flex" size="sm" variant="tertiary"> 更新账单 </Button> <CloseButton className="relative" /> </Alert> </div> ); } ``` ### 全局 CSS 要自定义 Alert 的组件类，可使用 `@layer components` 指令。 [了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Alert 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert.css)）： #### 基础类 \[!toc] * `.alert` - Alert 根容器 * `.alert__indicator` - 图标/指示器容器 * `.alert__content` - 包裹标题与说明的内容容器 * `.alert__title` - Alert 标题文本 * `.alert__description` - Alert 说明文本 #### 状态变体类 \[!toc] * `.alert--default` - 默认灰色状态 * `.alert--accent` - 强调蓝色状态 * `.alert--success` - 成功绿色状态 * `.alert--warning` - 警告黄/橙色状态 * `.alert--danger` - 危险红色状态 ### 交互状态 Alert 主要用于信息展示，基础组件本身通常没有交互状态；但它可以包含按钮或关闭按钮等交互元素。 ## API 参考 ### Alert | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------- | ----------- | ----------- | | `status` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Alert 的视觉状态 | | `className` | `string` | - | 附加的 CSS 类 | | `children` | `ReactNode` | - | Alert 内容 | ### Alert.Indicator | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ----------------- | | `className` | `string` | - | 附加的 CSS 类 | | `children` | `ReactNode` | - | 自定义指示图标（默认显示状态图标） | ### Alert.Content | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | --------------------------- | | `className` | `string` | - | 附加的 CSS 类 | | `children` | `ReactNode` | - | 内容（通常为 Title 与 Description） | ### Alert.Title | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ---------- | | `className` | `string` | - | 附加的 CSS 类 | | `children` | `ReactNode` | - | Alert 标题文本 | ### Alert.Description | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ---------- | | `className` | `string` | - | 附加的 CSS 类 | | `children` | `ReactNode` | - | Alert 说明文本 | ## 相关组件 ## Related Components * **CloseButton**: Button for dismissing overlays * **Button**: Allows a user to perform an action * **Spinner**: Loading indicator </page> <page url="/cn/docs/react/components/meter"> # Meter 计量条 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/meter **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(feedback)/meter.mdx > Meter 表示已知范围内的数量，或一个比例值。 ## 用法 ```tsx import { Meter, Label } from '@heroui/react'; ``` ```tsx import {Label, Meter} from "@heroui/react"; export function Basic() { return ( <Meter aria-label="存储空间" className="w-64" value={60}> <Label>存储空间</Label> <Meter.Output /> <Meter.Track> <Meter.Fill /> </Meter.Track> </Meter> ); } ``` ## 组件结构 ```tsx import { Meter, Label } from '@heroui/react'; export default () => ( <Meter value={60}> <Label>Storage</Label> <Meter.Output /> <Meter.Track> <Meter.Fill /> </Meter.Track> </Meter> ); ``` ## 示例 ### 尺寸 ```tsx import {Label, Meter} from "@heroui/react"; const SIZE_LABELS = { lg: "大", md: "中", sm: "小", } as const; export function Sizes() { return ( <div className="flex w-64 flex-col gap-6"> <Meter color="success" size="sm" value={40}> <Label>{SIZE_LABELS.sm}</Label> <Meter.Output /> <Meter.Track> <Meter.Fill /> </Meter.Track> </Meter> <Meter color="accent" size="md" value={60}> <Label>{SIZE_LABELS.md}</Label> <Meter.Output /> <Meter.Track> <Meter.Fill /> </Meter.Track> </Meter> <Meter color="warning" size="lg" value={80}> <Label>{SIZE_LABELS.lg}</Label> <Meter.Output /> <Meter.Track> <Meter.Fill /> </Meter.Track> </Meter> </div> ); } ``` ### 颜色 ```tsx import {Label, Meter} from "@heroui/react"; const colors = ["default", "accent", "success", "warning", "danger"] as const; const COLOR_LABELS: Record<(typeof colors)[number], string> = { accent: "强调", danger: "危险", default: "默认", success: "成功", warning: "警告", }; export function Colors() { return ( <div className="flex w-64 flex-col gap-6"> {colors.map((color) => ( <Meter key={color} color={color} value={50}> <Label>{COLOR_LABELS[color]}</Label> <Meter.Output /> <Meter.Track> <Meter.Fill /> </Meter.Track> </Meter> ))} </div> ); } ``` ### 无可见标签 无需可见标签时，使用 `aria-label` 提供无障碍标签。 ```tsx import {Meter} from "@heroui/react"; export function WithoutLabel() { return ( <Meter aria-label="存储空间用量" className="w-64" value={45}> <Meter.Track> <Meter.Fill /> </Meter.Track> </Meter> ); } ``` ### 自定义取值范围与格式 使用 `minValue`、`maxValue` 与 `formatOptions` 自定义取值范围与显示格式。 ```tsx import {Label, Meter} from "@heroui/react"; export function CustomValue() { return ( <Meter className="w-64" formatOptions={{currency: "USD", style: "currency"}} maxValue={1000} minValue={0} value={750} > <Label>收入</Label> <Meter.Output /> <Meter.Track> <Meter.Fill /> </Meter.Track> </Meter> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Label, Meter} from "@heroui/react"; export function CustomStyles() { return ( <Meter aria-label="已用存储空间" className="w-64" value={68}> <Label className="font-medium text-foreground">已用存储空间</Label> <Meter.Output className="text-muted tabular-nums" /> <Meter.Track className="rounded-full bg-default"> <Meter.Fill className="rounded-full bg-warning" /> </Meter.Track> </Meter> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .meter { @apply w-full gap-2; } .meter__track { @apply h-3 rounded-full; } .meter__fill { @apply rounded-full; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Meter 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/meter.css)）： #### 基础与元素类 \[!toc] * `.meter` — 基础容器（grid 布局） * `.meter__output` — 数值文本展示 * `.meter__track` — 轨道背景 * `.meter__fill` — 轨道已填充部分 #### 尺寸类 \[!toc] * `.meter--sm` — 小尺寸变体（更细的轨道） * `.meter--md` — 中等尺寸变体（默认） * `.meter--lg` — 大尺寸变体（更粗的轨道） #### 颜色类 \[!toc] * `.meter--default` — 默认颜色变体 * `.meter--accent` — 强调色变体 * `.meter--success` — 成功色变体 * `.meter--warning` — 警告色变体 * `.meter--danger` — 危险色变体 ## API 参考 ### Meter 继承自 [React Aria Meter](https://react-spectrum.adobe.com/react-aria/Meter.html)。 | Prop | 类型 | 默认值 | 描述 | | --------------- | ------------------------------------------------------------- | -------------------- | ---------- | | `value` | `number` | `0` | 当前值 | | `minValue` | `number` | `0` | 最小值 | | `maxValue` | `number` | `100` | 最大值 | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | Meter 轨道尺寸 | | `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | 填充条颜色 | | `formatOptions` | `Intl.NumberFormatOptions` | `{style: 'percent'}` | 数值展示的格式化选项 | | `valueLabel` | `ReactNode` | - | 自定义数值标签内容 | | `children` | `ReactNode \| (values: MeterRenderProps) => ReactNode` | - | 内容或渲染 prop | ### MeterRenderProps 使用渲染 prop 模式时，会提供以下值： | Prop | 类型 | 描述 | | ------------ | -------- | ---------------- | | `percentage` | `number` | Meter 百分比（0–100） | | `valueText` | `string` | 格式化后的数值文本 | ## 相关组件 </page> <page url="/cn/docs/react/components/progress-bar"> # ProgressBar 进度条 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/progress-bar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(feedback)/progress-bar.mdx > 进度条用于展示某项操作随时间变化的确定或不确定进度。 ## 用法 ```tsx import { ProgressBar, Label } from '@heroui/react'; ``` ```tsx import {Label, ProgressBar} from "@heroui/react"; export function Basic() { return ( <ProgressBar aria-label="加载中" className="w-64" value={60}> <Label>加载中</Label> <ProgressBar.Output /> <ProgressBar.Track> <ProgressBar.Fill /> </ProgressBar.Track> </ProgressBar> ); } ``` ## 组件结构 ```tsx import { ProgressBar, Label } from '@heroui/react'; export default () => ( <ProgressBar value={60}> <Label>Loading</Label> <ProgressBar.Output /> <ProgressBar.Track> <ProgressBar.Fill /> </ProgressBar.Track> </ProgressBar> ); ``` ## 示例 ### 尺寸 ```tsx import {Label, ProgressBar} from "@heroui/react"; const SIZE_LABELS = { lg: "大", md: "中", sm: "小", } as const; export function Sizes() { return ( <div className="flex w-64 flex-col gap-6"> <ProgressBar aria-label={SIZE_LABELS.sm} size="sm" value={40}> <Label>{SIZE_LABELS.sm}</Label> <ProgressBar.Output /> <ProgressBar.Track> <ProgressBar.Fill /> </ProgressBar.Track> </ProgressBar> <ProgressBar aria-label={SIZE_LABELS.md} size="md" value={60}> <Label>{SIZE_LABELS.md}</Label> <ProgressBar.Output /> <ProgressBar.Track> <ProgressBar.Fill /> </ProgressBar.Track> </ProgressBar> <ProgressBar aria-label={SIZE_LABELS.lg} size="lg" value={80}> <Label>{SIZE_LABELS.lg}</Label> <ProgressBar.Output /> <ProgressBar.Track> <ProgressBar.Fill /> </ProgressBar.Track> </ProgressBar> </div> ); } ``` ### 颜色 ```tsx import {Label, ProgressBar} from "@heroui/react"; const colors = ["default", "accent", "success", "warning", "danger"] as const; const COLOR_LABELS: Record<(typeof colors)[number], string> = { accent: "强调", danger: "危险", default: "默认", success: "成功", warning: "警告", }; export function Colors() { return ( <div className="flex w-64 flex-col gap-6"> {colors.map((color) => ( <ProgressBar key={color} aria-label={COLOR_LABELS[color]} color={color} value={50}> <Label>{COLOR_LABELS[color]}</Label> <ProgressBar.Output /> <ProgressBar.Track> <ProgressBar.Fill /> </ProgressBar.Track> </ProgressBar> ))} </div> ); } ``` ### 无可见标签 无需可见标签时，使用 `aria-label` 提供无障碍标签。 ```tsx import {ProgressBar} from "@heroui/react"; export function WithoutLabel() { return ( <ProgressBar aria-label="加载进度" className="w-64" value={45}> <ProgressBar.Track> <ProgressBar.Fill /> </ProgressBar.Track> </ProgressBar> ); } ``` ### 不确定进度 无法确定进度时使用 `isIndeterminate`。 ```tsx import {Label, ProgressBar} from "@heroui/react"; export function Indeterminate() { return ( <ProgressBar isIndeterminate aria-label="加载中" className="w-64"> <Label>加载中…</Label> <ProgressBar.Track> <ProgressBar.Fill /> </ProgressBar.Track> </ProgressBar> ); } ``` ### 自定义数值范围 使用 `minValue`、`maxValue` 与 `formatOptions` 自定义取值范围与显示格式。 ```tsx "use client"; import {Label, ListBox, NumberField, ProgressBar, Select, Separator} from "@heroui/react"; import {useState} from "react"; const formatStyleOptions: {label: string; value: string}[] = [ {label: "货币", value: "currency"}, {label: "百分比", value: "percent"}, {label: "小数", value: "decimal"}, {label: "单位", value: "unit"}, ]; const formatOptionsMap: Record<string, Intl.NumberFormatOptions> = { currency: {currency: "USD", style: "currency"}, decimal: {style: "decimal"}, percent: {style: "percent"}, unit: {style: "unit", unit: "mile"}, }; export function CustomValue() { const [value, setValue] = useState(750); const [minValue, setMinValue] = useState(0); const [maxValue, setMaxValue] = useState(1000); const [format, setFormat] = useState<string>("percent"); return ( <div className="flex w-full flex-col gap-6 md:flex-row md:items-center md:gap-10"> <div className="flex w-full max-w-md flex-1 justify-center"> <ProgressBar aria-label="收入" className="w-full max-w-52" formatOptions={formatOptionsMap[format]} maxValue={maxValue} minValue={minValue} value={value} > <Label>进度</Label> <ProgressBar.Output /> <ProgressBar.Track> <ProgressBar.Fill /> </ProgressBar.Track> </ProgressBar> </div> <Separator className="md:hidden" /> <Separator className="hidden md:block" orientation="vertical" /> <div className="flex max-w-52 flex-col gap-3"> <Label className="text-xs font-medium text-muted">选项</Label> <NumberField maxValue={maxValue} minValue={minValue} value={value} variant="secondary" onChange={(v) => setValue(v)} > <Label>值</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> <NumberField maxValue={maxValue - 1} minValue={0} value={minValue} variant="secondary" onChange={(v) => { setMinValue(v); if (value < v) setValue(v); }} > <Label>最小值</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> <NumberField maxValue={2000} minValue={minValue + 1} value={maxValue} variant="secondary" onChange={(v) => { setMaxValue(v); if (value > v) setValue(v); }} > <Label>最大值</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> <Select value={format} variant="secondary" onChange={(key) => setFormat(key as string)}> <Label>格式</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> {formatStyleOptions.map((option) => ( <ListBox.Item key={option.value} id={option.value} textValue={option.label}> {option.label} <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Select.Popover> </Select> </div> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Label, ProgressBar} from "@heroui/react"; export function CustomStyles() { return ( <ProgressBar aria-label="上传进度" className="w-64" value={45}> <Label className="font-medium text-foreground">正在上传 resume.pdf</Label> <ProgressBar.Output className="text-xs text-muted tabular-nums" /> <ProgressBar.Track className="rounded-full bg-default"> <ProgressBar.Fill className="rounded-full bg-accent" /> </ProgressBar.Track> </ProgressBar> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .progress-bar { @apply w-full gap-2; } .progress-bar__track { @apply h-3 rounded-full; } .progress-bar__fill { @apply rounded-full; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ProgressBar 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/progress-bar.css)）： #### 基础与元素类 \[!toc] * `.progress-bar` - 基础容器（网格布局） * `.progress-bar__output` - 数值文本展示 * `.progress-bar__track` - 轨道背景 * `.progress-bar__fill` - 轨道上已填充部分 #### 尺寸类 \[!toc] * `.progress-bar--sm` - 小尺寸变体（更细的轨道） * `.progress-bar--md` - 中等尺寸变体（默认） * `.progress-bar--lg` - 大尺寸变体（更粗的轨道） #### 颜色类 \[!toc] * `.progress-bar--default` - 默认颜色变体 * `.progress-bar--accent` - 强调色变体 * `.progress-bar--success` - 成功色变体 * `.progress-bar--warning` - 警告色变体 * `.progress-bar--danger` - 危险色变体 ## API 参考 ### ProgressBar 继承自 [React Aria ProgressBar](https://react-spectrum.adobe.com/react-aria/ProgressBar.html)。 | Prop | 类型 | 默认值 | 描述 | | ----------------- | ------------------------------------------------------------- | -------------------- | ---------- | | `value` | `number` | `0` | 当前值 | | `minValue` | `number` | `0` | 最小值 | | `maxValue` | `number` | `100` | 最大值 | | `isIndeterminate` | `boolean` | `false` | 是否为不确定进度 | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | 进度轨道尺寸 | | `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | 填充条颜色 | | `formatOptions` | `Intl.NumberFormatOptions` | `{style: 'percent'}` | 数值展示的数字格式 | | `valueLabel` | `ReactNode` | - | 自定义数值标签内容 | | `children` | `ReactNode \| (values: ProgressBarRenderProps) => ReactNode` | - | 内容或渲染 prop | ### ProgressBarRenderProps 使用渲染 prop 模式时，会提供以下值： | Prop | 类型 | 描述 | | ----------------- | --------- | ------------ | | `percentage` | `number` | 进度百分比（0–100） | | `valueText` | `string` | 格式化后的数值文本 | | `isIndeterminate` | `boolean` | 是否为不确定进度 | ## 相关组件 </page> <page url="/cn/docs/react/components/progress-circle"> # ProgressCircle 环形进度条 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/progress-circle **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(feedback)/progress-circle.mdx > 环形进度指示器，用于展示确定或不确定的进度。 ## 用法 ```tsx import { ProgressCircle } from '@heroui/react'; ``` ```tsx import {ProgressCircle} from "@heroui/react"; export function Basic() { return ( <ProgressCircle aria-label="加载中" value={60}> <ProgressCircle.Track> <ProgressCircle.TrackCircle /> <ProgressCircle.FillCircle /> </ProgressCircle.Track> </ProgressCircle> ); } ``` ## 组件结构 ```tsx import { ProgressCircle } from '@heroui/react'; export default () => ( <ProgressCircle aria-label="Loading" value={60}> <ProgressCircle.Track> <ProgressCircle.TrackCircle /> <ProgressCircle.FillCircle /> </ProgressCircle.Track> </ProgressCircle> ); ``` ## 示例 ### 尺寸 ```tsx import {ProgressCircle} from "@heroui/react"; const SIZE_LABELS = { lg: "大", md: "中", sm: "小", } as const; export function Sizes() { return ( <div className="flex items-center gap-6"> <ProgressCircle aria-label={SIZE_LABELS.sm} size="sm" value={40}> <ProgressCircle.Track> <ProgressCircle.TrackCircle /> <ProgressCircle.FillCircle /> </ProgressCircle.Track> </ProgressCircle> <ProgressCircle aria-label={SIZE_LABELS.md} size="md" value={60}> <ProgressCircle.Track> <ProgressCircle.TrackCircle /> <ProgressCircle.FillCircle /> </ProgressCircle.Track> </ProgressCircle> <ProgressCircle aria-label={SIZE_LABELS.lg} size="lg" value={80}> <ProgressCircle.Track> <ProgressCircle.TrackCircle /> <ProgressCircle.FillCircle /> </ProgressCircle.Track> </ProgressCircle> </div> ); } ``` ### 颜色 ```tsx import {ProgressCircle} from "@heroui/react"; const colors = ["default", "accent", "success", "warning", "danger"] as const; const COLOR_LABELS: Record<(typeof colors)[number], string> = { accent: "强调", danger: "危险", default: "默认", success: "成功", warning: "警告", }; export function Colors() { return ( <div className="flex items-center gap-6"> {colors.map((color) => ( <ProgressCircle key={color} aria-label={COLOR_LABELS[color]} color={color} value={60}> <ProgressCircle.Track> <ProgressCircle.TrackCircle /> <ProgressCircle.FillCircle /> </ProgressCircle.Track> </ProgressCircle> ))} </div> ); } ``` ### 不确定进度 无法确定进度时使用 `isIndeterminate`。 ```tsx import {ProgressCircle} from "@heroui/react"; export function Indeterminate() { return ( <ProgressCircle isIndeterminate aria-label="加载中"> <ProgressCircle.Track> <ProgressCircle.TrackCircle /> <ProgressCircle.FillCircle /> </ProgressCircle.Track> </ProgressCircle> ); } ``` ### 带标签 ```tsx import {Label, ProgressCircle} from "@heroui/react"; export function WithLabel() { return ( <div className="flex items-center gap-3"> <ProgressCircle aria-label="加载中" value={75}> <ProgressCircle.Track> <ProgressCircle.TrackCircle /> <ProgressCircle.FillCircle /> </ProgressCircle.Track> </ProgressCircle> <Label>已完成 75%</Label> </div> ); } ``` ### 自定义 SVG 属性 各子部分均为可组合组件，可直接覆盖 `strokeWidth`、`r`、`cx`、`cy`、`viewBox` 等 SVG 属性。 ```tsx import {ProgressCircle} from "@heroui/react"; export function CustomSvg() { return ( <div className="flex items-end gap-6"> <ProgressCircle aria-label="细圆环" value={60}> <ProgressCircle.Track strokeWidth={2} viewBox="0 0 36 36"> <ProgressCircle.TrackCircle cx={18} cy={18} r={17} strokeWidth={2} /> <ProgressCircle.FillCircle cx={18} cy={18} r={17} strokeWidth={2} /> </ProgressCircle.Track> </ProgressCircle> <ProgressCircle aria-label="默认圆环" value={60}> <ProgressCircle.Track> <ProgressCircle.TrackCircle /> <ProgressCircle.FillCircle /> </ProgressCircle.Track> </ProgressCircle> <ProgressCircle aria-label="粗圆环" value={60}> <ProgressCircle.Track strokeWidth={6} viewBox="0 0 36 36"> <ProgressCircle.TrackCircle cx={18} cy={18} r={15} strokeWidth={6} /> <ProgressCircle.FillCircle cx={18} cy={18} r={15} strokeWidth={6} /> </ProgressCircle.Track> </ProgressCircle> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {ProgressCircle} from "@heroui/react"; export function CustomStyles() { return ( <ProgressCircle aria-label="同步进度" className="size-14 text-neutral-700 dark:text-neutral-300" value={68} > <ProgressCircle.Track> <ProgressCircle.TrackCircle className="stroke-neutral-200 dark:stroke-neutral-800" /> <ProgressCircle.FillCircle className="stroke-neutral-700 dark:stroke-neutral-300" strokeLinecap="round" /> </ProgressCircle.Track> </ProgressCircle> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .progress-circle { @apply inline-flex; } .progress-circle__track { @apply size-12; } .progress-circle__fill-circle { stroke: purple; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ProgressCircle 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/progress-circle.css)）： #### 基础与元素类 \[!toc] * `.progress-circle` - 基础容器 * `.progress-circle__track` - SVG 元素 * `.progress-circle__track-circle` - 背景圆环 * `.progress-circle__fill-circle` - 进度弧 #### 尺寸类 \[!toc] * `.progress-circle--sm` - 小尺寸 * `.progress-circle--md` - 中等尺寸（默认） * `.progress-circle--lg` - 大尺寸 #### 颜色类 \[!toc] * `.progress-circle--default` - 默认颜色 * `.progress-circle--accent` - 强调色 * `.progress-circle--success` - 成功色 * `.progress-circle--warning` - 警告色 * `.progress-circle--danger` - 危险色 ## API 参考 ### ProgressCircle 继承自 [React Aria ProgressBar](https://react-spectrum.adobe.com/react-aria/ProgressBar.html)。 | Prop | 类型 | 默认值 | 描述 | | ----------------- | ------------------------------------------------------------- | -------------------- | ---------- | | `value` | `number` | `0` | 当前值 | | `minValue` | `number` | `0` | 最小值 | | `maxValue` | `number` | `100` | 最大值 | | `isIndeterminate` | `boolean` | `false` | 是否为不确定进度 | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | 圆环尺寸 | | `color` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | 进度弧颜色 | | `formatOptions` | `Intl.NumberFormatOptions` | `{style: 'percent'}` | 数值展示格式 | | `children` | `ReactNode \| (values: ProgressBarRenderProps) => ReactNode` | - | 内容或渲染 prop | ### ProgressBarRenderProps 使用渲染 prop 模式时，会提供以下值： | Prop | 类型 | 描述 | | ----------------- | --------- | ------------ | | `percentage` | `number` | 进度百分比（0–100） | | `valueText` | `string` | 格式化后的数值文案 | | `isIndeterminate` | `boolean` | 是否为不确定进度 | ## 相关组件 </page> <page url="/cn/docs/react/components/skeleton"> # Skeleton 骨架屏 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/skeleton **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(feedback)/skeleton.mdx > Skeleton 用于展示加载状态，并预览组件的预期形状。 ## 用法 ```tsx import { Skeleton } from '@heroui/react'; ``` ```tsx import {Skeleton} from "@heroui/react"; export function Basic() { return ( <div className="shadow-panel w-[250px] space-y-5 rounded-lg bg-transparent p-4"> <Skeleton className="h-32 rounded-lg" /> <div className="space-y-3"> <Skeleton className="h-3 w-3/5 rounded-lg" /> <Skeleton className="h-3 w-4/5 rounded-lg" /> <Skeleton className="h-3 w-2/5 rounded-lg" /> </div> </div> ); } ``` ## 示例 ### 文本内容 ```tsx import {Skeleton} from "@heroui/react"; export function TextContent() { return ( <div className="w-full max-w-md space-y-3"> <Skeleton className="h-4 w-full rounded" /> <Skeleton className="h-4 w-5/6 rounded" /> <Skeleton className="h-4 w-4/6 rounded" /> <Skeleton className="h-4 w-full rounded" /> <Skeleton className="h-4 w-3/6 rounded" /> </div> ); } ``` ### 用户资料 ```tsx import {Skeleton} from "@heroui/react"; export function UserProfile() { return ( <div className="flex items-center gap-3"> <Skeleton className="h-10 w-10 shrink-0 rounded-full" /> <div className="flex-1 space-y-2"> <Skeleton className="h-3 w-36 rounded-lg" /> <Skeleton className="h-3 w-24 rounded-lg" /> </div> </div> ); } ``` ### 列表项 ```tsx import {Skeleton} from "@heroui/react"; export function List() { return ( <div className="w-full max-w-sm space-y-4"> {Array.from({length: 3}).map((_, index) => ( <div key={index} className="flex items-center gap-3"> <Skeleton className="h-10 w-10 shrink-0 rounded-lg" /> <div className="flex-1 space-y-2"> <Skeleton className="h-3 w-full rounded" /> <Skeleton className="h-3 w-4/5 rounded" /> </div> </div> ))} </div> ); } ``` ### 网格 ```tsx import {Skeleton} from "@heroui/react"; export function Grid() { return ( <div className="grid w-full max-w-xl grid-cols-3 gap-4"> <Skeleton className="h-24 rounded-xl" /> <Skeleton className="h-24 rounded-xl" /> <Skeleton className="h-24 rounded-xl" /> </div> ); } ``` ### 单次闪烁 同步的 shimmer 效果会一次性扫过所有骨架元素。在父容器上应用 `skeleton--shimmer` 类，并将子骨架的 `animationType` 设为 `"none"`。 ```tsx import {Skeleton} from "@heroui/react"; export function SingleShimmer() { return ( <div className="skeleton--shimmer relative grid w-full max-w-xl grid-cols-3 gap-4 overflow-hidden rounded-xl"> <Skeleton animationType="none" className="h-24 rounded-xl" /> <Skeleton animationType="none" className="h-24 rounded-xl" /> <Skeleton animationType="none" className="h-24 rounded-xl" /> </div> ); } ``` ### 动画类型 ```tsx import {Skeleton} from "@heroui/react"; export function AnimationTypes() { return ( <div className="grid w-full max-w-xl grid-cols-1 gap-6 sm:grid-cols-2 lg:grid-cols-3"> <div className="space-y-2"> <p className="truncate text-xs text-muted">微光</p> <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4"> <Skeleton animationType="shimmer" className="h-20 rounded-lg" /> <Skeleton animationType="shimmer" className="h-3 w-3/5 rounded-lg" /> <Skeleton animationType="shimmer" className="h-3 w-4/5 rounded-lg" /> </div> </div> <div className="space-y-2"> <p className="truncate text-xs text-muted">脉冲</p> <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4"> <Skeleton animationType="pulse" className="h-20 rounded-lg" /> <Skeleton animationType="pulse" className="h-3 w-3/5 rounded-lg" /> <Skeleton animationType="pulse" className="h-3 w-4/5 rounded-lg" /> </div> </div> <div className="space-y-2"> <p className="truncate text-xs text-muted">无</p> <div className="shadow-panel space-y-3 rounded-lg bg-transparent p-4"> <Skeleton animationType="none" className="h-20 rounded-lg" /> <Skeleton animationType="none" className="h-3 w-3/5 rounded-lg" /> <Skeleton animationType="none" className="h-3 w-4/5 rounded-lg" /> </div> </div> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Skeleton} from "@heroui/react"; const bone = "animate-shine rounded-lg bg-neutral-200/90 dark:bg-neutral-800/90"; export function CustomStyles() { return ( <div className="w-[250px] space-y-5 rounded-xl border border-border/80 bg-surface p-4 shadow-sm ring-1 ring-black/5 dark:ring-white/10"> <Skeleton className={`h-32 ${bone}`} /> <div className="space-y-3"> <Skeleton className={`h-3 w-3/5 ${bone}`} /> <Skeleton className={`h-3 w-4/5 ${bone}`} /> <Skeleton className={`h-3 w-2/5 ${bone}`} /> </div> </div> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](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 */ } } ``` ### 全局动画配置 可在全局 CSS 中通过 `--skeleton-animation` 变量为所有 Skeleton 组件设置默认动画类型： ```css /* 全局 CSS 文件 */ :root { /* 可选值：shimmer、pulse、none */ --skeleton-animation: pulse; } /* 也可为浅色/深色主题设置不同值 */ .light, [data-theme="light"] { --skeleton-animation: shimmer; } .dark, [data-theme="dark"] { --skeleton-animation: pulse; } ``` 在单个组件上指定 `animationType` 属性会覆盖此全局设置。 ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### 全局动画配置 你可以通过在应用中定义 `--skeleton-animation` CSS 变量，为所有 Skeleton 设置默认动画类型： ```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; } ``` 在单个组件上指定 `animationType` 时，会覆盖上述全局设置。 ### CSS 类 Skeleton 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/skeleton.css)）： #### 基础类 \[!toc] `.skeleton` - 包含背景与圆角等基础骨架样式 #### 动画变体类 \[!toc] * `.skeleton--shimmer` - 添加带渐变效果的闪烁动画（默认） * `.skeleton--pulse` - 使用 Tailwind 的 `animate-pulse` 添加脉冲动画 * `.skeleton--none` - 无动画的静态骨架 ### 动画 Skeleton 支持三种动画类型，视觉效果各不相同： #### 闪烁动画 \[!toc] 闪烁效果会在骨架元素上移动渐变： ```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-['']; } ``` 闪烁动画在主题中通过以下方式定义： ```css @theme inline { --animate-skeleton: skeleton 2s linear infinite; @keyframes skeleton { 100% { transform: translateX(200%); } } } ``` #### 脉冲动画 \[!toc] 脉冲动画使用 Tailwind 内置的 `animate-pulse` 工具类： ```css .skeleton--pulse { @apply animate-pulse; } ``` #### 无动画 \[!toc] 用于不需要任何动画的静态骨架： ```css .skeleton--none { /* No animation styles applied */ } ``` ## API 参考 ### Skeleton | Prop | 类型 | 默认值 | 描述 | | --------------- | -------------------------------- | -------------------- | ------------------------------------------------------- | | `animationType` | `"shimmer" \| "pulse" \| "none"` | `"shimmer"` 或 CSS 变量 | Skeleton 的动画类型；也可通过 `--skeleton-animation` CSS 变量进行全局配置 | | `className` | `string` | - | 额外的 CSS 类名 | ## 相关组件 ## Related Components * **Card**: Content container with header, body, and footer * **Avatar**: Display user profile images </page> <page url="/cn/docs/react/components/spinner"> # Spinner 加载指示器 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/spinner **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(feedback)/spinner.mdx > 用于展示等待或处理中状态的加载指示组件。 ## 用法 ```tsx import { Spinner } from '@heroui/react'; ``` ```tsx import {Spinner} from "@heroui/react"; export function SpinnerBasic() { return ( <div className="flex items-center gap-4"> <Spinner /> </div> ); } ``` ## 示例 ### 颜色 ```tsx import {Spinner} from "@heroui/react"; const COLOR_LABELS = { accent: "强调", current: "当前", danger: "危险", success: "成功", warning: "警告", } as const; const colors = ["current", "accent", "success", "warning", "danger"] as const; export function SpinnerColors() { return ( <div className="flex items-center gap-8"> {colors.map((color) => ( <div key={color} className="flex flex-col items-center gap-2"> <Spinner color={color} /> <span className="text-xs text-muted">{COLOR_LABELS[color]}</span> </div> ))} </div> ); } ``` ### 尺寸 ```tsx import {Spinner} from "@heroui/react"; const SIZE_LABELS = { lg: "大", md: "中", sm: "小", xl: "特大", } as const; const sizes = ["sm", "md", "lg", "xl"] as const; export function SpinnerSizes() { return ( <div className="flex items-center gap-8"> {sizes.map((size) => ( <div key={size} className="flex flex-col items-center gap-2"> <Spinner size={size} /> <span className="text-xs text-muted">{SIZE_LABELS[size]}</span> </div> ))} </div> ); } ``` ### 速度 为单个 Spinner 添加动画工具类即可调整其旋转速度。请同时加上 `motion-reduce:animate-none`，以便在用户开启“减少动态效果”时保持静止。 ```tsx import {Spinner} from "@heroui/react"; export function SpinnerSpeed() { return ( <div className="flex items-center gap-8"> <div className="flex flex-col items-center gap-2"> <Spinner className="animate-[spin_1.5s_linear_infinite] motion-reduce:animate-none" /> <span className="text-xs text-muted">慢速</span> </div> <div className="flex flex-col items-center gap-2"> <Spinner /> <span className="text-xs text-muted">默认</span> </div> <div className="flex flex-col items-center gap-2"> <Spinner className="animate-[spin_0.4s_linear_infinite] motion-reduce:animate-none" /> <span className="text-xs text-muted">快速</span> </div> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Spinner} from "@heroui/react"; export function CustomStyles() { return ( <div className="flex items-center gap-4 rounded-xl border border-border bg-surface px-5 py-4"> <Spinner className="text-accent" size="sm" /> <Spinner className="text-muted" size="md" /> <Spinner className="text-success" size="lg" /> </div> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .spinner { @apply animate-spin; } .spinner--accent { color: var(--accent); } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Spinner 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/spinner.css)）： #### 基础类与尺寸类 \[!toc] * `.spinner` - 基础样式与默认尺寸 * `.spinner--sm` - 小尺寸变体 * `.spinner--md` - 中等尺寸变体（默认） * `.spinner--lg` - 大尺寸变体 * `.spinner--xl` - 特大尺寸变体 #### 颜色类 \[!toc] * `.spinner--current` - 继承当前文本颜色 * `.spinner--accent` - 强调色变体 * `.spinner--danger` - 危险色变体 * `.spinner--success` - 成功色变体 * `.spinner--warning` - 警告色变体 ## API 参考 ### Spinner | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------- | ---------- | ------------- | | `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"md"` | Spinner 的尺寸 | | `color` | `"current" \| "accent" \| "success" \| "warning" \| "danger"` | `"accent"` | Spinner 的颜色变体 | | `className` | `string` | - | 额外的 CSS 类名 | ## 相关组件 </page> <page url="/cn/docs/react/components/checkbox-group"> # CheckboxGroup 复选框组 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/checkbox-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/checkbox-group.mdx > 用于管理多个复选框选择的复选框组组件 ## 用法 ```tsx import { CheckboxGroup, Checkbox, Label, Description } from '@heroui/react'; ``` ```tsx import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function Basic() { return ( <CheckboxGroup name="interests"> <Label>选择你的兴趣</Label> <Description>可多选</Description> <Checkbox value="coding"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 编程 </Checkbox.Content> <Description>热爱构建软件</Description> </Checkbox> <Checkbox value="design"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 设计 </Checkbox.Content> <Description>喜欢打造精美界面</Description> </Checkbox> <Checkbox value="writing"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 写作 </Checkbox.Content> <Description>热衷于内容创作</Description> </Checkbox> </CheckboxGroup> ); } ``` ## 组件结构 ```tsx import {CheckboxGroup, Checkbox, Label, Description, FieldError} from '@heroui/react'; export default () => ( <CheckboxGroup name="interests"> <Label /> <Description /> {/* 可选 */} <Checkbox value="option1"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> Label {/* 纯文本 — 可点击标签 */} </Checkbox.Content> <Description /> {/* 可选 — 单个 Checkbox 的帮助文本 */} </Checkbox> <FieldError /> {/* 可选 */} </CheckboxGroup> ); ``` ## 示例 ### 表面样式 在 [Surface](/docs/react/components/surface) 组件内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。 ```tsx import {Checkbox, CheckboxGroup, Description, Label, Surface} from "@heroui/react"; export function OnSurface() { return ( <Surface className="w-full rounded-3xl p-6"> <CheckboxGroup name="interests" variant="secondary"> <Label>选择你的兴趣</Label> <Description>可多选</Description> <Checkbox value="coding"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 编程 </Checkbox.Content> <Description>热爱构建软件</Description> </Checkbox> <Checkbox value="design"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 设计 </Checkbox.Content> <Description>喜欢打造精美界面</Description> </Checkbox> <Checkbox value="writing"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 写作 </Checkbox.Content> <Description>热衷于内容创作</Description> </Checkbox> </CheckboxGroup> </Surface> ); } ``` ### 禁用 ```tsx import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function Disabled() { return ( <CheckboxGroup isDisabled name="disabled-features"> <Label>功能</Label> <Description>功能选择暂时不可用</Description> <Checkbox value="feature1"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 功能一 </Checkbox.Content> <Description>该功能即将推出</Description> </Checkbox> <Checkbox value="feature2"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 功能二 </Checkbox.Content> <Description>该功能即将推出</Description> </Checkbox> </CheckboxGroup> ); } ``` ### 半选状态 ```tsx "use client"; import {Checkbox, CheckboxGroup} from "@heroui/react"; import {useState} from "react"; export function Indeterminate() { const [selected, setSelected] = useState(["coding"]); const allOptions = ["coding", "design", "writing"]; return ( <div> <Checkbox isIndeterminate={selected.length > 0 && selected.length < allOptions.length} isSelected={selected.length === allOptions.length} name="select-all" onChange={(isSelected: boolean) => { setSelected(isSelected ? allOptions : []); }} > <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 全选 </Checkbox.Content> </Checkbox> <div className="ms-6 flex flex-col gap-2"> <CheckboxGroup value={selected} onChange={setSelected}> <Checkbox value="coding"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 编程 </Checkbox.Content> </Checkbox> <Checkbox value="design"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 设计 </Checkbox.Content> </Checkbox> <Checkbox value="writing"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 写作 </Checkbox.Content> </Checkbox> </CheckboxGroup> </div> </div> ); } ``` ### 受控组件 ```tsx "use client"; import {Checkbox, CheckboxGroup, Label} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [selected, setSelected] = useState(["coding", "design"]); return ( <CheckboxGroup className="min-w-[320px]" name="skills" value={selected} onChange={setSelected}> <Label>你的技能</Label> <Checkbox value="coding"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 编程 </Checkbox.Content> </Checkbox> <Checkbox value="design"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 设计 </Checkbox.Content> </Checkbox> <Checkbox value="writing"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 写作 </Checkbox.Content> </Checkbox> <Label className="my-4 text-sm text-muted">已选：{selected.join(", ") || "无"}</Label> </CheckboxGroup> ); } ``` ### 表单校验 ```tsx "use client"; import {Button, Checkbox, CheckboxGroup, FieldError, Form, Label} from "@heroui/react"; export function Validation() { return ( <Form className="flex flex-col gap-4 px-4" onSubmit={(e) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const values = formData.getAll("preferences"); alert(`已选偏好：${values.join(", ")}`); }} > <CheckboxGroup isRequired name="preferences"> <Label>偏好设置</Label> <Checkbox value="email"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 邮件通知 </Checkbox.Content> </Checkbox> <Checkbox value="sms"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 短信通知 </Checkbox.Content> </Checkbox> <Checkbox value="push"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 推送通知 </Checkbox.Content> </Checkbox> <FieldError>请至少选择一种通知方式。</FieldError> </CheckboxGroup> <Button type="submit">提交</Button> </Form> ); } ``` ### 功能扩展示例 ```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: "通过邮件接收更新", icon: Envelope, title: "邮件通知", value: "email", }, { description: "即时短信通知", icon: Comment, title: "短信提醒", value: "sms", }, { description: "浏览器与移动端推送提醒", icon: Bell, title: "推送通知", value: "push", }, ]; return ( <div className="flex w-full flex-col items-center gap-10 px-4 py-8"> <section className="flex w-full min-w-[320px] flex-col gap-4"> <CheckboxGroup name="notification-preferences"> <Label>通知偏好</Label> <Description>选择接收更新的方式</Description> <div className="flex flex-col gap-2"> {addOns.map((addon) => ( <Checkbox key={addon.value} value={addon.value} variant="secondary"> <Checkbox.Content className={clsx( "group relative flex w-full flex-row items-start justify-start gap-4 rounded-3xl bg-surface px-5 py-4 transition-all", "data-[selected=true]:bg-accent/10", )} > <Checkbox.Control className="absolute end-4 top-3 size-5 rounded-full before:rounded-full"> <Checkbox.Indicator /> </Checkbox.Control> <addon.icon className="size-5 text-accent-soft-foreground" /> <div className="flex flex-col gap-1"> <span>{addon.title}</span> <Description>{addon.description}</Description> </div> </Checkbox.Content> </Checkbox> ))} </div> </CheckboxGroup> </section> </div> ); } ``` ### 自定义指示器 ```tsx "use client"; import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function WithCustomIndicator() { return ( <CheckboxGroup name="features"> <Label>功能</Label> <Description>选择你需要的功能</Description> <Checkbox value="notifications"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator> {({isSelected}) => isSelected ? ( <svg aria-hidden="true" fill="none" stroke="currentColor" strokeLinecap="round" strokeWidth={2} viewBox="0 0 24 24" > <path d="M6 18L18 6M6 6l12 12" /> </svg> ) : null } </Checkbox.Indicator> </Checkbox.Control> 邮件通知 </Checkbox.Content> <Description>通过邮件接收更新</Description> </Checkbox> <Checkbox value="newsletter"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator> {({isSelected}) => isSelected ? ( <svg aria-hidden="true" fill="none" stroke="currentColor" strokeLinecap="round" strokeWidth={2} viewBox="0 0 24 24" > <path d="M6 18L18 6M6 6l12 12" /> </svg> ) : null } </Checkbox.Indicator> </Checkbox.Control> 邮件通讯 </Checkbox.Content> <Description>每周接收邮件简报</Description> </Checkbox> </CheckboxGroup> ); } ``` ### 渲染函数 ```tsx "use client"; import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; export function RenderFunction() { return ( <CheckboxGroup name="interests" render={(props) => <div {...props} data-custom="foo" />}> <Label>选择你的兴趣</Label> <Description>可多选</Description> <Checkbox value="coding"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 编程 </Checkbox.Content> <Description>热爱构建软件</Description> </Checkbox> <Checkbox value="design"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 设计 </Checkbox.Content> <Description>喜欢打造精美界面</Description> </Checkbox> <Checkbox value="writing"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 写作 </Checkbox.Content> <Description>热衷于内容创作</Description> </Checkbox> </CheckboxGroup> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Checkbox, CheckboxGroup, Description, Label} from "@heroui/react"; const controlClassName = "bg-success-soft before:bg-success"; const indicatorClassName = "**:data-[slot=checkbox-default-indicator--checkmark]:text-success-foreground"; const channels = [ {label: "电子邮件", value: "email"}, {label: "短信", value: "sms"}, {label: "推送", value: "push"}, ] as const; export function CustomStyles() { return ( <CheckboxGroup className="gap-3 **:data-[slot=checkbox]:mt-0" defaultValue={["email"]} name="notification-channels" > <Label>通知渠道</Label> <Description>选择我们通过何种方式向您发送账户更新。</Description> {channels.map(({label, value}) => ( <Checkbox key={value} value={value}> <Checkbox.Content> <Checkbox.Control className={controlClassName}> <Checkbox.Indicator className={indicatorClassName} /> </Checkbox.Control> {label} </Checkbox.Content> </Checkbox> ))} </CheckboxGroup> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 CheckboxGroup 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .checkbox-group { @apply flex flex-col gap-2; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 CheckboxGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox-group.css)）： #### 基础类 \[!toc] * `.checkbox-group` - 复选框组根容器 ## API 参考 ### CheckboxGroup 继承自 [React Aria CheckboxGroup](https://react-spectrum.adobe.com/react-aria/CheckboxGroup.html)。 | Prop | 类型 | 默认值 | 描述 | | -------------- | -------------------------------------------------------------------------------- | ------- | -------------------------- | | `value` | `string[]` | - | 当前选中值（受控） | | `defaultValue` | `string[]` | - | 默认选中值（非受控） | | `onChange` | `(value: string[]) => void` | - | 选中值变化时的回调 | | `isDisabled` | `boolean` | `false` | 是否禁用 | | `isRequired` | `boolean` | `false` | 是否必填 | | `isReadOnly` | `boolean` | `false` | 是否只读 | | `isInvalid` | `boolean` | `false` | 是否处于无效状态 | | `name` | `string` | - | 提交 HTML 表单时复选框组的名称 | | `children` | `React.ReactNode \| (values: CheckboxGroupRenderProps) => React.ReactNode` | - | 内容或 render prop | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxGroupRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Render Props 使用 render prop 模式时，提供以下值： | Prop | 类型 | 描述 | | ------------ | ---------- | -------- | | `value` | `string[]` | 当前选中值 | | `isDisabled` | `boolean` | 是否禁用 | | `isReadOnly` | `boolean` | 是否只读 | | `isInvalid` | `boolean` | 是否处于无效状态 | | `isRequired` | `boolean` | 是否必填 | ## 相关组件 ## Related Components * **Checkbox**: Binary choice input control * **Label**: Accessible label for form controls * **Fieldset**: Group related form controls with legends </page> <page url="/cn/docs/react/components/checkbox"> # Checkbox 复选框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/checkbox **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/checkbox.mdx > 复选框允许用户从列表中选择多项，或标记单个项目为选中状态 ## 用法 ```tsx import { Checkbox } from '@heroui/react'; ``` ```tsx import {Checkbox} from "@heroui/react"; export function Basic() { return ( <Checkbox name="basic-terms"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 接受条款与条件 </Checkbox.Content> </Checkbox> ); } ``` ## 组件结构 ```tsx import { Checkbox, Description, FieldError } from '@heroui/react'; export default () => ( <Checkbox> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> Label {/* 纯文本 — 可点击标签与无障碍名称 */} </Checkbox.Content> <Description /> {/* 可选 — 字段级帮助文本 */} <FieldError /> {/* 可选 — 校验消息 */} </Checkbox> ); ``` ## 示例 ### 变体 Checkbox 组件支持两种视觉变体： * **`primary`**（默认）- 标准样式与默认背景，适用于大多数场景 * **`secondary`** - 低强调变体，适用于 Surface 组件内 ```tsx import {Checkbox, Description} 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">主要变体</p> <Checkbox id="primary" name="primary" variant="primary"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 主要复选框 </Checkbox.Content> <Description>默认背景的标准样式</Description> </Checkbox> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">次要变体</p> <Checkbox id="secondary" name="secondary" variant="secondary"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 次要复选框 </Checkbox.Content> <Description>用于表面容器的低强调样式</Description> </Checkbox> </div> </div> ); } ``` ### 全圆角 ```tsx import {Checkbox, Label} from "@heroui/react"; export function FullRounded() { return ( <div className="flex flex-col gap-6"> <div className="flex flex-col gap-3"> <Label className="text-muted">圆角复选框</Label> <Checkbox className="[&_[data-slot='checkbox-default-indicator--checkmark']]:size-2" name="small-rounded" > <Checkbox.Content> <Checkbox.Control className="size-3 rounded-full before:rounded-full"> <Checkbox.Indicator /> </Checkbox.Control> 小尺寸 </Checkbox.Content> </Checkbox> </div> <div className="flex flex-col gap-3"> <Checkbox name="default-rounded"> <Checkbox.Content> <Checkbox.Control className="size-4 rounded-full before:rounded-full"> <Checkbox.Indicator /> </Checkbox.Control> 默认尺寸 </Checkbox.Content> </Checkbox> </div> <div className="flex flex-col gap-3"> <Checkbox name="large-rounded"> <Checkbox.Content> <Checkbox.Control className="size-5 rounded-full before:rounded-full"> <Checkbox.Indicator /> </Checkbox.Control> 大尺寸 </Checkbox.Content> </Checkbox> </div> <div className="flex flex-col gap-3"> <Checkbox className="[&_[data-slot='checkbox-default-indicator--checkmark']]:size-4" name="xl-rounded" > <Checkbox.Content> <Checkbox.Control className="size-6 rounded-full before:rounded-full"> <Checkbox.Indicator /> </Checkbox.Control> 特大尺寸 </Checkbox.Content> </Checkbox> </div> </div> ); } ``` ### 禁用 ```tsx import {Checkbox, Description} from "@heroui/react"; export function Disabled() { return ( <Checkbox isDisabled id="feature"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 高级功能 </Checkbox.Content> <Description>该功能即将推出</Description> </Checkbox> ); } ``` ### 外部标签 ```tsx import {Checkbox, Label} from "@heroui/react"; export function ExternalLabel() { return ( <div className="flex items-center gap-3"> <Checkbox id="label-marketing"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> </Checkbox.Content> </Checkbox> <Label htmlFor="label-marketing">给我发送营销邮件</Label> </div> ); } ``` ### 带描述 ```tsx import {Checkbox, Description} from "@heroui/react"; export function WithDescription() { return ( <Checkbox name="description-notifications"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 邮件通知 </Checkbox.Content> <Description>当有人在评论中提及您时收到通知</Description> </Checkbox> ); } ``` ### 默认选中 ```tsx import {Checkbox} from "@heroui/react"; export function DefaultSelected() { return ( <Checkbox defaultSelected id="default-notifications"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 启用邮件通知 </Checkbox.Content> </Checkbox> ); } ``` ### 无效状态 ```tsx import {Checkbox, FieldError} from "@heroui/react"; export function Invalid() { return ( <Checkbox isInvalid isRequired name="agreement"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 我同意条款 </Checkbox.Content> <FieldError>您必须接受条款才能继续</FieldError> </Checkbox> ); } ``` ### 受控组件 ```tsx "use client"; import {Checkbox} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [isSelected, setIsSelected] = useState(true); return ( <div className="flex flex-col gap-3"> <Checkbox id="email-notifications" isSelected={isSelected} onChange={setIsSelected}> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 邮件通知 </Checkbox.Content> </Checkbox> <p className="text-sm text-muted"> 状态：<span className="font-medium">{isSelected ? "已勾选" : "未勾选"}</span> </p> </div> ); } ``` ### 半选状态 ```tsx "use client"; import {Checkbox, Description} from "@heroui/react"; import {useState} from "react"; export function Indeterminate() { const [isIndeterminate, setIsIndeterminate] = useState(true); const [isSelected, setIsSelected] = useState(false); return ( <Checkbox id="select-all" isIndeterminate={isIndeterminate} isSelected={isSelected} onChange={(selected: boolean) => { setIsSelected(selected); setIsIndeterminate(false); }} > <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 全选 </Checkbox.Content> <Description>展示部分选中状态（短横线图标）</Description> </Checkbox> ); } ``` ### 表单集成 ```tsx "use client"; import {Button, Checkbox} from "@heroui/react"; import React from "react"; export function Form() { const handleSubmit = (e: React.SyntheticEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.target as HTMLFormElement); alert( `表单提交数据：\n${Array.from(formData.entries()) .map(([key, value]) => `${key}: ${value}`) .join("\n")}`, ); }; return ( <form className="flex flex-col gap-4" onSubmit={handleSubmit}> <div className="flex flex-col gap-3"> <Checkbox name="notifications" value="on"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 启用通知 </Checkbox.Content> </Checkbox> <Checkbox defaultSelected name="newsletter" value="on"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 订阅新闻通讯 </Checkbox.Content> </Checkbox> <Checkbox name="marketing" value="on"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 接收营销更新 </Checkbox.Content> </Checkbox> </div> <Button className="mt-4" size="sm" type="submit" variant="primary"> 提交 </Button> </form> ); } ``` ### 渲染属性 ```tsx "use client"; import {Checkbox, Description} from "@heroui/react"; export function RenderProps() { return ( <Checkbox id="render-props-terms"> {({isSelected}) => ( <> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> {isSelected ? "已同意条款" : "接受条款"} </Checkbox.Content> <Description>{isSelected ? "感谢您的确认" : "请先阅读并接受条款"}</Description> </> )} </Checkbox> ); } ``` ### 渲染函数 ```tsx "use client"; import {Checkbox} from "@heroui/react"; export function RenderFunction() { return ( <Checkbox render={(props) => <div {...props} data-custom="bar" />}> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator /> </Checkbox.Control> 接受条款与条件 </Checkbox.Content> </Checkbox> ); } ``` ### 自定义指示器 ```tsx "use client"; import {Checkbox} from "@heroui/react"; export function CustomIndicator() { return ( <div className="flex gap-4"> <Checkbox defaultSelected name="heart"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator> {({isSelected}) => isSelected ? ( <svg fill="currentColor" viewBox="0 0 24 24"> <path d="M12.62 20.81c-.34.12-.9.12-1.24 0C8.48 19.82 2 15.69 2 8.69 2 5.6 4.49 3.1 7.56 3.1c1.82 0 3.43.88 4.44 2.24a5.53 5.53 0 0 1 4.44-2.24C19.51 3.1 22 5.6 22 8.69c0 7-6.48 11.13-9.38 12.12Z" fill="currentColor" /> </svg> ) : null } </Checkbox.Indicator> </Checkbox.Control> 心形 </Checkbox.Content> </Checkbox> <Checkbox defaultSelected name="plus"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator> {({isSelected}) => isSelected ? ( <svg fill="none" viewBox="0 0 24 24"> <path d="M6 12H18" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="3" /> <path d="M12 18V6" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="3" /> </svg> ) : null } </Checkbox.Indicator> </Checkbox.Control> 加号 </Checkbox.Content> </Checkbox> <Checkbox isIndeterminate name="indeterminate"> <Checkbox.Content> <Checkbox.Control> <Checkbox.Indicator> {({isIndeterminate}) => isIndeterminate ? ( <svg stroke="currentColor" strokeWidth={3} viewBox="0 0 24 24"> <line x1="21" x2="3" y1="12" y2="12" /> </svg> ) : null } </Checkbox.Indicator> </Checkbox.Control> 部分选中 </Checkbox.Content> </Checkbox> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Checkbox} from "@heroui/react"; export function CustomStyles() { return ( <Checkbox id="custom"> <Checkbox.Content> <Checkbox.Control className="bg-success-soft before:bg-success"> <Checkbox.Indicator className="**:data-[slot=checkbox-default-indicator--checkmark]:text-success-foreground" /> </Checkbox.Control> 自定义样式复选框 </Checkbox.Content> </Checkbox> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Checkbox 组件类。 [了解更多](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 items-center gap-3; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Checkbox 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/checkbox.css)）： #### 基础类 \[!toc] * `.checkbox` - 基础复选框容器（字段） * `.checkbox__content` - 包裹控件与标签文本的可点击 label * `.checkbox__control` - 复选框控件框 * `.checkbox__indicator` - 复选框勾选指示器 ### 交互状态 复选框同时支持 CSS 伪类与 data 属性： * **Selected**：`[data-selected="true"]` 或 `[aria-checked="true"]`（显示勾选与背景色变化） * **Indeterminate**：`[data-indeterminate="true"]`（显示不确定状态的短横线） * **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]`（显示 danger 色错误状态） * **Hover**：`Checkbox.Control`（按钮）上的 `:hover` 或 `[data-hovered="true"]` * **Focus**：按钮上的 `:focus-visible` 或 `[data-focus-visible="true"]`（控件上显示焦点环） * **Disabled**：字段上的 `[data-disabled="true"]`（降低透明度，包括帮助文本） * **Pressed**：`:active` 或 `[data-pressed="true"]` ## API 参考 ### Checkbox 继承自 [React Aria CheckboxField](https://react-spectrum.adobe.com/react-aria/Checkbox.html)。 | Prop | 类型 | 默认值 | 描述 | | -------------------- | -------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------- | | `isSelected` | `boolean` | `false` | 是否选中 | | `defaultSelected` | `boolean` | `false` | 默认是否选中（非受控） | | `isIndeterminate` | `boolean` | `false` | 是否处于不确定状态 | | `isDisabled` | `boolean` | `false` | 是否禁用 | | `isInvalid` | `boolean` | `false` | 是否无效 | | `isReadOnly` | `boolean` | `false` | 是否只读 | | `isRequired` | `boolean` | `false` | 是否必须选中 | | `validate` | `(value: boolean) => ValidationError \| true \| null \| undefined` | - | 自定义验证函数 | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单验证还是 ARIA | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 | | `name` | `string` | - | 提交 HTML 表单时 input 元素的名称 | | `value` | `string` | - | 提交 HTML 表单时 input 元素的值 | | `onChange` | `(isSelected: boolean) => void` | - | 值变化时的回调 | | `children` | `React.ReactNode \| (values: CheckboxFieldRenderProps) => React.ReactNode` | - | 内容或字段 render prop | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxFieldRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Checkbox.Content 可点击的 `<label>`，包裹控件与标签文本。将 `Checkbox.Control` 与 `Label` 放在其中；`Description`/`FieldError` 作为 `Checkbox.Content` 的兄弟节点。无标签的复选框可省略 `Label`，并在 `Checkbox` 上传递 `aria-label`。 | Prop | 类型 | 默认值 | 描述 | | ----------- | --------------------------------------------------------------------------- | --- | ---------------------------- | | `children` | `React.ReactNode \| (values: CheckboxButtonRenderProps) => React.ReactNode` | - | 按钮内容（控件 + 标签）或按钮 render prop | | `className` | `string \| (values: CheckboxButtonRenderProps) => string` | - | 应用于可点击 label 的类 | ### CheckboxFieldRenderProps 在根 `Checkbox` 上使用 render prop 时，提供以下字段级值： | Prop | 类型 | 描述 | | ----------------- | --------- | --------- | | `isSelected` | `boolean` | 是否当前选中 | | `isIndeterminate` | `boolean` | 是否处于不确定状态 | | `isDisabled` | `boolean` | 是否禁用 | | `isReadOnly` | `boolean` | 是否只读 | | `isInvalid` | `boolean` | 是否无效 | | `isRequired` | `boolean` | 是否必填 | ### CheckboxButtonRenderProps `Checkbox.Control` 与 `Checkbox.Indicator` 使用按钮级 render props（`isHovered`、`isPressed`、`isFocusVisible` 等）。将函数作为 `Checkbox.Control` 子节点或传给 `Checkbox.Indicator` 以访问它们。 ## 相关组件 ## Related Components * **Label**: Accessible label for form controls * **CheckboxGroup**: Group of checkboxes with shared state * **Description**: Helper text for form fields </page> <page url="/cn/docs/react/components/description"> # Description 描述 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/description **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/description.mdx > 为表单字段及其他组件提供补充说明文本 ## 用法 ```tsx import { Description } from '@heroui/react'; ``` ```tsx import {Description, Input, Label} from "@heroui/react"; export function Basic() { return ( <div className="flex flex-col gap-1"> <Label htmlFor="email">邮箱</Label> <Input aria-describedby="email-description" className="w-64" id="email" placeholder="you@example.com" type="email" /> <Description id="email-description">我们不会将你的邮箱分享给任何人。</Description> </div> ); } ``` ## 示例 ### 搭配表单字段 ```tsx <div className="flex flex-col gap-1"> <Label htmlFor="password">Password</Label> <Input id="password" type="password" aria-describedby="password-description" /> <Description id="password-description"> 至少 8 个字符，且包含一个大写字母 </Description> </div> ``` ### 与 TextField 配合 ```tsx import {TextField, Label, Input, Description} from '@heroui/react'; <TextField type="email"> <Label>Email</Label> <Input placeholder="Enter your email" /> <Description>We'll never share your email</Description> </TextField> ``` 使用 [TextField](./text-field) 组件时，无障碍属性会自动应用到标签与描述。 ## 自定义样式 ### Tailwind CSS ```tsx import {Description, Input, Label} from "@heroui/react"; export function CustomStyles() { return ( <div className="flex w-64 flex-col gap-1"> <Label htmlFor="workspace-slug">工作区 URL</Label> <Input id="workspace-slug" placeholder="acme" type="text" /> <Description className="leading-relaxed tracking-wide" id="workspace-slug-hint"> 仅支持小写字母和连字符。将用于 app.heroui.com/acme </Description> </div> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Description 组件类。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .description { @apply text-muted; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Description 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/description.css)）： #### 基础类 \[!toc] * `.description` - 基础描述样式，使用 `muted` 文本颜色 ## API 参考 ### Description | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | -------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode` | - | 描述内容 | ## 无障碍 Description 组件通过以下方式增强无障碍性： * 使用屏幕阅读器可识别的语义化 HTML * 提供 `slot="description"` 属性以集成 React Aria * 支持适当的文本对比度 ## 相关组件 ## 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 </page> <page url="/cn/docs/react/components/error-message"> # ErrorMessage 错误消息 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/error-message **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/error-message.mdx > 用于展示错误的底层错误消息组件 ## 用法 ```tsx import { ErrorMessage } from '@heroui/react'; ``` ```tsx "use client"; import type {Key} from "@heroui/react"; import {Description, ErrorMessage, Label, Tag, TagGroup} from "@heroui/react"; import {useMemo, useState} from "react"; export function ErrorMessageBasic() { const [selected, setSelected] = useState<Iterable<Key>>(new Set()); const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]); return ( <TagGroup selectedKeys={selected} selectionMode="multiple" onSelectionChange={(keys) => setSelected(keys)} > <Label>必选分类</Label> <TagGroup.List> <Tag id="news">新闻</Tag> <Tag id="travel">旅游</Tag> <Tag id="gaming">游戏</Tag> <Tag id="shopping">购物</Tag> </TagGroup.List> <Description>请至少选择一个分类</Description> <ErrorMessage>{!!isInvalid && <>请至少选择一个分类</>}</ErrorMessage> </TagGroup> ); } ``` `ErrorMessage` 是基于 React Aria `Text` 组件、`errorMessage` slot 的底层组件，用于在 **非表单组件**（如 `TagGroup`、`Calendar` 及其他集合类组件）中展示错误消息。 ## 组件结构 ```tsx import { TagGroup, Tag, Label, Description, ErrorMessage } from '@heroui/react'; <TagGroup> <Label /> <TagGroup.List> <Tag /> </TagGroup.List> <Description /> <ErrorMessage /> </TagGroup> ``` ## 何时使用 `ErrorMessage` **不绑定表单**，是用于非表单上下文的通用错误展示组件。 * **推荐用于** 非表单组件（如 `TagGroup`、`Calendar`、集合类组件） * **表单字段** 建议使用 [`FieldError`](/docs/react/components/field-error)，它提供表单专用校验特性与自动错误处理，遵循标准化表单校验模式。 ## ErrorMessage 与 FieldError | 组件 | 使用场景 | 表单集成 | 示例组件 | | -------------- | -------- | ---- | ---------------------------------- | | `ErrorMessage` | 非表单组件 | 否 | `TagGroup`、`Calendar` | | `FieldError` | 表单字段（推荐） | 是 | `TextField`、`NumberField`、`Select` | 表单校验建议使用 `FieldError`，它遵循标准化表单校验模式并提供表单专用特性。参见 [FieldError 文档](/docs/react/components/field-error) 与 [Form 指南](/docs/react/components/form)。 ## 自定义样式 ### Tailwind CSS ```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 CustomStyles() { const [selected, setSelected] = useState<Iterable<Key>>(new Set()); const isInvalid = useMemo(() => Array.from(selected).length === 0, [selected]); return ( <TagGroup className="w-full max-w-xs gap-1.5" selectedKeys={selected} selectionMode="multiple" onSelectionChange={setSelected} > <Label>主题</Label> <TagGroup.List> <Tag id="api">API</Tag> <Tag id="design">设计</Tag> <Tag id="docs">文档</Tag> </TagGroup.List> <Description>请至少选择一个主题</Description> <ErrorMessage className="font-medium text-danger"> {!!isInvalid && <>请至少选择一个主题</>} </ErrorMessage> </TagGroup> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 ErrorMessage 组件类。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .error-message { @apply text-sm font-medium text-danger; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ErrorMessage 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/error-message.css)）： #### 基础类 \[!toc] * `.error-message` - 基础错误消息样式，danger 色与文本截断 #### 插槽类 \[!toc] * `[slot="errorMessage"]` - 用于 React Aria 集成的 ErrorMessage slot 样式 ## API 参考 ### ErrorMessage | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | -------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode` | - | 错误消息内容 | ## 说明 `ErrorMessage` 基于 React Aria 的 `Text` 组件，`slot="errorMessage"`。可通过 `[slot=errorMessage]` CSS 选择器定位。 ## 无障碍 ErrorMessage 组件通过以下方式增强无障碍性： * 使用屏幕阅读器可识别的语义化 HTML * 提供 `slot="errorMessage"` 属性以集成 React Aria * 错误状态支持适当的文本对比度 * 遵循 WAI-ARIA 错误消息最佳实践 ## 相关组件 ## Related Components * **TagGroup**: Focusable list of tags with selection and removal support </page> <page url="/cn/docs/react/components/field-error"> # FieldError 字段错误 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/field-error **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/field-error.mdx > 展示表单字段校验错误消息 ## 用法 ```tsx import { FieldError } from '@heroui/react'; ``` ```tsx "use client"; import {FieldError, Input, Label, TextField} from "@heroui/react"; import {useState} from "react"; export function Basic() { const [value, setValue] = useState("jr"); const isInvalid = value.length > 0 && value.length < 3; return ( <TextField className="w-64" isInvalid={isInvalid}> <Label htmlFor="username">用户名</Label> <Input id="username" placeholder="输入用户名" value={value} onChange={(e) => setValue(e.target.value)} /> <FieldError>用户名至少需要 3 个字符</FieldError> </TextField> ); } ``` FieldError 组件展示表单字段的校验错误消息。当父字段标记为无效时自动显示，并提供平滑的透明度过渡。 ## 示例 ### 基础校验 ```tsx export function Basic() { const [value, setValue] = useState(""); const isInvalid = value.length > 0 && value.length < 3; return ( <TextField className="w-64" isInvalid={isInvalid}> <Label htmlFor="username">Username</Label> <Input id="username" placeholder="Enter username" value={value} onChange={(e) => setValue(e.target.value)} /> <FieldError>Username must be at least 3 characters</FieldError> </TextField> ); } ``` ### 动态错误信息 ```tsx <TextField isInvalid={errors.length > 0}> <Label>Password</Label> <Input type="password" /> <FieldError> {(validation) => validation.validationErrors.join(', ')} </FieldError> </TextField> ``` ### 自定义校验逻辑 ```tsx function EmailField() { const [email, setEmail] = useState(''); const isInvalid = email.length > 0 && !email.includes('@'); return ( <TextField isInvalid={isInvalid}> <Label>Email</Label> <Input type="email" value={email} onChange={(e) => setEmail(e.target.value)} /> <FieldError>Email must include @ symbol</FieldError> </TextField> ); } ``` ### 多条错误信息 ```tsx <TextField isInvalid={hasErrors}> <Label>Username</Label> <Input /> <FieldError> {errors.map((error, i) => ( <div key={i}>{error}</div> ))} </FieldError> </TextField> ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {FieldError, Input, Label, TextField} from "@heroui/react"; import {useState} from "react"; export function CustomStyles() { const [value, setValue] = useState("jr"); const isInvalid = value.length > 0 && value.length < 3; return ( <TextField className="w-64" isInvalid={isInvalid}> <Label htmlFor="handle">用户名</Label> <Input className="bg-field font-mono" id="handle" placeholder="至少 3 个字符" value={value} onChange={(e) => setValue(e.target.value)} /> <FieldError className="font-medium">用户名至少需要 3 个字符</FieldError> </TextField> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 FieldError 组件类。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .field-error { @apply font-medium text-danger; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 FieldError 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/field-error.css)）： #### 基础类 \[!toc] * `.field-error` - 基础错误样式，danger 色 * 仅在存在 `data-visible` 属性时显示 * 长消息以省略号截断 ## API 参考 ### FieldError | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------ | --- | ----------------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode \| ((validation: ValidationResult) => ReactNode)` | - | 错误消息内容或 render 函数 | ## 无障碍 FieldError 组件通过以下方式确保无障碍性： * 使用适当的 ARIA 属性播报错误 * 语义化 HTML 支持屏幕阅读器 * 提供视觉与程序化错误指示 * 根据校验状态自动管理可见性 ## 相关组件 ## 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 </page> <page url="/cn/docs/react/components/fieldset"> # Fieldset 字段组 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/fieldset **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/fieldset.mdx > 将相关表单控件与图例、描述和操作组合在一起 ## 用法 ```tsx import { Fieldset } from '@heroui/react'; ``` ```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.SyntheticEvent<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("表单提交成功！"); }; return ( <Form className="w-full max-w-96" onSubmit={onSubmit}> <Fieldset> <Fieldset.Legend>个人资料设置</Fieldset.Legend> <Description>更新你的个人资料信息。</Description> <FieldGroup> <TextField isRequired name="name" validate={(value) => { if (value.length < 3) { return "姓名至少需要 3 个字符"; } return null; }} > <Label>姓名</Label> <Input placeholder="John Doe" /> <FieldError /> </TextField> <TextField isRequired name="email" type="email"> <Label>邮箱</Label> <Input placeholder="john@example.com" /> <FieldError /> </TextField> <TextField isRequired name="bio" validate={(value) => { if (value.length < 10) { return "简介至少需要 10 个字符"; } return null; }} > <Label>简介</Label> <TextArea placeholder="介绍一下你自己…" /> <Description>至少 10 个字符</Description> <FieldError /> </TextField> </FieldGroup> <Fieldset.Actions> <Button type="submit"> <FloppyDisk /> 保存更改 </Button> <Button type="reset" variant="secondary"> 取消 </Button> </Fieldset.Actions> </Fieldset> </Form> ); } ``` ## 组件结构 ```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> ) ``` ## 示例 ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请在表单控件（Input、TextArea 等）上使用 `variant="secondary"`，以应用适合 Surface 背景的低强调变体。 ```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.SyntheticEvent<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("表单提交成功！"); }; 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>个人资料设置</Fieldset.Legend> <Description>更新你的个人资料信息。</Description> <Fieldset.Group> <TextField isRequired name="name" validate={(value) => { if (value.length < 3) { return "姓名至少需要 3 个字符"; } return null; }} > <Label>姓名</Label> <Input placeholder="John Doe" variant="secondary" /> <FieldError /> </TextField> <TextField isRequired name="email" type="email"> <Label>邮箱</Label> <Input placeholder="john@example.com" variant="secondary" /> <FieldError /> </TextField> <TextField isRequired name="bio" validate={(value) => { if (value.length < 10) { return "简介至少需要 10 个字符"; } return null; }} > <Label>简介</Label> <TextArea placeholder="介绍一下你自己…" variant="secondary" /> <Description>至少 10 个字符</Description> <FieldError /> </TextField> </Fieldset.Group> <Fieldset.Actions> <Button type="submit"> <FloppyDisk /> 保存更改 </Button> <Button type="reset" variant="tertiary"> 取消 </Button> </Fieldset.Actions> </Fieldset> </Form> </Surface> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {FloppyDisk} from "@gravity-ui/icons"; import { Button, Description, FieldError, FieldGroup, Fieldset, Form, Input, Label, TextArea, TextField, } from "@heroui/react"; const shell = "rounded-xl border border-border/70 bg-linear-to-b from-neutral-50/90 to-white p-4 ring-1 ring-black/5 dark:from-neutral-900/80 dark:to-neutral-900 dark:ring-white/10"; const field = "rounded-xl border border-border/80 bg-surface shadow-sm ring-1 ring-black/5 transition-[box-shadow,border-color] focus-visible:ring-2 focus-visible:ring-neutral-400/25 dark:ring-white/10 dark:focus-visible:ring-neutral-500/30"; export function CustomStyles() { const onSubmit = (e: React.SyntheticEvent<HTMLFormElement>) => { e.preventDefault(); alert("表单提交成功！"); }; return ( <Form className="w-full max-w-96" onSubmit={onSubmit}> <Fieldset className={shell}> <Fieldset.Legend className="font-medium text-neutral-800 dark:text-neutral-100"> 个人资料设置 </Fieldset.Legend> <Description className="text-neutral-600 dark:text-neutral-400"> 更新你的个人资料信息。 </Description> <FieldGroup> <TextField isRequired name="name" validate={(value) => { if (value.length < 3) { return "姓名至少需要 3 个字符"; } return null; }} > <Label>姓名</Label> <Input className={field} placeholder="John Doe" /> <FieldError /> </TextField> <TextField isRequired name="email" type="email"> <Label>邮箱</Label> <Input className={field} placeholder="john@example.com" /> <FieldError /> </TextField> <TextField isRequired name="bio" validate={(value) => { if (value.length < 10) { return "简介至少需要 10 个字符"; } return null; }} > <Label>简介</Label> <TextArea className={field} placeholder="介绍一下你自己…" /> <Description>至少 10 个字符</Description> <FieldError /> </TextField> </FieldGroup> <Fieldset.Actions> <Button type="submit"> <FloppyDisk /> 保存更改 </Button> <Button type="reset" variant="secondary"> 取消 </Button> </Fieldset.Actions> </Fieldset> </Form> ); } ``` ### 全局 CSS 使用 `@layer components` 指令定位 Fieldset 的 [BEM](https://getbem.com/) 风格类。 ```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; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Fieldset 复合组件暴露以下 CSS 选择器： #### 基础类 \[!toc] * `.fieldset` – 根容器 * `.fieldset__legend` – 图例元素 * `.fieldset__field-group` – 分组字段包裹层 * `.fieldset__actions` – 字段下方的操作栏 ## API 参考 ### Fieldset | Prop | 类型 | 默认值 | 描述 | | ------------- | ------------------------------------------- | ------------------- | ------------------------ | | `className` | `string` | - | 应用于根元素的 Tailwind CSS 类 | | `children` | `React.ReactNode` | - | Fieldset 内容（图例、分组、描述、操作） | | `nativeProps` | `React.HTMLAttributes<HTMLFieldSetElement>` | 支持原生 fieldset 属性与事件 | | ### Fieldset.Legend | Prop | 类型 | 默认值 | 描述 | | ------------- | ----------------------------------------- | --- | ---------------- | | `className` | `string` | - | 图例元素的 Tailwind 类 | | `children` | `React.ReactNode` | - | 图例内容，通常为纯文本 | | `nativeProps` | `React.HTMLAttributes<HTMLLegendElement>` | - | 原生 legend 属性 | ### Fieldset.Group | Prop | 类型 | 默认值 | 描述 | | ------------- | -------------------------------------- | --- | ------------------ | | `className` | `string` | - | 分组字段的布局与间距类 | | `children` | `React.ReactNode` | - | fieldset 内要分组的表单控件 | | `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | 原生 div 属性 | ### Fieldset.Actions | Prop | 类型 | 默认值 | 描述 | | ------------- | -------------------------------------- | --- | --------------------- | | `className` | `string` | - | 对齐操作按钮或文本的 Tailwind 类 | | `children` | `React.ReactNode` | - | 操作按钮或辅助文本 | | `nativeProps` | `React.HTMLAttributes<HTMLDivElement>` | - | 原生 div 属性 | ## 相关案例 ## 相关组件 ## Related Components * **TextField**: Composition-friendly fields with labels and validation * **Label**: Accessible label for form controls * **CheckboxGroup**: Group of checkboxes with shared state </page> <page url="/cn/docs/react/components/form"> # Form 表单 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/form **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/form.mdx > 用于表单校验与提交处理的包裹组件 ## 用法 ```tsx import { Form } from '@heroui/react'; ``` ```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.SyntheticEvent<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(`表单提交数据：${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 "请输入有效的邮箱地址"; } return null; }} > <Label>邮箱</Label> <Input placeholder="john@example.com" /> <FieldError /> </TextField> <TextField isRequired minLength={8} name="password" type="password" validate={(value) => { if (value.length < 8) { return "密码至少需要 8 个字符"; } if (!/[A-Z]/.test(value)) { return "密码至少需要包含一个大写字母"; } if (!/[0-9]/.test(value)) { return "密码至少需要包含一个数字"; } return null; }} > <Label>密码</Label> <Input placeholder="输入密码" /> <Description>至少 8 个字符，且包含 1 个大写字母和 1 个数字</Description> <FieldError /> </TextField> <div className="flex gap-2"> <Button type="submit"> <Check /> 提交 </Button> <Button type="reset" variant="secondary"> 重置 </Button> </div> </Form> ); } ``` ## 组件结构 ```tsx import {Form, Button} from '@heroui/react'; export default () => ( <Form> {/* Form fields go here */} <Button type="submit"/> <Button type="reset"/> </Form> ) ``` ## 示例 ### 渲染函数 ```tsx "use client"; import {Check} from "@gravity-ui/icons"; import {Button, Description, FieldError, Form, Input, Label, TextField} from "@heroui/react"; export function RenderFunction() { const onSubmit = (e: React.SyntheticEvent<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(`表单提交数据：${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 "请输入有效的邮箱地址"; } return null; }} > <Label>邮箱</Label> <Input placeholder="john@example.com" /> <FieldError /> </TextField> <TextField isRequired minLength={8} name="password" type="password" validate={(value) => { if (value.length < 8) { return "密码至少需要 8 个字符"; } if (!/[A-Z]/.test(value)) { return "密码至少需要包含一个大写字母"; } if (!/[0-9]/.test(value)) { return "密码至少需要包含一个数字"; } return null; }} > <Label>密码</Label> <Input placeholder="输入密码" /> <Description>至少 8 个字符，且包含 1 个大写字母和 1 个数字</Description> <FieldError /> </TextField> <div className="flex gap-2"> <Button type="submit"> <Check /> 提交 </Button> <Button type="reset" variant="secondary"> 重置 </Button> </div> </Form> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {Button, Form, Input, Label, TextField} from "@heroui/react"; export function CustomStyles() { return ( <Form className="flex w-80 flex-col gap-3 rounded-xl border border-border/80 bg-surface p-4 shadow-sm" onSubmit={(e) => e.preventDefault()} > <TextField isRequired name="email" type="email"> <Label>工作邮箱</Label> <Input className="bg-field" placeholder="you@company.com" /> </TextField> <Button className="w-full" type="submit"> 继续 </Button> </Form> ); } ``` ### 全局 CSS 要自定义表单布局与间距，可在 `<Form>` 上使用 `className` prop，或通过 `@layer components` 添加项目级类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 `Form` 渲染原生 `<form>` 元素，聚焦校验与提交。`@heroui/styles` 中无专用 BEM 类——从全局 CSS 应用容器样式，控件级自定义请使用字段组件。 ```css @layer components { .form-layout { @apply flex flex-col gap-4 rounded-xl border border-border bg-surface p-4 shadow-sm; } } ``` ```tsx <Form className="form-layout" onSubmit={handleSubmit}> {/* TextField, Input, Button, etc. */} </Form> ``` 分组字段与共享布局请使用 [Fieldset](./fieldset)，并定位 `.fieldset`、`.fieldset__legend` 等相关类。单个控件请参阅 [TextField](./text-field)、[Input](./input)、[Label](./label)、[FieldError](./field-error) 的 **Global CSS** 部分。 ## 样式参考 HeroUI 对在 `@heroui/styles` 中提供样式的组件遵循 [BEM](https://getbem.com/) 方法论。 `Form` 渲染原生 `<form>` 元素，无专用 BEM 类。通过 `className` 应用布局、间距与表面样式。字段外观与校验状态来自 `TextField`、`Input`、`Label`、`Description`、`FieldError` 等子组件。结构化多字段布局请与 [Fieldset](./fieldset) 组合使用。 ## API 参考 ### Form Form 组件是 React Aria Form 原语的包裹层，提供表单校验与提交处理能力。 | Prop | 类型 | 默认值 | 描述 | | -------------------- | ------------------------------------------------------------------------------ | ---------- | ---------------------------------------------------- | | `action` | `string \| FormHTMLAttributes['action']` | - | 提交表单数据的 URL | | `className` | `string` | - | 应用于 form 元素的 Tailwind CSS 类 | | `children` | `React.ReactNode` | - | 表单内容（字段、按钮等） | | `encType` | `'application/x-www-form-urlencoded' \| 'multipart/form-data' \| 'text/plain'` | - | 表单数据提交的编码类型 | | `method` | `'get' \| 'post'` | - | 提交表单时使用的 HTTP 方法 | | `onInvalid` | `(event: SyntheticEvent<HTMLFormElement>) => void` | - | 表单校验失败时调用。默认聚焦第一个无效字段。使用 `preventDefault()` 可自定义聚焦行为 | | `onReset` | `(event: SyntheticEvent<HTMLFormElement>) => void` | - | 表单重置时调用 | | `onSubmit` | `(event: SyntheticEvent<HTMLFormElement>) => void` | - | 表单提交时调用 | | `target` | `'_self' \| '_blank' \| '_parent' \| '_top'` | - | 提交后显示响应的位置 | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 校验还是 ARIA 校验。`native` 阻止提交，`aria` 实时显示错误 | | `validationErrors` | `ValidationErrors` | - | 按字段名映射的服务端校验错误。立即显示，用户修改字段时清除 | | `aria-label` | `string` | - | 表单的无障碍标签 | | `aria-labelledby` | `string` | - | 标注表单的元素 ID。提供时创建 form landmark | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Form Validation Form 组件集成 React Aria 校验系统，支持： * 使用内置 HTML5 校验属性（`required`、`minLength`、`pattern` 等） * 在 TextField 组件上提供自定义校验函数 * 使用 FieldError 组件展示校验错误 * 在正确校验后处理表单提交 * 通过 `validationErrors` prop 提供服务端校验错误 #### Validation Behavior `validationBehavior` prop 控制校验展示方式： * **`native`**（默认）：使用原生 HTML 校验，有错误时阻止提交 * **`aria`**：使用 ARIA 属性校验，用户输入时实时显示错误，不阻止提交 可在表单级或单个字段级设置此行为。 ### Form Submission 表单可通过多种方式提交： * **传统提交**：设置 `action` prop 提交到 URL * **JavaScript 处理**：使用 `onSubmit` 处理表单数据 * **FormData API**：在 submit 处理函数中使用 FormData API 访问表单数据 FormData 示例： ```tsx import type {SyntheticEvent} from "react"; function handleSubmit(e: SyntheticEvent<HTMLFormElement>) { e.preventDefault(); const formData = new FormData(e.currentTarget); const data = Object.fromEntries(formData); console.log('Form data:', data); } ``` ### Integration with Form Fields Form 组件与 HeroUI 表单字段组件无缝协作： * **TextField**：带标签与校验的文本输入 * **Checkbox**：布尔选择 * **RadioGroup**：多选一 * **Switch**：开关控件 * **Button**：提交与重置操作 所有字段组件放在 Form 内时会自动集成 Form 的校验与提交行为。 ### Advanced Usage 更高级用法包括： * 自定义校验上下文 * 表单 context provider * 与第三方库集成 * 校验错误时的自定义焦点管理 请参阅 [React Aria Form 文档](https://react-spectrum.adobe.com/react-aria/Form.html)。 ## 无障碍 使用 React Aria 组件时，表单默认可访问。主要特性包括： * 原生 `<form>` 元素语义 * 使用 `aria-label` 或 `aria-labelledby` 创建 form landmark * 校验错误时自动焦点管理 * 使用 `validationBehavior="aria"` 时的 ARIA 校验属性 ## 相关案例 ## 相关组件 ## 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 </page> <page url="/cn/docs/react/components/input-group"> # InputGroup 输入框组 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/input-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/input-group.mdx > 将相关输入控件与前后缀元素组合，以增强表单字段 ## 用法 ```tsx import { InputGroup } from '@heroui/react'; ``` ```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>邮箱地址</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> ); } ``` ## 组件结构 ```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** 使用可选的前缀与后缀包裹输入框，形成视觉上统一的组合。通常放在 **[TextField](/docs/react/components/text-field)** 内，用于在输入前后添加图标、文字、按钮等元素。单行输入请使用 **InputGroup.Input**，多行输入请使用 **InputGroup.TextArea**。 ## 示例 ### 变体 InputGroup 组件支持两种视觉变体： * **`primary`**（默认）- 标准样式带阴影，适用于大多数场景 * **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内 ```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>主要变体</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>次要变体</Label> <InputGroup variant="secondary"> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input placeholder="name@email.com" /> </InputGroup> </TextField> </div> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。 ```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>邮箱地址</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>我们不会将此邮箱分享给任何人</Description> </TextField> </Surface> ); } ``` ### 后缀加载状态 在后缀显示加载 spinner 以表示正在处理。 ```tsx "use client"; import {InputGroup, Spinner, TextField} from "@heroui/react"; export function WithLoadingSuffix() { return ( <TextField className="w-full max-w-[280px]" defaultValue="发送中…" name="status"> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" /> <InputGroup.Suffix> <Spinner className="size-4" /> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### 必填字段 InputGroup 会遵循父级 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>邮箱地址</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>设置价格</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>客户将支付的价格</Description> </TextField> </div> ); } ``` ### 禁用状态 InputGroup 会遵循父级 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>邮箱地址</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>设置价格</Label> <InputGroup> <InputGroup.Prefix>$</InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[200px]" type="number" /> <InputGroup.Suffix>USD</InputGroup.Suffix> </InputGroup> </TextField> </div> ); } ``` ### 宽度充满 ```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>邮箱地址</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>密码</Label> <InputGroup fullWidth> <InputGroup.Input placeholder="输入密码" type="password" /> <InputGroup.Suffix> <Eye className="size-4 text-muted" /> </InputGroup.Suffix> </InputGroup> </TextField> </div> ); } ``` ### 文字前缀 使用文字作为前缀，例如货币符号或协议前缀。 ```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>网站</Label> <InputGroup> <InputGroup.Prefix>https://</InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[280px]" /> </InputGroup> </TextField> ); } ``` ### 文字后缀 使用文字作为后缀，例如域名后缀或单位。 ```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>网站</Label> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" /> <InputGroup.Suffix>.com</InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### 图标前缀与文字后缀 组合图标前缀与文字后缀。 ```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>网站</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> ); } ``` ### 复制按钮后缀 在后缀中加入交互按钮，例如复制按钮。 ```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>网站</Label> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" /> <InputGroup.Suffix className="pe-0"> <Button isIconOnly aria-label="复制" size="sm" variant="ghost"> <Copy className="size-4" /> </Button> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### 图标前缀与复制按钮 组合图标前缀与交互式后缀按钮。 ```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>网站</Label> <InputGroup> <InputGroup.Prefix> <Globe className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[280px]" /> <InputGroup.Suffix className="pe-0"> <Button isIconOnly aria-label="复制" size="sm" variant="ghost"> <Copy className="size-4" /> </Button> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### 密码可见性切换 在后缀中使用按钮切换密码可见性。 ```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>密码</Label> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" type={isVisible ? "text" : "password"} value={isVisible ? "87$2h.3diua" : "••••••••"} /> <InputGroup.Suffix className="pe-0"> <Button isIconOnly aria-label={isVisible ? "隐藏密码" : "显示密码"} size="sm" variant="ghost" onPress={() => setIsVisible(!isVisible)} > {isVisible ? <Eye className="size-4" /> : <EyeSlash className="size-4" />} </Button> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### 键盘快捷键 使用 [Kbd](/docs/react/components/kbd) 组件展示键盘快捷键。 ```tsx "use client"; import {InputGroup, Kbd, TextField} from "@heroui/react"; export function WithKeyboardShortcut() { return ( <TextField aria-label="命令" className="w-full max-w-[280px]" name="command"> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" placeholder="命令" /> <InputGroup.Suffix className="pe-2"> <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>K</Kbd.Content> </Kbd> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### 徽章后缀 在后缀中加入徽章或 chip，用于展示状态或标签。 ```tsx "use client"; import {Chip, InputGroup, TextField} from "@heroui/react"; export function WithBadgeSuffix() { return ( <TextField aria-label="邮箱地址" className="w-full max-w-[280px]" name="email"> <InputGroup> <InputGroup.Input className="w-full max-w-[280px]" placeholder="邮箱地址" /> <InputGroup.Suffix className="pe-2"> <Chip color="accent" size="md" variant="soft"> Pro </Chip> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### 表单校验 InputGroup 会自动反映父级 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>邮箱地址</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>请输入有效的邮箱地址</FieldError> </TextField> <TextField isInvalid isRequired className="w-full max-w-[280px]" name="price"> <Label>设置价格</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>价格必须大于 0</FieldError> </TextField> </div> ); } ``` ### 前缀图标 在输入框前添加图标。 ```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>邮箱地址</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>我们不会将此邮箱分享给任何人</Description> </TextField> ); } ``` ### 后缀图标 在输入框后添加图标。 ```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>邮箱地址</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>我们不会发送垃圾邮件</Description> </TextField> ); } ``` ### 前缀与后缀 同时组合前缀与后缀。 ```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>设置价格</Label> <InputGroup> <InputGroup.Prefix>$</InputGroup.Prefix> <InputGroup.Input className="w-full max-w-[200px]" type="number" /> <InputGroup.Suffix>USD</InputGroup.Suffix> </InputGroup> <Description>客户将支付的价格</Description> </TextField> ); } ``` ### 文本域 多行输入请使用 **InputGroup.TextArea**，并搭配前缀与后缀。当存在 textarea 时，容器高度会自动适应内容，并将前缀/后缀与顶部对齐。 ```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="提示输入" 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="添加上下文" size="sm" variant="outline"> <At /> 添加上下文 </Button> </InputGroup.Prefix> <InputGroup.TextArea className="w-full resize-none px-3.5 py-0" placeholder="分配任务或提问…" 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="附加文件" size="sm" variant="tertiary"> <Plus /> </Button> <Tooltip.Content> <p className="text-xs">添加文件等</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Button isIconOnly aria-label="连接应用" size="sm" variant="tertiary"> <PlugConnection /> </Button> <Tooltip.Content> <p className="text-xs">连接应用</p> </Tooltip.Content> </Tooltip> <div className="ms-auto flex items-center gap-1.5"> <Tooltip delay={0}> <Button isIconOnly aria-label="语音输入" size="sm" variant="ghost"> <Microphone /> </Button> <Tooltip.Content> <p className="text-xs">语音输入</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Button isIconOnly aria-label="发送提示" 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">发送</p> <Kbd className="h-4 rounded-sm px-1"> <Kbd.Abbr keyValue="enter" /> </Kbd> </Tooltip.Content> </Tooltip> </div> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### 用法示例 ```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 aria-label="Confirm" size="sm" variant="ghost"> <Icon icon="gravity-ui:check" /> </Button> </InputGroup.Suffix> </InputGroup> </TextField> ); } ``` ### 文本域用法示例 ```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> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {Envelope} from "@gravity-ui/icons"; import {InputGroup, Label, TextField} from "@heroui/react"; export function CustomStyles() { return ( <TextField className="w-full max-w-xs" name="email"> <Label>工作邮箱</Label> <InputGroup className="rounded-xl border border-border/80 bg-default shadow-sm"> <InputGroup.Prefix> <Envelope className="size-4 text-muted" /> </InputGroup.Prefix> <InputGroup.Input placeholder="you@company.com" /> </InputGroup> </TextField> ); } ``` ### 全局 CSS InputGroup 使用可自定义的 CSS 类。覆盖组件类以匹配设计系统。 ```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); } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 #### 基础类 \[!toc] * `.input-group` – 根容器：带边框、背景与 flex 布局。默认 `min-h-9` 与 `items-center`；存在 textarea 时切换为 `items-start` * `.input-group__input` – 透明背景、无边框的输入元素。textarea 也使用该基础类 * `.input-group__prefix` – 左侧圆角的前缀容器。与 textarea 搭配时与顶部对齐 * `.input-group__suffix` – 右侧圆角的后缀容器。与 textarea 搭配时与顶部对齐 #### 变体类 \[!toc] * `.input-group--primary` – 带阴影的主变体（默认） * `.input-group--secondary` – 无阴影的次变体，适用于 Surface 内 **Note：** 使用 `InputGroup.TextArea` 时，容器从 `items-center` 切换为 `items-start`，并使用 `height: auto` 替代固定高度。前缀与后缀与顶部对齐，并增加内边距以匹配 textarea 的垂直内边距。textarea 使用相同的 `.input-group__input` 基础类，并通过 `[data-slot="input-group-textarea"]` 选择器应用 textarea 专用样式（最小高度与纵向 resize）。 ### 交互状态 InputGroup 会根据状态自动管理以下 data 属性： * **Hover**：`[data-hovered]` - 悬停在组合上时应用 * **Focus Within**：`[data-focus-within]` - 输入聚焦时应用 * **Invalid**：`[data-invalid]` - 父级 TextField 无效时应用 * **Disabled**：`[data-disabled]` 或 `[aria-disabled]` - 父级 TextField 禁用时应用 ## API 参考 ### InputGroup InputGroup 继承 React Aria [Group](https://react-spectrum.adobe.com/react-aria/Group.html) 组件的全部 props。 #### Base Props | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------------------------------------------------------- | ------- | -------------------------------------------- | | `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | 子组件（Input、TextArea、Prefix、Suffix）或 render 函数 | | `className` | `string \| (values: GroupRenderProps) => string` | - | CSS 类，支持 render props | | `style` | `React.CSSProperties \| (values: GroupRenderProps) => React.CSSProperties` | - | 行内样式，支持 render props | | `fullWidth` | `boolean` | `false` | 输入组是否占满容器宽度 | | `id` | `string` | - | 元素唯一标识符 | #### Variant Props | Prop | 类型 | 默认值 | 描述 | | --------- | -------------------------- | ----------- | --------------------------------------------------------- | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 | #### Accessibility Props | Prop | 类型 | 默认值 | 描述 | | ------------------ | --------------------------------------- | --------- | --------------------------------------------- | | `aria-label` | `string` | - | 无可见标签时的无障碍标签 | | `aria-labelledby` | `string` | - | 标注该组的元素 ID | | `aria-describedby` | `string` | - | 描述该组的元素 ID | | `aria-details` | `string` | - | 包含更多详情的元素 ID | | `role` | `'group' \| 'region' \| 'presentation'` | `'group'` | 分组的无障碍角色。重要内容用 `region`，纯视觉分组用 `presentation` | ### Composition Components InputGroup 与以下子组件配合使用： * **InputGroup.Root** - 根容器（也可写作 `InputGroup`） * **InputGroup.Input** - 单行输入元素组件 * **InputGroup.TextArea** - 多行 textarea 元素组件 * **InputGroup.Prefix** - 前缀容器组件 * **InputGroup.Suffix** - 后缀容器组件 #### InputGroup.Input InputGroup.Input 继承 React Aria [Input](https://react-spectrum.adobe.com/react-aria/Input.html) 组件的全部 props。 | Prop | 类型 | 默认值 | 描述 | | -------------- | -------------------------- | ----------- | --------------------------- | | `className` | `string` | - | CSS 类 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 输入视觉变体 | | `type` | `string` | `'text'` | 输入类型（text、password、email 等） | | `value` | `string` | - | 当前值（受控） | | `defaultValue` | `string` | - | 默认值（非受控） | | `placeholder` | `string` | - | 占位文本 | | `disabled` | `boolean` | - | 是否禁用 | | `readOnly` | `boolean` | - | 是否只读 | #### InputGroup.TextArea InputGroup.TextArea 继承 React Aria [TextArea](https://react-spectrum.adobe.com/react-aria/TextArea.html) 组件的全部 props。 | Prop | 类型 | 默认值 | 描述 | | -------------- | -------------------------- | ----------- | ------------- | | `className` | `string` | - | CSS 类 | | `variant` | `"primary" \| "secondary"` | `"primary"` | textarea 视觉变体 | | `value` | `string` | - | 当前值（受控） | | `defaultValue` | `string` | - | 默认值（非受控） | | `placeholder` | `string` | - | 占位文本 | | `rows` | `number` | - | 可见文本行数 | | `disabled` | `boolean` | - | 是否禁用 | | `readOnly` | `boolean` | - | 是否只读 | #### InputGroup.Prefix | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ------------ | | `children` | `React.ReactNode` | - | 前缀内容（图标、文字等） | | `className` | `string` | - | CSS 类 | #### InputGroup.Suffix | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | --------------- | | `children` | `React.ReactNode` | - | 后缀内容（图标、按钮、徽章等） | | `className` | `string` | - | CSS 类 | ## 相关案例 ## 相关组件 ## 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 </page> <page url="/cn/docs/react/components/input-otp"> # InputOTP 一次性密码输入 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/input-otp **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/input-otp.mdx > 用于验证码与安全认证的一次性密码输入组件 ## 用法 ```tsx import { InputOTP } from '@heroui/react'; ``` ```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>验证账户</Label> <p className="text-sm text-muted">我们已向 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">没有收到验证码？</p> <Link className="text-foreground underline" href="#"> 重新发送 </Link> </div> </div> ); } ``` ## 组件结构 ```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** 基于 [@guilherme\_rodz](https://twitter.com/guilherme_rodz) 的 [input-otp](https://github.com/guilhermerodz/input-otp) 构建，为 OTP 输入组件提供灵活且无障碍的基础。 ## 示例 ### 变体 InputOTP 组件支持两种视觉变体： * **`primary`**（默认）- 标准样式带阴影，适用于大多数场景 * **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内 ```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>主要变体</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>次要变体</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> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。 ```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>验证账户</Label> <p className="text-sm text-muted">我们已向 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">没有收到验证码？</p> <Link className="text-foreground underline" href="#"> 重新发送 </Link> </div> </Surface> ); } ``` ### 禁用状态 ```tsx import {Description, InputOTP, Label} from "@heroui/react"; export function Disabled() { return ( <div className="flex w-[280px] flex-col gap-2"> <Label isDisabled>验证账户</Label> <Description>验证码校验当前已禁用</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> ); } ``` ### 四位验证码 ```tsx import {InputOTP, Label} from "@heroui/react"; export function FourDigits() { return ( <div className="flex w-[280px] flex-col gap-2"> <Label>输入 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> ); } ``` ### 受控组件 控制 value 以与状态同步、清空输入或实现自定义校验。 ```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>验证账户</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.length}/6) •{" "} <button className="font-medium text-foreground underline" onClick={() => setValue("")}> Clear </button> </> ) : ( "请输入 6 位验证码" )} </Description> </div> ); } ``` ### 输入完成回调 使用 `onComplete` 回调在所有 slot 填满时触发操作。 ```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.SyntheticEvent<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>验证账户</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" /> 验证中… </> ) : ( "验证验证码" )} </Button> </Form> ); } ``` ### 表单示例 完整的双因素认证表单，含校验与提交。 ```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.SyntheticEvent<HTMLFormElement>) => { e.preventDefault(); setError(""); if (value.length !== 6) { setError("请输入全部 6 位数字"); return; } setIsSubmitting(true); // Simulate API call setTimeout(() => { if (value === "123456") { console.log("Code verified successfully!"); setValue(""); } else { setError("验证码无效，请重试。"); } setIsSubmitting(false); }, 1500); }; return ( <Form className="flex w-[280px] flex-col gap-4" onSubmit={handleSubmit}> <div className="flex flex-col gap-2"> <Label>双重身份验证</Label> <Description>请输入身份验证器应用中的 6 位验证码</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" /> 验证中… </> ) : ( "验证" )} </Button> <div className="flex items-center justify-center gap-1"> <p className="text-sm text-muted">遇到问题？</p> <Link className="text-sm text-foreground underline" href="#"> 使用备用码 </Link> </div> </Form> ); } ``` ### 限定格式 使用 `pattern` prop 限制输入字符。HeroUI 导出 `REGEXP_ONLY_CHARS`、`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>输入验证码（仅字母）</Label> <Description>仅允许输入字母</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> ); } ``` ### 带校验 配合 `isInvalid` 与校验消息展示错误。 ```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.SyntheticEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const code = formData.get("code"); if (code !== "123456") { setIsInvalid(true); return; } setIsInvalid(false); setValue(""); alert("验证码校验成功！"); }; 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>验证账户</Label> <Description>提示：验证码为 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"> 验证码无效，请重试。 </span> <Button isDisabled={value.length !== 6} type="submit"> 提交 </Button> </Form> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {InputOTP, Label, Link} from "@heroui/react"; const slotClass = "rounded-lg border-border/80 bg-default data-[active=true]:border-accent/40 data-[active=true]:bg-accent-soft"; export function CustomStyles() { return ( <div className="flex w-72 flex-col gap-2"> <Label>验证账户</Label> <InputOTP maxLength={6}> <InputOTP.Group> <InputOTP.Slot className={slotClass} index={0} /> <InputOTP.Slot className={slotClass} index={1} /> <InputOTP.Slot className={slotClass} index={2} /> </InputOTP.Group> <InputOTP.Separator className="bg-border" /> <InputOTP.Group> <InputOTP.Slot className={slotClass} index={3} /> <InputOTP.Slot className={slotClass} index={4} /> <InputOTP.Slot className={slotClass} index={5} /> </InputOTP.Group> </InputOTP> <Link className="text-sm text-link" href="#"> 重新发送 </Link> </div> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 InputOTP 组件类。 [了解更多](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-accent-500 ring-2 ring-accent-200; } .input-otp__separator { @apply w-2 h-1 bg-border-strong rounded-full; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 InputOTP 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/input-otp.css)）： #### 基础类 \[!toc] * `.input-otp` - 基础容器 * `.input-otp__container` - input-otp 库的内部容器 * `.input-otp__group` - slot 组 * `.input-otp__slot` - 单个输入 slot * `.input-otp__slot-value` - slot 内的字符 * `.input-otp__caret` - 闪烁光标指示器 * `.input-otp__separator` - 组之间的视觉分隔符 #### 状态类 \[!toc] * `.input-otp__slot[data-active="true"]` - 当前激活的 slot * `.input-otp__slot[data-filled="true"]` - 含字符的 slot * `.input-otp__slot[data-disabled="true"]` - 禁用的 slot * `.input-otp__slot[data-invalid="true"]` - 无效的 slot * `.input-otp__container[data-disabled="true"]` - 禁用的容器 ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Hover**：slot 上 `:hover` 或 `[data-hovered="true"]` * **Active**：slot 上 `[data-active="true"]`（当前聚焦） * **Filled**：slot 上 `[data-filled="true"]`（含字符） * **Disabled**：容器与 slot 上 `[data-disabled="true"]` * **Invalid**：slot 上 `[data-invalid="true"]` ## API 参考 ### InputOTP InputOTP 基于 [input-otp](https://github.com/guilhermerodz/input-otp) 库构建，并附加额外特性。 #### Base Props | Prop | 类型 | 默认值 | 描述 | | -------------------- | -------------------------- | ----------- | --------------------------------------------------------- | | `maxLength` | `number` | - | **必填。** 输入 slot 数量 | | `value` | `string` | - | 受控值（未提供则为非受控） | | `onChange` | `(value: string) => void` | - | 值变化时的回调 | | `onComplete` | `(value: string) => void` | - | 所有 slot 填满时的回调 | | `className` | `string` | - | 容器的附加 CSS 类 | | `containerClassName` | `string` | - | 内部容器的 CSS 类 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 | | `children` | `React.ReactNode` | - | InputOTP.Group、InputOTP.Slot 与 InputOTP.Separator 组件 | #### Validation Props | Prop | 类型 | 默认值 | 描述 | | ------------------- | --------------- | ------- | ----------- | | `isDisabled` | `boolean` | `false` | 是否禁用 | | `isInvalid` | `boolean` | `false` | 是否处于无效状态 | | `validationErrors` | `string[]` | - | 服务端或自定义校验错误 | | `validationDetails` | `ValidityState` | - | HTML5 校验详情 | #### Input Props | Prop | 类型 | 默认值 | 描述 | | ------------------ | --------------------------------------------------------------------------- | ----------- | --------------------------------- | | `pattern` | `string` | - | 允许字符的正则模式（如 `REGEXP_ONLY_DIGITS`） | | `textAlign` | `'left' \| 'center' \| 'right'` | `'left'` | slot 内文本对齐 | | `inputMode` | `'numeric' \| 'text' \| 'decimal' \| 'tel' \| 'search' \| 'email' \| 'url'` | `'numeric'` | 移动设备虚拟键盘类型 | | `placeholder` | `string` | - | 空 slot 的占位文本 | | `pasteTransformer` | `(text: string) => string` | - | 转换粘贴文本（如移除连字符） | #### Form Props | Prop | 类型 | 默认值 | 描述 | | ----------- | --------- | --- | --------------- | | `name` | `string` | - | 表单提交的 name 属性 | | `autoFocus` | `boolean` | - | 挂载时是否聚焦第一个 slot | ### InputOTP.Group | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ---------------- | | `className` | `string` | - | 组的附加 CSS 类 | | `children` | `React.ReactNode` | - | InputOTP.Slot 组件 | ### InputOTP.Slot | Prop | 类型 | 默认值 | 描述 | | ----------- | -------- | --- | -------------------- | | `index` | `number` | - | **必填。** slot 的从零开始索引 | | `className` | `string` | - | slot 的附加 CSS 类 | ### InputOTP.Separator | Prop | 类型 | 默认值 | 描述 | | ----------- | -------- | --- | ------------ | | `className` | `string` | - | 分隔符的附加 CSS 类 | ### Exported Patterns HeroUI 重新导出 input-otp 的常用正则模式以便使用： ```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** - 仅数字字符（0-9） * **REGEXP\_ONLY\_CHARS** - 仅字母字符（a-z、A-Z） * **REGEXP\_ONLY\_DIGITS\_AND\_CHARS** - 字母数字字符（0-9、a-z、A-Z） ## 相关组件 ## Related Components * **Input**: Single-line text input built on React Aria * **Form**: Form validation and submission handling * **Surface**: Base container surface </page> <page url="/cn/docs/react/components/input"> # Input 输入框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/input **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/input.mdx > 接受标准 HTML 属性的原生单行文本输入组件 ## 用法 ```tsx import { Input } from '@heroui/react'; ``` ```tsx import {Input} from "@heroui/react"; export function Basic() { return <Input aria-label="姓名" className="w-64" placeholder="输入你的姓名" />; } ``` <Callout> 校验、标签与错误消息请参阅 **[TextField](/docs/react/components/text-field)**。 </Callout> ## 示例 ### 变体 Input 组件支持两种视觉变体： * **`primary`**（默认）- 标准样式带阴影，适用于大多数场景 * **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内 ```tsx import {Input} from "@heroui/react"; export function Variants() { return ( <div className="flex w-[240px] flex-col gap-2"> <Input fullWidth placeholder="主要输入框" variant="primary" /> <Input fullWidth placeholder="次要输入框" variant="secondary" /> </div> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。 ```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="你的姓名" variant="secondary" /> </Surface> ); } ``` ### 宽度充满 ```tsx import {Input} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-3"> <Input fullWidth placeholder="全宽输入框" /> </div> ); } ``` ### 输入类型 ```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">邮箱</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">年龄</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">密码</Label> <Input id="input-type-password" placeholder="••••••••" type="password" /> </div> </div> ); } ``` ### 受控组件 ```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="域名" placeholder="域名" value={value} onChange={(event) => setValue(event.target.value)} /> <span className="px-1 text-sm text-muted">https://{value || "你的域名"}</span> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Input} from "@heroui/react"; export function CustomStyles() { return ( <Input aria-label="搜索项目" className="w-64 rounded-xl border border-border/80 bg-default text-foreground placeholder:text-muted" placeholder="搜索项目…" /> ); } ``` ### 全局 CSS 基础类 `.input` 驱动每个实例。使用 `@layer components` 一次性覆盖。 ```css @layer components { .input { @apply rounded-lg border border-border bg-surface 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-accent ring-2 ring-accent/20; } &[data-invalid="true"] { @apply border-danger bg-danger-soft text-danger; } } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 #### 基础类 \[!toc] * `.input` – 原生 input 元素样式 ### 交互状态 * **Hover**：`:hover` 或 `[data-hovered="true"]` * **Focus Visible**：`:focus-visible` 或 `[data-focus-visible="true"]` * **Invalid**：`[data-invalid="true"]`（与 `aria-invalid` 同步） * **Disabled**：`:disabled` 或 `[aria-disabled="true"]` * **Read Only**：`[aria-readonly="true"]` ## API 参考 ### Input Input 接受所有标准 HTML `<input>` 属性，以及以下 props： | Prop | 类型 | 默认值 | 描述 | | -------------- | ------------------------------------------------------ | ----------- | --------------------------------------------------------- | | `className` | `string` | - | 与组件样式合并的 Tailwind 类 | | `type` | `string` | `"text"` | 输入类型（text、email、password、number 等） | | `value` | `string` | - | 受控值 | | `defaultValue` | `string` | - | 非受控初始值 | | `onChange` | `(event: React.ChangeEvent<HTMLInputElement>) => void` | - | 变化处理函数 | | `placeholder` | `string` | - | 占位文本 | | `disabled` | `boolean` | `false` | 是否禁用 | | `readOnly` | `boolean` | `false` | 是否只读 | | `required` | `boolean` | `false` | 是否必填 | | `name` | `string` | - | 表单提交时的 name | | `autoComplete` | `string` | - | 浏览器自动完成提示 | | `maxLength` | `number` | - | 最大字符数 | | `minLength` | `number` | - | 最小字符数 | | `pattern` | `string` | - | 校验用正则模式 | | `min` | `number \| string` | - | 最小值（number/date 输入） | | `max` | `number \| string` | - | 最大值（number/date 输入） | | `step` | `number \| string` | - | 步进间隔（number 输入） | | `fullWidth` | `boolean` | `false` | 是否占满容器宽度 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 | > 校验 props 如 `isInvalid`、`isRequired` 与错误处理，请使用 **[TextField](/docs/react/components/text-field)** 并将 Input 作为子组件。 ## 相关组件 ## Related Components * **TextField**: Composition-friendly fields with labels and validation * **TextArea**: Multiline text input with focus management * **Label**: Accessible label for form controls </page> <page url="/cn/docs/react/components/label"> # Label 标签 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/label **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/label.mdx > 渲染与表单控件关联的无障碍标签。 ## 用法 ```tsx import { Label } from '@heroui/react'; ``` ```tsx import {Input, Label} from "@heroui/react"; export function Basic() { return ( <div className="flex flex-col gap-1"> <Label htmlFor="name">姓名</Label> <Input className="w-64" id="name" placeholder="输入你的姓名" type="text" /> </div> ); } ``` ## 示例 ### 带必填指示符 ```tsx <Label htmlFor="email" isRequired> Email Address </Label> <Input id="email" type="email" /> ``` ### 禁用状态 ```tsx <Label htmlFor="username" isDisabled> Username </Label> <Input id="username" isDisabled /> ``` ### 无效状态 ```tsx <Label htmlFor="password" isInvalid> Password </Label> <Input id="password" isInvalid /> ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Input, Label} from "@heroui/react"; export function CustomStyles() { return ( <div className="flex flex-col gap-1.5"> <Label className="text-xs font-semibold tracking-wide text-accent uppercase" htmlFor="repo"> 仓库 </Label> <Input className="w-64 bg-field" id="repo" placeholder="heroui/react" /> </div> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .label { @apply font-semibold text-foreground; } .label--required::after { @apply text-accent; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Label 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/label.css)）： #### 基础类 \[!toc] * `.label` — 基础标签文本样式 #### 状态修饰类 \[!toc] * `.label--required` 或 `[data-required="true"] > .label` — 显示必填星号 * `.label--disabled` 或 `[data-disabled="true"] .label` — 禁用状态样式 * `.label--invalid` 或 `[data-invalid="true"] .label` 或 `[aria-invalid="true"] .label` — 无效状态样式（危险/红色文本） **说明：** 必填星号会基于 role 与 `data-slot` 智能应用，并排除： * `role="group"`、`role="radiogroup"`、`role="checkboxgroup"` 的元素 * `data-slot="radio"` 或 `data-slot="checkbox"` 的元素 从而在分组组件与必填字段组合时避免重复星号。 ## API 参考 ### Label | Prop | 类型 | 默认值 | 描述 | | ------------ | ----------- | ------- | ----------- | | `htmlFor` | `string` | - | 标签所关联元素的 id | | `isRequired` | `boolean` | `false` | 是否显示必填指示符 | | `isDisabled` | `boolean` | `false` | 标签是否处于禁用状态 | | `isInvalid` | `boolean` | `false` | 标签是否处于无效状态 | | `className` | `string` | - | 附加的 CSS 类 | | `children` | `ReactNode` | - | 标签内容 | ## 无障碍 Label 基于原生 HTML `<label>`（[MDN 参考](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label)），并遵循 WAI-ARIA 最佳实践： * 使用 `htmlFor` 与表单控件关联 * 提供语义化的 `<label>` 元素 * 与表单控件关联时支持键盘导航 * 向屏幕阅读器传达必填与无效状态 * 点击标签可聚焦/激活关联的表单控件 ## 相关组件 ## 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 </page> <page url="/cn/docs/react/components/number-field"> # NumberField 数字输入框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/number-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/number-field.mdx > 数字输入字段，包含增减按钮、校验与国际化格式化能力。 ## 用法 ```tsx import { NumberField } from '@heroui/react'; ``` ```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>宽度</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> ); } ``` ## 组件结构 ```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** 允许用户输入数值，并可选择是否显示增减按钮。它支持国际化格式化、校验与键盘导航。 ## 示例 ### 变体 NumberField 组件支持两种视觉变体： * **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景 * **`secondary`** — 低强调、无阴影，适合在 Surface 等表面背景上使用 ```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>主要变体</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>次要变体</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> </div> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。 ```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>宽度</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-full" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>以像素为单位输入宽度</Description> </NumberField> <NumberField defaultValue={0.5} formatOptions={{style: "percent"}} maxValue={1} minValue={0} name="percentage" step={0.1} variant="secondary" > <Label>百分比</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-full" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>取值须在 0 到 100 之间</Description> </NumberField> </Surface> ); } ``` ### 带描述 ```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>宽度</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>以像素为单位输入宽度</Description> </NumberField> <NumberField defaultValue={0.5} formatOptions={{style: "percent"}} maxValue={1} minValue={0} name="percentage" step={0.1} > <Label>百分比</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>取值须在 0 到 100 之间</Description> </NumberField> </div> ); } ``` ### 必填字段 ```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>数量</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>评分</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>评分范围 1 到 10</Description> </NumberField> </div> ); } ``` ### 禁用状态 ```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>宽度</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>以像素为单位输入宽度</Description> </NumberField> <NumberField isDisabled defaultValue={0.5} formatOptions={{style: "percent"}} maxValue={1} minValue={0} name="percentage" step={0.1} > <Label>百分比</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>取值须在 0 到 100 之间</Description> </NumberField> </div> ); } ``` ### 宽度充满 ```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>宽度</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> </div> ); } ``` ### 表单校验 将 `isInvalid` 与 `FieldError` 配合使用，以展示校验消息。 ```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>数量</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <FieldError>数量必须大于或等于 0</FieldError> </NumberField> <NumberField isInvalid formatOptions={{style: "percent"}} maxValue={1} minValue={0} name="percentage" step={0.1} value={1.5} > <Label>百分比</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <FieldError>百分比必须在 0 到 100 之间</FieldError> </NumberField> </div> ); } ``` ### 受控组件 控制 value 以与其他组件同步或执行自定义格式化。 ```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>宽度</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>当前值：{value}</Description> </NumberField> <div className="flex gap-2"> <Button variant="tertiary" onPress={() => setValue(0)}> 重置为 0 </Button> <Button variant="tertiary" onPress={() => setValue(2048)}> 设为 2048 </Button> </div> </div> ); } ``` ### 步进值 配置增减步进值以实现精确控制。 ```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>步长：1</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>每次增减 1</Description> </NumberField> <NumberField defaultValue={0} maxValue={100} minValue={0} name="step5" step={5}> <Label>步长：5</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>每次增减 5</Description> </NumberField> <NumberField defaultValue={0} maxValue={100} minValue={0} name="step10" step={10}> <Label>步长：10</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>每次增减 10</Description> </NumberField> </div> ); } ``` ### 格式化选项 支持将数字格式化为货币、百分比、小数或单位，并具备国际化能力。 ```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>货币（EUR - 会计格式）</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>欧元会计记账格式</Description> </NumberField> <NumberField defaultValue={99.99} minValue={0} name="currency-usd" formatOptions={{ currency: "USD", style: "currency", }} > <Label>货币（USD）</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>标准美元货币格式</Description> </NumberField> <NumberField defaultValue={0.5} formatOptions={{style: "percent"}} maxValue={1} minValue={0} name="percentage" step={0.01} > <Label>百分比</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>百分比格式（0–1，0.5 表示 50%）</Description> </NumberField> <NumberField defaultValue={1234.56} minValue={0} name="decimal" formatOptions={{ maximumFractionDigits: 2, minimumFractionDigits: 2, style: "decimal", }} > <Label>小数（保留 2 位）</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>保留 2 位小数格式</Description> </NumberField> <NumberField defaultValue={1000} minValue={0} name="unit" formatOptions={{ style: "unit", unit: "kilogram", unitDisplay: "short", }} > <Label>单位（千克）</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> <Description>千克单位格式</Description> </NumberField> </div> ); } ``` ### 表单示例 完整的表单集成示例，包含校验与提交处理。 ```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.SyntheticEvent<HTMLFormElement>) => { 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>订购数量</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> {isOutOfStock ? ( <FieldError>仅剩 {STOCK_AVAILABLE} 件库存</FieldError> ) : ( <Description>仅剩 {STOCK_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" /> 处理中… </> ) : ( "下单" )} </Button> </Form> ); } ``` ### 带校验 通过受控 value 实现自定义校验逻辑。 ```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>百分比</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> {isInvalid ? ( <FieldError>百分比必须在 0 到 100 之间</FieldError> ) : ( <Description>请输入 0 到 100 之间的值</Description> )} </NumberField> </div> ); } ``` ### 自定义图标 自定义增减按钮图标。 ```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>宽度（自定义图标）</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>自定义图标子元素</Description> </NumberField> </div> ); } ``` ### 步进箭头 使用垂直布局的 chevron 图标，呈现不同的视觉风格。 ```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>带 Chevron 的数字输入框</Label> <NumberField.Group className="flex"> <NumberField.Input className="flex-1" /> <div className="flex h-full flex-col border-s border-field-placeholder/15"> <NumberField.IncrementButton className="flex h-1/2 w-6 items-center justify-center rounded-none border-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="flex h-1/2 w-6 items-center justify-center rounded-none border-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> ); } ``` ### 渲染函数 ```tsx "use client"; import {Label, NumberField} from "@heroui/react"; export function RenderFunction() { return ( <NumberField className="w-full max-w-64" defaultValue={1024} minValue={0} name="width" render={(props) => <div {...props} data-custom="foo" />} > <Label>宽度</Label> <NumberField.Group> <NumberField.DecrementButton /> <NumberField.Input className="w-[120px]" /> <NumberField.IncrementButton /> </NumberField.Group> </NumberField> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Label, NumberField} from "@heroui/react"; export function CustomStyles() { return ( <NumberField className="w-full max-w-48" defaultValue={2} minValue={1} name="guests" variant="secondary" > <Label className="font-medium text-foreground">宾客</Label> <NumberField.Group className="rounded-xl bg-default"> <NumberField.DecrementButton className="text-muted hover:text-foreground" /> <NumberField.Input className="text-center tabular-nums" /> <NumberField.IncrementButton className="text-muted hover:text-foreground" /> </NumberField.Group> </NumberField> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```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; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 #### 基础类 \[!toc] * `.number-field` – 根容器，样式非常克制（`flex flex-col gap-1`） * `.number-field__group` – 输入与按钮的容器，包含边框与背景样式 * `.number-field__input` – 数字输入字段 * `.number-field__increment-button` – 用于增加数值的按钮 * `.number-field__decrement-button` – 用于减少数值的按钮 #### 变体类 \[!toc] * `.number-field--primary` – 带阴影的主变体（默认） * `.number-field--secondary` – 无阴影的次变体，适合用在 surface 上 > **说明：** 子组件（[Label](/docs/react/components/label)、[Description](/docs/react/components/description)、[FieldError](/docs/react/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参见对应文档。 ### 交互状态 NumberField 会根据状态自动管理以下 data 属性： * **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` – 无效时会自动隐藏 description 插槽 * **Disabled**：`[data-disabled="true"]` – 当 `isDisabled` 为 true 时应用 * **Focus Within**：`[data-focus-within="true"]` – 当输入框或按钮聚焦时应用 * **Focus Visible**：`[data-focus-visible="true"]` – 当焦点可见（键盘导航）时应用 * **Hovered**：`[data-hovered="true"]` – 当悬停在按钮上时应用 更多属性可通过渲染 prop 获得（见下方的 NumberFieldRenderProps）。 ## API 参考 ### NumberField NumberField 继承 React Aria [NumberField](https://react-spectrum.adobe.com/react-aria/NumberField.html) 组件的全部 props。 #### Base Props | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- | | `children` | `React.ReactNode \| (values: NumberFieldRenderProps) => React.ReactNode` | - | 子组件（Label、Group、Input 等）或渲染函数。 | | `className` | `string \| (values: NumberFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 | | `style` | `React.CSSProperties \| (values: NumberFieldRenderProps) => React.CSSProperties` | - | 行内样式，支持渲染 prop。 | | `fullWidth` | `boolean` | `false` | 数字字段是否占满容器宽度 | | `id` | `string` | - | 元素的唯一标识符。 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, NumberFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | #### Value Props | Prop | 类型 | 默认值 | 描述 | | -------------- | -------------------------------------- | --- | -------------- | | `value` | `number` | - | 当前值（受控）。 | | `defaultValue` | `number` | - | 默认值（非受控）。 | | `onChange` | `(value: number \| undefined) => void` | - | 值变化时触发的事件处理函数。 | #### Formatting Props | Prop | 类型 | 默认值 | 描述 | | --------------- | -------------------------- | --- | ----------------------- | | `formatOptions` | `Intl.NumberFormatOptions` | - | 数字格式化选项（货币、百分比、小数、单位等）。 | | `locale` | `string` | - | 数字格式化的区域设置。 | #### Validation Props | Prop | 类型 | 默认值 | 描述 | | -------------------- | ----------------------------------------------------------------- | ---------- | ------------------------ | | `isRequired` | `boolean` | `false` | 提交表单前是否要求用户输入。 | | `isInvalid` | `boolean` | - | 当前值是否无效。 | | `validate` | `(value: number) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验或 ARIA 属性。 | | `validationErrors` | `string[]` | - | 服务端校验错误。 | #### Range Props | Prop | 类型 | 默认值 | 描述 | | ---------- | -------- | --- | --------- | | `minValue` | `number` | - | 允许的最小值。 | | `maxValue` | `number` | - | 允许的最大值。 | | `step` | `number` | `1` | 增减操作的步进值。 | #### State Props | Prop | 类型 | 默认值 | 描述 | | ------------ | --------- | --- | ----------- | | `isDisabled` | `boolean` | - | 是否禁用输入。 | | `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 | #### Form Props | Prop | 类型 | 默认值 | 描述 | | ----------- | --------- | --- | ------------------------- | | `name` | `string` | - | input 元素的名称，用于 HTML 表单提交。 | | `autoFocus` | `boolean` | - | 元素渲染后是否应获得焦点。 | #### Accessibility Props | Prop | 类型 | 默认值 | 描述 | | ------------------ | -------- | --- | -------------- | | `aria-label` | `string` | - | 没有可见标签时的无障碍标签。 | | `aria-labelledby` | `string` | - | 用于标注该字段的元素 ID。 | | `aria-describedby` | `string` | - | 用于描述该字段的元素 ID。 | | `aria-details` | `string` | - | 包含更多详情的元素 ID。 | ### Composition Components NumberField 需要与以下独立组件组合使用，请分别导入并直接使用： * **NumberField.Group** – 输入与按钮的容器 * **NumberField.Input** – 数字输入字段 * **NumberField.IncrementButton** – 用于增加数值的按钮 * **NumberField.DecrementButton** – 用于减少数值的按钮 * **Label** – 字段标签组件（`@heroui/react`） * **Description** – 辅助说明文本组件（`@heroui/react`） * **FieldError** – 校验错误信息组件（`@heroui/react`） 这些组件各自拥有 props API。请直接在 NumberField 内组合使用： ```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 继承 React Aria [Group](https://react-spectrum.adobe.com/react-aria/Group.html) 组件的 props。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------ | --- | ------------------------ | | `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | 子组件（Input、Buttons）或渲染函数。 | | `className` | `string \| (values: GroupRenderProps) => string` | - | 用于样式的 CSS 类。 | #### NumberField.Input Props NumberField.Input 继承 React Aria [Input](https://react-spectrum.adobe.com/react-aria/Input.html) 组件的 props。 | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------- | ----------- | ----------------------------------------------------------------- | | `className` | `string` | - | 用于样式的 CSS 类。 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 输入的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 | #### NumberField.IncrementButton Props NumberField.IncrementButton 继承 React Aria [Button](https://react-spectrum.adobe.com/react-aria/Button.html) 组件的 props。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | -------------- | --------------------------- | | `children` | `React.ReactNode` | `<IconPlus />` | 按钮的图标或内容。默认为加号图标。 | | `className` | `string` | - | 用于样式的 CSS 类。 | | `slot` | `"increment"` | `"increment"` | 必须设置为 `"increment"`（会自动设置）。 | #### NumberField.DecrementButton Props NumberField.DecrementButton 继承 React Aria [Button](https://react-spectrum.adobe.com/react-aria/Button.html) 组件的 props。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --------------- | --------------------------- | | `children` | `React.ReactNode` | `<IconMinus />` | 按钮的图标或内容。默认为减号图标。 | | `className` | `string` | - | 用于样式的 CSS 类。 | | `slot` | `"decrement"` | `"decrement"` | 必须设置为 `"decrement"`（会自动设置）。 | ### NumberFieldRenderProps 在 `className`、`style` 或 `children` 上使用渲染 prop 时，可使用以下值： | Prop | 类型 | 描述 | | ---------------- | --------------------- | -------------------------------- | | `isDisabled` | `boolean` | 字段是否禁用。 | | `isInvalid` | `boolean` | 字段当前是否无效。 | | `isReadOnly` | `boolean` | 字段是否只读。 | | `isRequired` | `boolean` | 字段是否必填。 | | `isFocused` | `boolean` | 字段是否聚焦（已弃用，请使用 `isFocusWithin`）。 | | `isFocusWithin` | `boolean` | 是否有任意子元素聚焦。 | | `isFocusVisible` | `boolean` | 是否为可见焦点（键盘导航）。 | | `value` | `number \| undefined` | 当前值。 | | `minValue` | `number \| undefined` | 允许的最小值。 | | `maxValue` | `number \| undefined` | 允许的最大值。 | | `step` | `number` | 增减步进值。 | ## 相关案例 ## 相关组件 ## Related Components * **Label**: Accessible label for form controls * **Description**: Helper text for form fields * **FieldError**: Inline validation messages for form fields </page> <page url="/cn/docs/react/components/radio-group"> # RadioGroup 单选框组 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/radio-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/radio-group.mdx > 用于从列表中选择单个选项的单选组。 ## 用法 ```tsx import { RadioGroup, Radio } from '@heroui/react'; ``` ```tsx import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function Basic() { return ( <RadioGroup defaultValue="premium" name="plan"> <Label>选择套餐</Label> <Description>选择最适合你的套餐</Description> <Radio value="basic"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 基础版 </Radio.Content> <Description>每月包含 100 条消息</Description> </Radio> <Radio value="premium"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 高级版 </Radio.Content> <Description>每月包含 200 条消息</Description> </Radio> <Radio value="business"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 商业版 </Radio.Content> <Description>无限消息</Description> </Radio> </RadioGroup> ); } ``` ## 组件结构 导入 RadioGroup 组件后，可通过点号访问各个子部分。 ```tsx import {RadioGroup, Radio, Label, Description, FieldError} from '@heroui/react'; export default () => ( <RadioGroup> <Label /> <Description /> <Radio value="option1"> <Radio.Content> {/* 可点击区域：control + label */} <Radio.Control> <Radio.Indicator> <span>✓</span> {/* Custom indicator (optional) */} </Radio.Indicator> </Radio.Control> Label {/* 纯文本 —— 可点击的标签 */} </Radio.Content> <Description /> {/* 兄弟节点 — 位于按钮外部（通过 aria-describedby 关联） */} <FieldError /> {/* 可选 — 单选项校验错误信息 */} </Radio> <FieldError /> {/* 可选 — 组级校验 */} </RadioGroup> ) ``` ## 示例 ### 水平排列 ```tsx import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function Horizontal() { return ( <div className="flex flex-col gap-4"> <Label>订阅套餐</Label> <RadioGroup defaultValue="pro" name="plan-orientation" orientation="horizontal"> <Radio value="starter"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 入门版 </Radio.Content> <Description>适合副项目</Description> </Radio> <Radio value="pro"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 专业版 </Radio.Content> <Description>高级报表</Description> </Radio> <Radio value="teams"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 团队版 </Radio.Content> <Description>最多 10 名队友</Description> </Radio> </RadioGroup> </div> ); } ``` ### 变体 RadioGroup 组件支持两种视觉变体： * **`primary`**（默认）— 带默认背景的标准样式，适用于大多数场景 * **`secondary`** — 低强调变体，适合在 Surface 等表面背景上使用 ```tsx import {Description, 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">主要变体</p> <RadioGroup defaultValue="option1" name="primary-plan" variant="primary"> <Radio value="option1"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 选项 1 </Radio.Content> <Description>默认背景的标准样式</Description> </Radio> <Radio value="option2"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 选项 2 </Radio.Content> <Description>另一种主要样式选项</Description> </Radio> </RadioGroup> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">次要变体</p> <RadioGroup defaultValue="option1" name="secondary-plan" variant="secondary"> <Radio value="option1"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 选项 1 </Radio.Content> <Description>用于表面上的低强调变体</Description> </Radio> <Radio value="option2"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 选项 2 </Radio.Content> <Description>另一种次要样式选项</Description> </Radio> </RadioGroup> </div> </div> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。 ```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-on-surface" variant="secondary"> <Label>选择套餐</Label> <Description>选择最适合你的套餐</Description> <Radio value="basic"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 基础版 </Radio.Content> <Description>每月包含 100 条消息</Description> </Radio> <Radio value="premium"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 高级版 </Radio.Content> <Description>每月包含 200 条消息</Description> </Radio> <Radio value="business"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 商业版 </Radio.Content> <Description>无限消息</Description> </Radio> </RadioGroup> </Surface> ); } ``` ### 禁用 ```tsx import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function Disabled() { return ( <RadioGroup isDisabled defaultValue="pro" name="plan-disabled"> <Label>订阅套餐</Label> <Description>我们正在发布更新，暂时无法更改套餐。</Description> <Radio value="starter"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 入门版 </Radio.Content> <Description>适合副项目和小型团队</Description> </Radio> <Radio value="pro"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 专业版 </Radio.Content> <Description>高级报表与分析</Description> </Radio> <Radio value="teams"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 团队版 </Radio.Content> <Description>最多可与 10 名队友共享访问权限</Description> </Radio> </RadioGroup> ); } ``` ### 受控组件 ```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>订阅套餐</Label> <Radio value="starter"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 入门版 </Radio.Content> <Description>适合副项目和小型团队</Description> </Radio> <Radio value="pro"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 专业版 </Radio.Content> <Description>高级报表与分析</Description> </Radio> <Radio value="teams"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 团队版 </Radio.Content> <Description>最多可与 10 名队友共享访问权限</Description> </Radio> </RadioGroup> <p className="text-sm text-muted"> 已选套餐： <span className="font-medium">{value}</span> </p> </div> ); } ``` ### 非受控 仅需响应更新时，将 `defaultValue` 与 `onChange` 配合使用。 ```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>订阅套餐</Label> <Radio value="starter"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 入门版 </Radio.Content> <Description>适合副项目和小型团队</Description> </Radio> <Radio value="pro"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 专业版 </Radio.Content> <Description>高级报表与分析</Description> </Radio> <Radio value="teams"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 团队版 </Radio.Content> <Description>最多可与 10 名队友共享访问权限</Description> </Radio> </RadioGroup> <p className="text-sm text-muted"> 上次选择的套餐： <span className="font-medium">{selection}</span> </p> </div> ); } ``` ### 表单校验 ```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(`你选择的套餐是： ${value}`); }} > <RadioGroup isRequired name="plan-validation"> <Label>订阅套餐</Label> <Radio value="starter"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 入门版 </Radio.Content> <Description>适合副项目和小型团队</Description> </Radio> <Radio value="pro"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 专业版 </Radio.Content> <Description>高级报表与分析</Description> </Radio> <Radio value="teams"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 团队版 </Radio.Content> <Description>最多可与 10 名队友共享访问权限</Description> </Radio> <FieldError>请先选择订阅套餐再继续。</FieldError> </RadioGroup> <Button className="mt-2 w-fit" type="submit"> Submit </Button> {!!message && <p className="text-sm text-muted">{message}</p>} </Form> ); } ``` ### 配送与支付 ### 自定义指示器 ```tsx "use client"; import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function CustomIndicator() { return ( <RadioGroup defaultValue="premium" name="plan-custom-indicator"> <Label>选择套餐</Label> <Description>选择最适合你的套餐</Description> <Radio value="basic"> <Radio.Content> <Radio.Control> <Radio.Indicator> {({isSelected}) => isSelected ? <span className="text-xs leading-none text-background">✓</span> : null } </Radio.Indicator> </Radio.Control> 基础版 </Radio.Content> <Description>每月包含 100 条消息</Description> </Radio> <Radio value="premium"> <Radio.Content> <Radio.Control> <Radio.Indicator> {({isSelected}) => isSelected ? <span className="text-xs leading-none text-background">✓</span> : null } </Radio.Indicator> </Radio.Control> 高级版 </Radio.Content> <Description>每月包含 200 条消息</Description> </Radio> <Radio value="business"> <Radio.Content> <Radio.Control> <Radio.Indicator> {({isSelected}) => isSelected ? <span className="text-xs leading-none text-background">✓</span> : null } </Radio.Indicator> </Radio.Control> 商业版 </Radio.Content> <Description>无限消息</Description> </Radio> </RadioGroup> ); } ``` ### 渲染函数 ```tsx "use client"; import {Description, Label, Radio, RadioGroup} from "@heroui/react"; export function RenderFunction() { return ( <RadioGroup defaultValue="premium" name="plan-custom-render" render={(props) => <div {...props} data-custom="foo" />} > <Label>选择套餐</Label> <Description>选择最适合你的套餐</Description> <Radio value="basic"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 基础版 </Radio.Content> <Description>每月包含 100 条消息</Description> </Radio> <Radio value="premium"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 高级版 </Radio.Content> <Description>每月包含 200 条消息</Description> </Radio> <Radio value="business"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 商业版 </Radio.Content> <Description>无限消息</Description> </Radio> </RadioGroup> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Description, Label, Radio, RadioGroup} from "@heroui/react"; const options = [ {description: "每月扣费 $12", label: "按月", value: "monthly"}, {description: "每年一次性扣费 $120", label: "按年", value: "yearly"}, ] as const; const contentClassName = "group flex w-full items-start gap-3 rounded-xl border border-success/10 bg-success-soft/30 px-4 py-3 transition-colors data-[focus-visible=true]:ring-2 data-[focus-visible=true]:ring-success/15 data-[hovered=true]:bg-success-soft-hover data-[selected=true]:border-success/30 data-[selected=true]:bg-success-soft data-[selected=true]:data-[hovered=true]:bg-success-soft-hover"; const controlClassName = "mt-0.5 size-5 shrink-0 rounded-full border border-border bg-default shadow-none group-data-[pressed=true]:scale-95 group-data-[selected=true]:border-transparent group-data-[selected=true]:bg-success group-data-[selected=true]:group-data-[pressed=true]:bg-success-hover"; const indicatorClassName = "before:rounded-full before:bg-default group-data-[selected=true]:before:scale-50 group-data-[selected=true]:before:bg-success-foreground group-data-[selected=true]:group-data-[pressed=true]:before:scale-[0.57]"; export function CustomStyles() { return ( <RadioGroup className="w-full max-w-sm gap-3 **:data-[slot=radio]:mt-0" defaultValue="yearly" name="billing" variant="secondary" > <Label className="font-medium text-foreground">计费周期</Label> <Description>选择你的扣费频率。</Description> {options.map(({description, label, value}) => ( <Radio key={value} value={value}> <Radio.Content className={contentClassName}> <Radio.Control className={controlClassName}> <Radio.Indicator className={indicatorClassName} /> </Radio.Control> <div className="flex flex-col gap-0.5"> <span className="font-medium text-foreground group-data-[selected=true]:text-success-soft-foreground"> {label} </span> <Description className="group-data-[selected=true]:text-success-soft-foreground/80"> {description} </Description> </div> </Radio.Content> </Radio> ))} </RadioGroup> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](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-accent; } .radio__indicator { @apply bg-primary; } .radio__content { @apply gap-1; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 RadioGroup 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/radio-group.css)）： #### 基础类 \[!toc] * `.radio-group` - 单选组基础容器 * `.radio` - 单个单选项 * `.radio__control` - 单选控件（圆形按钮） * `.radio__indicator` - 单选指示器（内部圆点） * `.radio__content` - 单选内容包裹层 #### 修饰类 \[!toc] 禁用态通过 `.radio` 上的 `[data-disabled="true"]` / `[aria-disabled="true"]`（以及 `:disabled`）应用——没有 `.radio--disabled` 修饰类。 ### 交互状态 单选项同时支持 CSS 伪类与 data 属性，便于灵活定制： * **Selected**：`[aria-checked="true"]` 或 `[data-selected="true"]`（显示指示器） * **Hover**：`:hover` 或 `[data-hovered="true"]`（边框颜色变化） * **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]`（显示焦点环） * **Pressed**：`:active` 或 `[data-pressed="true"]`（缩放变换） * **Disabled**：`:disabled` 或 `[aria-disabled="true"]`（降低透明度并禁用指针事件） * **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]`（错误边框颜色） ## API 参考 ### RadioGroup | Prop | 类型 | 默认值 | 描述 | | -------------- | ----------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------- | | `value` | `string` | - | 当前值（受控） | | `defaultValue` | `string` | - | 默认值（非受控） | | `onChange` | `(value: string) => void` | - | 值变化时触发的事件处理函数 | | `isDisabled` | `boolean` | `false` | 是否禁用整个单选组 | | `isRequired` | `boolean` | `false` | 是否必填 | | `isReadOnly` | `boolean` | `false` | 是否只读 | | `isInvalid` | `boolean` | `false` | 是否处于无效状态 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 | | `name` | `string` | - | 单选组的名称，用于提交 HTML 表单 | | `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` | 单选组的排列方向 | | `children` | `React.ReactNode \| (values: RadioGroupRenderProps) => React.ReactNode` | - | 单选组内容或渲染 prop | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, RadioGroupRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Radio | Prop | 类型 | 默认值 | 描述 | | ------------ | ----------------------------------------------------------------------------- | ------- | --------------------- | | `value` | `string` | - | 单选项的值 | | `isDisabled` | `boolean` | `false` | 是否禁用该单选项 | | `name` | `string` | - | 单选项名称，用于提交 HTML 表单 | | `children` | `React.ReactNode \| (values: RadioFieldRenderProps) => React.ReactNode` | - | 单选内容或字段级渲染 prop | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, RadioFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Radio.Control 继承 `React.HTMLAttributes<HTMLSpanElement>`。 | Prop | 类型 | 默认值 | 描述 | | ---------- | ----------------- | --- | --------------------------------- | | `children` | `React.ReactNode` | - | 控件包裹层内要渲染的内容（通常为 Radio.Indicator） | ### Radio.Indicator 继承 `React.HTMLAttributes<HTMLSpanElement>`。 | Prop | 类型 | 默认值 | 描述 | | ---------- | ------------------------------------------------------------------------ | --- | ------------------------ | | `children` | `React.ReactNode \| (values: RadioButtonRenderProps) => React.ReactNode` | - | 可选内容或接收当前单选按钮状态的渲染 prop。 | ### Radio.Content 单选项的可点击区域（包裹隐藏 input 的 `<label>`）。请将 `Radio.Control` 与 `Label` 放在其中。`className` 支持接收 `RadioButtonRenderProps` 的渲染函数。 | Prop | 类型 | 默认值 | 描述 | | ---------- | ------------------------------------------------------------------------ | --- | -------------------------------- | | `children` | `React.ReactNode \| (values: RadioButtonRenderProps) => React.ReactNode` | - | 可点击内容（通常为 Radio.Control 与 Label） | ### RadioFieldRenderProps 在根级 `Radio` 上使用渲染 prop 时，会提供以下字段级值： | Prop | 类型 | 描述 | | ------------ | --------- | -------- | | `isSelected` | `boolean` | 单选项是否已选中 | | `isDisabled` | `boolean` | 是否禁用 | | `isReadOnly` | `boolean` | 是否只读 | | `isInvalid` | `boolean` | 是否无效 | | `isRequired` | `boolean` | 是否必填 | ### RadioButtonRenderProps `Radio.Control` 和 `Radio.Indicator` 使用按钮级渲染 prop（`isHovered`、`isPressed`、`isFocusVisible` 等）。将函数作为 `Radio.Control` 子节点或传给 `Radio.Indicator` 即可访问它们。 ## 相关案例 ## 相关组件 ## Related Components * **Fieldset**: Group related form controls with legends * **Surface**: Base container surface * **Description**: Helper text for form fields </page> <page url="/cn/docs/react/components/search-field"> # SearchField 搜索框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/search-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/search-field.mdx > 搜索输入字段，包含清除按钮与搜索图标。 ## 用法 ```tsx import { SearchField } from '@heroui/react'; ``` ```tsx import {Label, SearchField} from "@heroui/react"; export function Basic() { return ( <SearchField name="search"> <Label>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> ); } ``` ## 组件结构 ```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** 允许用户输入并清空搜索关键词。它包含搜索图标，并提供可选的清除按钮以便快速重置。 ## 示例 ### 变体 SearchField 组件支持两种视觉变体： * **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景 * **`secondary`** — 低强调、无阴影，适合在 Surface 等表面背景上使用 ```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>主要变体</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <SearchField name="secondary-search" variant="secondary"> <Label>次要变体</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> </div> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。 ```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>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-full" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> <Description>输入关键词进行搜索</Description> </SearchField> <SearchField name="search-2" variant="secondary"> <Label>高级搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-full" placeholder="高级搜索…" /> <SearchField.ClearButton /> </SearchField.Group> <Description>使用筛选条件细化搜索</Description> </SearchField> </Surface> ); } ``` ### 带描述 ```tsx import {Description, Label, SearchField} from "@heroui/react"; export function WithDescription() { return ( <div className="flex flex-col gap-4"> <SearchField name="search"> <Label>搜索产品</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索产品…" /> <SearchField.ClearButton /> </SearchField.Group> <Description>输入关键词进行搜索 for products</Description> </SearchField> <SearchField name="search-users"> <Label>搜索用户</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索用户…" /> <SearchField.ClearButton /> </SearchField.Group> <Description>按姓名、邮箱或用户名搜索</Description> </SearchField> </div> ); } ``` ### 必填字段 ```tsx import {Description, Label, SearchField} from "@heroui/react"; export function Required() { return ( <div className="flex flex-col gap-4"> <SearchField isRequired name="search"> <Label>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <SearchField isRequired name="search-query"> <Label>搜索内容</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="输入搜索内容…" /> <SearchField.ClearButton /> </SearchField.Group> <Description>至少需要 3 个字符</Description> </SearchField> </div> ); } ``` ### 禁用状态 ```tsx import {Description, Label, SearchField} from "@heroui/react"; export function Disabled() { return ( <div className="flex flex-col gap-4"> <SearchField isDisabled name="search" value="已禁用的搜索"> <Label>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> <Description>此搜索框已禁用</Description> </SearchField> <SearchField isDisabled name="search-empty"> <Label>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> <Description>此搜索框已禁用</Description> </SearchField> </div> ); } ``` ### 宽度充满 ```tsx import {Label, SearchField} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <SearchField fullWidth name="search"> <Label>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> </div> ); } ``` ### 表单校验 将 `isInvalid` 与 `FieldError` 配合使用，以展示校验消息。 ```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>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> <FieldError>搜索内容至少需要 3 个字符</FieldError> </SearchField> <SearchField isInvalid name="search-invalid"> <Label>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索…" value="invalid@query" /> <SearchField.ClearButton /> </SearchField.Group> <FieldError>搜索内容包含无效字符</FieldError> </SearchField> </div> ); } ``` ### 受控组件 控制 value 以与其他组件同步或执行自定义格式化。 ```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>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> <Description>当前值： {value || "（空）"}</Description> </SearchField> <div className="flex gap-2"> <Button variant="tertiary" onPress={() => setValue("")}> Clear </Button> <Button variant="tertiary" onPress={() => setValue("示例查询")}> 设置示例 </Button> </div> </div> ); } ``` ### 表单示例 完整的表单集成示例，包含校验与提交处理。 ```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.SyntheticEvent<HTMLFormElement>) => { 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>搜索产品</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-full" placeholder="搜索产品…" /> <SearchField.ClearButton /> </SearchField.Group> {isInvalid ? ( <FieldError>搜索内容至少需要 {MIN_LENGTH} 个字符</FieldError> ) : ( <Description>请输入至少 {MIN_LENGTH} 个字符后再搜索</Description> )} </SearchField> <Button className="w-full" isDisabled={value.length < MIN_LENGTH} isPending={isSubmitting} type="submit" variant="primary" > {isSubmitting ? ( <> <Spinner color="current" size="sm" /> 搜索中… </> ) : ( "搜索" )} </Button> </Form> ); } ``` ### 带校验 通过受控 value 实现自定义校验逻辑。 ```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>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> {isInvalid ? ( <FieldError>搜索内容至少需要 3 个字符</FieldError> ) : ( <Description>请输入至少 3 个字符后再搜索</Description> )} </SearchField> </div> ); } ``` ### 自定义图标 自定义搜索图标与清除按钮图标。 ```tsx import {Description, Label, SearchField} from "@heroui/react"; export function CustomIcons() { return ( <div className="flex flex-col gap-4"> <SearchField name="search-custom"> <Label>搜索（自定义图标）</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="搜索…" /> <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>自定义图标子元素</Description> </SearchField> </div> ); } ``` ### 键盘快捷键 添加快捷键以快速聚焦搜索框。 ```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>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input ref={inputRef} className="w-[280px]" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> <Description>使用键盘快捷键快速聚焦此输入框</Description> </SearchField> </div> <div className="text-default-500 flex items-center gap-2 text-sm"> <span>按</span> <Kbd> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>S</Kbd.Content> </Kbd> <span>聚焦搜索框</span> </div> </div> ); } ``` ### 渲染函数 ```tsx "use client"; import {Label, SearchField} from "@heroui/react"; export function RenderFunction() { return ( <SearchField name="search" render={(props) => <div {...props} data-custom="foo" />}> <Label>搜索</Label> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input className="w-[280px]" placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Label, SearchField} from "@heroui/react"; export function CustomStyles() { return ( <SearchField className="w-full max-w-64" name="docs" variant="secondary"> <Label className="font-medium text-foreground">搜索文档</Label> <SearchField.Group className="rounded-xl bg-default"> <SearchField.SearchIcon className="text-muted" /> <SearchField.Input className="placeholder:text-muted" placeholder="组件、指南..." /> <SearchField.ClearButton className="text-muted" /> </SearchField.Group> </SearchField> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```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; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 #### 基础类 \[!toc] * `.search-field` – 根容器，样式非常克制（`flex flex-col gap-1`） * `.search-field__group` – 搜索图标、输入框与清除按钮的容器，包含边框与背景样式 * `.search-field__input` – 搜索输入字段 * `.search-field__search-icon` – 左侧显示的搜索图标 * `.search-field__clear-button` – 用于清空搜索字段的按钮 #### 变体类 \[!toc] * `.search-field--primary` – 带阴影的主变体（默认） * `.search-field--secondary` – 无阴影的次变体，适合用在 surface 上 > **说明：** 子组件（[Label](/docs/react/components/label)、[Description](/docs/react/components/description)、[FieldError](/docs/react/components/field-error)）拥有各自的 CSS 类与样式。自定义方式请参见对应文档。 ### 交互状态 SearchField 会根据状态自动管理以下 data 属性： * **Invalid**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` – 无效时会自动隐藏 description 插槽 * **Disabled**：`[data-disabled="true"]` – 当 `isDisabled` 为 true 时应用 * **Focus Within**：`[data-focus-within="true"]` – 当输入框聚焦时应用 * **Focus Visible**：`[data-focus-visible="true"]` – 当焦点可见（键盘导航）时应用 * **Hovered**：`[data-hovered="true"]` – 当悬停在整个组合上时应用 * **Empty**：`[data-empty="true"]` – 当字段为空时应用（会隐藏清除按钮） 更多属性可通过渲染 prop 获得（见下方的 SearchFieldRenderProps）。 ## API 参考 ### SearchField SearchField 继承 React Aria [SearchField](https://react-spectrum.adobe.com/react-aria/SearchField.html) 组件的全部 props。 #### Base Props | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------- | | `children` | `React.ReactNode \| (values: SearchFieldRenderProps) => React.ReactNode` | - | 子组件（Label、Group、Input 等）或渲染函数。 | | `className` | `string \| (values: SearchFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 | | `style` | `React.CSSProperties \| (values: SearchFieldRenderProps) => React.CSSProperties` | - | 行内样式，支持渲染 prop。 | | `fullWidth` | `boolean` | `false` | 搜索字段是否占满容器宽度 | | `id` | `string` | - | 元素的唯一标识符。 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SearchFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | #### Value Props | Prop | 类型 | 默认值 | 描述 | | -------------- | ------------------------- | --- | -------------- | | `value` | `string` | - | 当前值（受控）。 | | `defaultValue` | `string` | - | 默认值（非受控）。 | | `onChange` | `(value: string) => void` | - | 值变化时触发的事件处理函数。 | #### Validation Props | Prop | 类型 | 默认值 | 描述 | | -------------------- | ----------------------------------------------------------------- | ---------- | ------------------------ | | `isRequired` | `boolean` | `false` | 提交表单前是否要求用户输入。 | | `isInvalid` | `boolean` | - | 当前值是否无效。 | | `validate` | `(value: string) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验或 ARIA 属性。 | | `validationErrors` | `string[]` | - | 服务端校验错误。 | #### State Props | Prop | 类型 | 默认值 | 描述 | | ------------ | --------- | --- | ----------- | | `isDisabled` | `boolean` | - | 是否禁用输入。 | | `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 | #### Form Props | Prop | 类型 | 默认值 | 描述 | | ----------- | --------- | --- | ------------------------- | | `name` | `string` | - | input 元素的名称，用于 HTML 表单提交。 | | `autoFocus` | `boolean` | - | 元素渲染后是否应获得焦点。 | #### Event Props | Prop | 类型 | 默认值 | 描述 | | ---------- | ------------------------- | --- | ------------------------ | | `onSubmit` | `(value: string) => void` | - | 用户提交搜索（Enter）时触发的事件处理函数。 | | `onClear` | `() => void` | - | 按下清除按钮时触发的事件处理函数。 | #### Accessibility Props | Prop | 类型 | 默认值 | 描述 | | ------------------ | -------- | --- | -------------- | | `aria-label` | `string` | - | 没有可见标签时的无障碍标签。 | | `aria-labelledby` | `string` | - | 用于标注该字段的元素 ID。 | | `aria-describedby` | `string` | - | 用于描述该字段的元素 ID。 | | `aria-details` | `string` | - | 包含更多详情的元素 ID。 | ### Composition Components SearchField 需要与以下独立组件组合使用，请分别导入并直接使用： * **SearchField.Group** – 搜索图标、输入框与清除按钮的容器 * **SearchField.Input** – 搜索输入字段 * **SearchField.SearchIcon** – 左侧显示的搜索图标 * **SearchField.ClearButton** – 用于清空搜索字段的按钮 * **Label** – 字段标签组件（`@heroui/react`） * **Description** – 辅助说明文本组件（`@heroui/react`） * **FieldError** – 校验错误信息组件（`@heroui/react`） 这些组件各自拥有 props API。请直接在 SearchField 内组合使用： ```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 继承 React Aria [Group](https://react-spectrum.adobe.com/react-aria/Group.html) 组件的 props。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------ | --- | --------------------------------------- | | `children` | `React.ReactNode \| (values: GroupRenderProps) => React.ReactNode` | - | 子组件（SearchIcon、Input、ClearButton）或渲染函数。 | | `className` | `string \| (values: GroupRenderProps) => string` | - | 用于样式的 CSS 类。 | #### SearchField.Input Props SearchField.Input 继承 React Aria [Input](https://react-spectrum.adobe.com/react-aria/Input.html) 组件的 props。 | Prop | 类型 | 默认值 | 描述 | | ------------- | -------------------------- | ----------- | ----------------------------------------------------------------- | | `className` | `string` | - | 用于样式的 CSS 类。 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 输入的视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合用在 surface 上。 | | `placeholder` | `string` | - | 输入为空时显示的占位符文本。 | | `type` | `string` | `"search"` | 输入类型（会自动设置为 `"search"`）。 | #### SearchField.SearchIcon Props SearchField.SearchIcon 是一个用于渲染搜索图标的自定义组件。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | ---------------- | ---------------- | | `children` | `React.ReactNode` | `<IconSearch />` | 自定义图标元素。默认为搜索图标。 | | `className` | `string` | - | 用于样式的 CSS 类。 | #### SearchField.ClearButton Props SearchField.ClearButton 继承 React Aria [Button](https://react-spectrum.adobe.com/react-aria/Button.html) 组件的 props。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | ---------------------- | ----------------------- | | `children` | `React.ReactNode` | `<CloseButton icon />` | 按钮的图标或内容。默认为关闭图标。 | | `className` | `string` | - | 用于样式的 CSS 类。 | | `slot` | `"clear"` | `"clear"` | 必须设置为 `"clear"`（会自动设置）。 | ### SearchFieldRenderProps 在 `className`、`style` 或 `children` 上使用渲染 prop 时，可使用以下值： | Prop | 类型 | 描述 | | ---------------- | --------- | -------------------------------- | | `isDisabled` | `boolean` | 字段是否禁用。 | | `isInvalid` | `boolean` | 字段当前是否无效。 | | `isReadOnly` | `boolean` | 字段是否只读。 | | `isRequired` | `boolean` | 字段是否必填。 | | `isFocused` | `boolean` | 字段是否聚焦（已弃用，请使用 `isFocusWithin`）。 | | `isFocusWithin` | `boolean` | 是否有任意子元素聚焦。 | | `isFocusVisible` | `boolean` | 是否为可见焦点（键盘导航）。 | | `value` | `string` | 当前值。 | | `isEmpty` | `boolean` | 字段是否为空。 | ## 相关案例 ## 相关组件 ## Related Components * **Label**: Accessible label for form controls * **Description**: Helper text for form fields * **FieldError**: Inline validation messages for form fields </page> <page url="/cn/docs/react/components/text-area"> # TextArea 多行文本框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/text-area **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/text-area.mdx > 原语级多行文本输入组件，可接受标准 HTML 属性。 ## 用法 ```tsx import { TextArea } from '@heroui/react'; ``` ```tsx import {TextArea} from "@heroui/react"; export function Basic() { return ( <TextArea aria-label="快速项目更新" className="h-32 w-96" placeholder="分享一条简短的项目更新…" /> ); } ``` <Callout> 校验、标签与错误消息请参阅 **[TextField](/docs/react/components/text-field)**。 </Callout> ## 示例 ### 变体 TextArea 组件支持两种视觉变体： * **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景 * **`secondary`** — 低强调、无阴影，适合在 Surface 等表面背景上使用 ```tsx import {TextArea} from "@heroui/react"; export function Variants() { return ( <div className="flex w-[280px] flex-col gap-2"> <TextArea fullWidth placeholder="主要文本域" variant="primary" /> <TextArea fullWidth placeholder="次要文本域" variant="secondary" /> </div> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。 ```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="描述你的产品" variant="secondary" /> </Surface> ); } ``` ### 宽度充满 ```tsx import {TextArea} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-3"> <TextArea fullWidth placeholder="全宽文本域" /> </div> ); } ``` ### 受控组件 ```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="公告" placeholder="撰写公告…" value={value} onChange={(event) => setValue(event.target.value)} /> <Description id="textarea-controlled-description">字符数： {value.length} / 280</Description> </div> ); } ``` ### 行数与尺寸调整 ```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">简短反馈</Label> <TextArea aria-label="简短反馈" id="textarea-rows-3" placeholder="本周亮点…" rows={3} /> </div> <div className="flex flex-col gap-2"> <Label htmlFor="textarea-rows-6">详细笔记</Label> <TextArea aria-label="详细笔记" id="textarea-rows-6" placeholder="写下完整的会议记录…" rows={6} style={{resize: "vertical"}} /> </div> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {TextArea} from "@heroui/react"; const fieldClass = "rounded-xl border border-border/80 bg-surface shadow-sm ring-1 ring-black/5 transition-[box-shadow,border-color] focus-visible:ring-2 focus-visible:ring-neutral-400/25 dark:ring-white/10 dark:focus-visible:ring-neutral-500/30"; export function CustomStyles() { return ( <TextArea aria-label="备注" className={`h-28 w-full max-w-xs text-sm text-neutral-800 placeholder:text-neutral-400 dark:text-neutral-100 dark:placeholder:text-neutral-500 ${fieldClass}`} placeholder="添加备注…" /> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .textarea { @apply rounded-xl border border-border bg-surface 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-accent ring-2 ring-accent/20; } &[data-invalid="true"] { @apply border-danger bg-danger-soft text-danger; } } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 #### 基础类 \[!toc] * `.textarea` – 底层 `<textarea>` 元素样式 ### 交互状态 * **悬停**：`:hover` 或 `[data-hovered="true"]` * **可见焦点**：`:focus-visible` 或 `[data-focus-visible="true"]` * **无效**：`[data-invalid="true"]` * **禁用**：`:disabled` 或 `[aria-disabled="true"]` ## API 参考 ### TextArea TextArea 接受所有标准 HTML `<textarea>` 属性，以及以下属性： | Prop | 类型 | 默认值 | 描述 | | -------------- | --------------------------------------------------------- | ----------- | ----------------------------------------------------------------- | | `className` | `string` | - | 与基础样式合并的 Tailwind 类。 | | `rows` | `number` | `3` | 可见文本行数。 | | `cols` | `number` | - | 文本控件的可见宽度。 | | `value` | `string` | - | TextArea 的受控值。 | | `defaultValue` | `string` | - | 非受控初始值。 | | `onChange` | `(event: React.ChangeEvent<HTMLTextAreaElement>) => void` | - | 变更处理函数。 | | `placeholder` | `string` | - | 占位符文本。 | | `disabled` | `boolean` | `false` | 禁用 TextArea。 | | `readOnly` | `boolean` | `false` | 将 TextArea 设为只读。 | | `required` | `boolean` | `false` | 将 TextArea 标记为必填。 | | `name` | `string` | - | 表单提交时使用的 name。 | | `autoComplete` | `string` | - | 浏览器自动完成提示。 | | `maxLength` | `number` | - | 最大字符数。 | | `minLength` | `number` | - | 最小字符数。 | | `wrap` | `'soft' \| 'hard'` | - | 提交时文本如何换行。 | | `fullWidth` | `boolean` | `false` | TextArea 是否占满容器宽度 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 组件的视觉变体。`primary` 为默认带阴影样式。`secondary` 为弱强调、无阴影变体，适合用于 surface 上。 | > 对于 `isInvalid`、`isRequired` 等校验 prop 以及错误处理，请将 TextArea 作为子组件与 **[TextField](/docs/react/components/text-field)** 一起使用。 ## 相关案例 ## 相关组件 ## 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 </page> <page url="/cn/docs/react/components/text-field"> # TextField 文本输入框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/text-field **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(forms)/text-field.mdx > 便于组合的文本字段，包含标签、说明与内联校验。 ## 用法 ```tsx import { TextField } from '@heroui/react'; ``` ```tsx import {Input, Label, TextField} from "@heroui/react"; export function Basic() { return ( <TextField className="w-full max-w-64" name="email" type="email"> <Label>邮箱</Label> <Input placeholder="输入你的邮箱" /> </TextField> ); } ``` ## 组件结构 ```tsx import {TextField, Label, Input, Description, FieldError} from '@heroui/react'; export default () => ( <TextField> <Label /> <Input /> <Description /> <FieldError /> </TextField> ) ``` > **TextField** 将标签、输入、说明与错误信息整合为单个无障碍组件。若只需独立输入，请使用 **[Input](/docs/react/components/input)** 或 **[TextArea](/docs/react/components/text-area)**。 ## 示例 ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请在 Input 或 TextArea 组件上使用 `variant="secondary"`，以应用适合表面背景的低强调变体。 ```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>你的姓名</Label> <Input className="w-full" placeholder="John" /> <Description>我们绝不会与他人分享此信息</Description> </TextField> <TextField name="email" type="email" variant="secondary"> <Label>邮箱</Label> <Input className="w-full" placeholder="john@example.com" /> </TextField> <TextField name="bio" variant="secondary"> <Label>个人简介</Label> <TextArea className="w-full" placeholder="介绍一下你自己…" rows={4} /> <Description>至少 4 行</Description> </TextField> </Surface> ); } ``` ### 带描述 ```tsx import {Description, Input, Label, TextField} from "@heroui/react"; export function WithDescription() { return ( <TextField className="w-full max-w-64" name="username"> <Label>用户名</Label> <Input placeholder="输入用户名" /> <Description>为你的账户选择一个唯一的用户名</Description> </TextField> ); } ``` ### 必填字段 ```tsx import {Description, Input, Label, TextField} from "@heroui/react"; export function Required() { return ( <TextField isRequired className="w-full max-w-64" name="fullName"> <Label>全名</Label> <Input placeholder="John Doe" /> <Description>此字段为必填项</Description> </TextField> ); } ``` ### 禁用状态 ```tsx import {Description, Input, Label, TextField} from "@heroui/react"; export function Disabled() { return ( <TextField isDisabled className="w-full max-w-64" name="accountId" value="USR-12345"> <Label>账户 ID</Label> <Input placeholder="自动生成" /> <Description>此字段不可编辑</Description> </TextField> ); } ``` ### 宽度充满 ```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>你的姓名</Label> <Input placeholder="John" /> </TextField> <TextField fullWidth isInvalid isRequired name="password" type="password"> <Label>密码</Label> <Input /> <FieldError>密码长度必须超过 8 个字符</FieldError> </TextField> </div> ); } ``` ### 表单校验 将 `isInvalid` 与 `FieldError` 配合使用，以展示校验消息。 ```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" value={username} onChange={setUsername} > <Label>用户名</Label> <Input placeholder="jane_doe" /> {isUsernameInvalid ? ( <FieldError>用户名至少需要 3 个字符。</FieldError> ) : ( <Description>为你的资料选择一个唯一的用户名。</Description> )} </TextField> <TextField isRequired isInvalid={isBioInvalid} name="bio" value={bio} onChange={setBio}> <Label>个人简介</Label> <TextArea placeholder="介绍一下你自己…" /> {isBioInvalid ? ( <FieldError>个人简介至少需要 20 个字符。</FieldError> ) : ( <Description>至少 20 个字符 ({bio.length}/20).</Description> )} </TextField> </div> ); } ``` ### 受控组件 控制 value 以同步计数器、预览或格式化逻辑。 ```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" value={name} onChange={setName}> <Label>显示名称</Label> <Input placeholder="Jane" /> <Description>字符数： {name.length}</Description> </TextField> <TextField name="bio" value={bio} onChange={setBio}> <Label>个人简介</Label> <TextArea placeholder="介绍一下你自己…" /> <Description>字符数： {bio.length} / 200</Description> </TextField> </div> ); } ``` ### 错误信息 ```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>邮箱</Label> <Input placeholder="user@example.com" /> <FieldError>请输入有效的邮箱地址</FieldError> </TextField> ); } ``` ### 文本域 多行内容请使用 [TextArea](/docs/react/components/text-area)，而非 [Input](/docs/react/components/input)。 ```tsx import {Description, Label, TextArea, TextField} from "@heroui/react"; export function TextAreaExample() { return ( <TextField className="w-full max-w-64" name="message"> <Label>消息</Label> <TextArea placeholder="在此输入你的消息…" rows={4} /> <Description>最多 500 个字符</Description> </TextField> ); } ``` ### Input 类型 ```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>密码</Label> <Input placeholder="••••••••" /> </TextField> <TextField name="age" type="number"> <Label>年龄</Label> <Input max="150" min="0" placeholder="21" /> </TextField> <TextField name="email" type="email"> <Label>邮箱</Label> <Input placeholder="user@example.com" /> </TextField> <TextField name="website" type="url"> <Label>网站</Label> <Input placeholder="https://example.com" /> </TextField> <TextField name="phone" type="tel"> <Label>电话</Label> <Input placeholder="+1 (555) 000-0000" /> </TextField> </div> ); } ``` ### 渲染函数 ```tsx "use client"; import {Input, Label, TextField} from "@heroui/react"; export function RenderFunction() { return ( <TextField className="w-full max-w-64" name="email" render={(props) => <div {...props} data-custom="foo" />} type="email" > <Label>邮箱</Label> <Input placeholder="输入你的邮箱" /> </TextField> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Input, Label, TextField} from "@heroui/react"; const fieldClass = "rounded-xl border border-border/80 bg-surface shadow-sm ring-1 ring-black/5 transition-[box-shadow,border-color] focus-visible:ring-2 focus-visible:ring-neutral-400/25 dark:ring-white/10 dark:focus-visible:ring-neutral-500/30"; export function CustomStyles() { return ( <TextField className="w-full max-w-64 gap-1.5" name="email" type="email"> <Label className="font-medium text-neutral-800 dark:text-neutral-100">邮箱</Label> <Input className={`text-sm text-neutral-800 placeholder:text-neutral-400 dark:text-neutral-100 dark:placeholder:text-neutral-500 ${fieldClass}`} placeholder="输入你的邮箱" /> </TextField> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```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; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 * `.textfield` – 根容器，样式极少（`flex flex-col gap-1`） > **提示：** 子组件（[Label](/docs/react/components/label)、[Input](/docs/react/components/input)、[TextArea](/docs/react/components/text-area)、[Description](/docs/react/components/description)、[FieldError](/docs/react/components/field-error)）各自拥有 CSS 类与样式，定制方式请参见对应文档。 ### 交互状态 TextField 会根据状态自动管理以下 data 属性： * **无效**：`[data-invalid="true"]` 或 `[aria-invalid="true"]` — 无效时自动隐藏 description 插槽 * **禁用**：`[data-disabled="true"]` — 在 `isDisabled` 为 true 时应用 * **焦点在内部**：`[data-focus-within="true"]` — 任一子级 input 聚焦时应用 * **可见焦点**：`[data-focus-visible="true"]` — 键盘导航产生可见焦点时应用 更多属性可通过 render prop 获取（见下文 TextFieldRenderProps）。 ## API 参考 ### TextField 继承 React Aria [TextField](https://react-spectrum.adobe.com/react-aria/TextField.html) 的全部 props。 #### Base Props | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------ | ------- | ------------------------ | | `children` | `React.ReactNode \| (values: TextFieldRenderProps) => React.ReactNode` | - | 子组件（Label、Input 等）或渲染函数。 | | `className` | `string \| (values: TextFieldRenderProps) => string` | - | 用于样式的 CSS 类，支持渲染 prop。 | | `style` | `React.CSSProperties \| (values: TextFieldRenderProps) => React.CSSProperties` | - | 行内样式，支持渲染 prop。 | | `fullWidth` | `boolean` | `false` | TextField 是否占满容器宽度。 | | `id` | `string` | - | 元素的唯一 id。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TextFieldRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | #### Validation Props | Prop | 类型 | 默认值 | 描述 | | -------------------- | ----------------------------------------------------------------- | ---------- | ------------------------- | | `isRequired` | `boolean` | `false` | 提交表单前是否必须填写。 | | `isInvalid` | `boolean` | - | 当前值是否无效。 | | `validate` | `(value: string) => ValidationError \| true \| null \| undefined` | - | 自定义校验函数。 | | `validationBehavior` | `'native' \| 'aria'` | `'native'` | 使用原生 HTML 表单校验还是 ARIA 属性。 | | `validationErrors` | `string[]` | - | 服务端校验错误。 | #### Value Props | Prop | 类型 | 默认值 | 描述 | | -------------- | ------------------------- | --- | -------------- | | `value` | `string` | - | 当前值（受控）。 | | `defaultValue` | `string` | - | 默认值（非受控）。 | | `onChange` | `(value: string) => void` | - | 值变化时调用的事件处理函数。 | #### State Props | Prop | 类型 | 默认值 | 描述 | | ------------ | --------- | --- | ----------- | | `isDisabled` | `boolean` | - | 是否禁用输入。 | | `isReadOnly` | `boolean` | - | 是否可选中但不可修改。 | #### Form Props | Prop | 类型 | 默认值 | 描述 | | ----------- | --------- | --- | ----------------------- | | `name` | `string` | - | 用于 HTML 表单提交的 input 名称。 | | `autoFocus` | `boolean` | - | 是否在挂载时自动聚焦。 | #### Accessibility Props | Prop | 类型 | 默认值 | 描述 | | ------------------ | -------- | --- | -------------- | | `aria-label` | `string` | - | 无可见标签时的无障碍标签。 | | `aria-labelledby` | `string` | - | 用于标注该字段的元素 id。 | | `aria-describedby` | `string` | - | 用于描述该字段的元素 id。 | | `aria-details` | `string` | - | 提供附加详情的元素 id。 | ### Composition Components TextField 与以下独立组件配合使用，请直接按需引入并组合： * **Label** — `@heroui/react` 的字段标签组件 * **Input** — `@heroui/react` 的单行文本输入 * **TextArea** — `@heroui/react` 的多行文本输入 * **Description** — `@heroui/react` 的辅助说明组件 * **FieldError** — `@heroui/react` 的校验错误信息组件 这些组件各自有独立的 props API，请在 TextField 内直接使用： ```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 对 `className`、`style` 或 `children` 使用渲染 prop 时，可使用以下值： | Prop | 类型 | 描述 | | ---------------- | --------- | ---------------------------------- | | `isDisabled` | `boolean` | 字段是否禁用。 | | `isInvalid` | `boolean` | 字段当前是否无效。 | | `isReadOnly` | `boolean` | 字段是否只读。 | | `isRequired` | `boolean` | 字段是否必填。 | | `isFocused` | `boolean` | 字段是否聚焦（已弃用 — 请使用 `isFocusWithin`）。 | | `isFocusWithin` | `boolean` | 是否有任一子元素聚焦。 | | `isFocusVisible` | `boolean` | 是否为可见键盘焦点。 | ## 相关案例 ## 相关组件 ## 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 </page> <page url="/cn/docs/react/components/card"> # Card 卡片 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/card **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(layout)/card.mdx > 灵活容器组件，用于分组相关内容与操作 ## 用法 ```tsx import { Card } from "@heroui/react"; ``` ```tsx import {CircleDollar} from "@gravity-ui/icons"; import {Card, Link} from "@heroui/react"; export function Default() { return ( <Card className="w-[400px]"> <CircleDollar aria-label="美元图标" className="text-primary size-6" role="img" /> <Card.Header> <Card.Title>成为 Acme 创作者！</Card.Title> <Card.Description> 前往 Acme 创作者中心立即注册，开始从粉丝与支持者处获得积分奖励。 </Card.Description> </Card.Header> <Card.Footer> <Link aria-label="前往 Acme 创作者中心（在新标签页打开）" href="https://heroui.com" rel="noopener noreferrer" target="_blank" > 创作者中心 <Link.Icon aria-hidden="true" /> </Link> </Card.Footer> </Card> ); } ``` ## 组件结构 ```tsx import { Card } from "@heroui/react"; export default () => ( <Card> <Card.Header> <Card.Title /> <Card.Description /> </Card.Header> <Card.Content /> <Card.Footer /> </Card> ); ``` ## 示例 ### 变体 Card 提供语义变体，描述 prominence 级别而非具体视觉样式，允许主题以不同方式解读： ```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>透明</Card.Title> <Card.Description>背景透明，视觉层级较低（transparent）</Card.Description> </Card.Header> <Card.Content> <p>适合次要内容或嵌套在其它容器中的卡片</p> </Card.Content> </Card> <Card className="w-[320px]" variant="default"> <Card.Header> <Card.Title>默认</Card.Title> <Card.Description>标准外观（bg-surface）</Card.Description> </Card.Header> <Card.Content> <p>大多数场景的默认卡片变体</p> </Card.Content> </Card> <Card className="w-[320px]" variant="secondary"> <Card.Header> <Card.Title>次要</Card.Title> <Card.Description>中等强调（bg-surface-secondary）</Card.Description> </Card.Header> <Card.Content> <p>用于需要适度吸引注意力的内容</p> </Card.Content> </Card> <Card className="w-[320px]" variant="tertiary"> <Card.Header> <Card.Title>第三</Card.Title> <Card.Description>更高强调（bg-surface-tertiary）</Card.Description> </Card.Header> <Card.Content> <p>适合主要内容或需要突出的展示位</p> </Card.Content> </Card> </div> ); } ``` * **`transparent`** - 最低 prominence，透明背景（适合嵌套卡片） * **`default`** - 大多数场景的标准卡片（surface-secondary） * **`secondary`** - 中等 prominence 以吸引适度注意（surface-tertiary） * **`tertiary`** - 更高 prominence 用于重要内容（surface-tertiary） ### 水平布局 ```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="樱桃" 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="pe-8">成为 ACME 创作者！</Card.Title> <Card.Description> 这是一段占位说明文字，用于展示横向卡片布局、配图与右上角关闭按钮的排版效果。 </Card.Description> <CloseButton aria-label="关闭横幅" className="absolute end-3 top-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">仅剩 10 个名额</span> <span className="text-xs text-muted">报名截止：10 月 10 日</span> </div> <Button className="w-full sm:w-auto">立即申请</Button> </Card.Footer> </div> </Card> ); } ``` ### 带头像 ```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="独立创客社区" 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 位成员</Card.Description> </Card.Header> <Card.Footer className="flex gap-2"> <Avatar aria-label="玛莎的头像" className="size-5"> <Avatar.Image alt="玛莎的头像" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg" /> <Avatar.Fallback className="text-xs">IH</Avatar.Fallback> </Avatar> <span className="text-xs">创建者：玛莎</span> </Card.Footer> </Card> <Card className="w-[200px] gap-2"> <img alt="AI 开发者社区" 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 位成员</Card.Description> </Card.Header> <Card.Footer className="flex gap-2"> <Avatar aria-label="约翰的头像" className="size-5"> <Avatar.Image alt="约翰的头像" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback className="text-xs">B</Avatar.Fallback> </Avatar> <span className="text-xs">创建者：约翰</span> </Card.Footer> </Card> </div> ); } ``` ### 带图片 ```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"> {/* 第 1 行：大图商品卡 */} <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="樱桃" 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="pe-8">成为 ACME 创作者！</Card.Title> <Card.Description> 这是一段占位说明文字，用于展示横向卡片布局、配图与右上角关闭按钮的排版效果。 </Card.Description> <CloseButton aria-label="关闭横幅" className="absolute end-3 top-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">仅剩 10 个名额</span> <span className="text-xs text-muted">报名截止：10 月 10 日</span> </div> <Button className="w-full sm:w-auto">立即申请</Button> </Card.Footer> </div> </Card> {/* 第 2 行 */} <div className="col-span-12 grid grid-cols-12 gap-4"> {/* 左栏 */} <div className="col-span-12 grid grid-cols-12 gap-4 lg:col-span-6"> {/* 上方卡片 */} <Card className="col-span-12"> <div className="absolute end-3 top-3 z-10"> <CloseButton aria-label="关闭通知" /> </div> <Card.Header className="gap-3"> <CircleDollar aria-label="美元图标" 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">支付</span> <Card.Title className="pe-8 text-sm sm:text-base"> 现已支持加密货币提现 </Card.Title> <Card.Description className="text-xs sm:text-sm"> 在设置中添加钱包即可提现 </Card.Description> </div> </Card.Header> <Card.Footer> <Link aria-label="前往设置" href="#" rel="noopener noreferrer"> 前往设置 <Link.Icon aria-hidden="true" /> </Link> </Card.Footer> </Card> {/* 下方小卡 */} <div className="col-span-12 grid grid-cols-12 gap-4"> {/* 左卡 */} <Card className="col-span-12 gap-2 sm:col-span-6"> <Card.Header> <Avatar className="size-[56px] rounded-xl"> <Avatar.Image alt="演示图片 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 位成员</p> </Card.Content> <Card.Footer className="flex items-center gap-2"> <Avatar className="size-4"> <Avatar.Image alt="约翰" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg" /> <Avatar.Fallback>JK</Avatar.Fallback> </Avatar> <p className="text-xs text-muted">创建者：约翰</p> </Card.Footer> </Card> {/* 右卡 */} <Card className="col-span-12 gap-2 sm:col-span-6"> <Card.Header> <Avatar className="size-[56px] rounded-xl"> <Avatar.Image alt="演示图片 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 位成员</p> </Card.Content> <Card.Footer className="flex items-center gap-2"> <Avatar className="size-4"> <Avatar.Image alt="玛莎" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>M</Avatar.Fallback> </Avatar> <p className="text-xs text-muted">创建者：玛莎</p> </Card.Footer> </Card> </div> </div> {/* 右栏 */} <Card className="col-span-12 min-h-[200px] overflow-hidden rounded-3xl lg:col-span-6"> {/* 背景图 */} <img alt="NEO 家用机器人" aria-hidden="true" className="absolute inset-0 h-full w-full object-cover" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/neo2.jpeg" /> {/* 标题区 */} <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"> 家用机器人 </Card.Description> </Card.Header> {/* 底部 */} <Card.Footer className="z-10 mt-auto flex items-center justify-between"> <div> <div className="text-sm font-medium text-black">即将推出</div> <div className="text-xs text-black/60">接收上架通知</div> </div> <Button className="bg-white text-black" size="sm" variant="tertiary"> 通知我 </Button> </Card.Footer> </Card> </div> {/* 第 3 行 */} <div className="col-span-12 grid grid-cols-12 gap-4"> {/* 左：大图卡 */} <Card className="relative col-span-12 h-[250px] sm:h-[300px] md:col-span-8 md:h-[350px]"> <img alt="NEO 家用机器人" 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/月</div> </div> <Button className="bg-white text-black" size="sm" variant="tertiary"> 立即购买 </Button> </Card.Footer> </Card> {/* 右：堆叠小卡 */} <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="未来感机器人" 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">连接未来</Card.Title> <Card.Description className="text-xs">今天 18:30</Card.Description> </div> </Card> {/* 2 */} <Card className="flex flex-row gap-3 p-1" variant="transparent"> <img alt="牛油果" 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">牛油果黑客松</Card.Title> <Card.Description className="text-xs">周三 16:30</Card.Description> </div> </Card> {/* 3 */} <Card className="flex flex-row gap-3 p-1" variant="transparent"> <img alt="Sound Electro 活动" 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｜超越艺术</Card.Title> <Card.Description className="text-xs">周五 20:00</Card.Description> </div> </Card> </div> </div> </div> </div> ); } ``` ### 搭配表单 ```tsx "use client"; import {Button, Card, Form, Input, Label, Link, TextField} from "@heroui/react"; export function WithForm() { const onSubmit = (e: React.SyntheticEvent<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("表单提交成功！"); }; return ( <Card className="w-full max-w-md"> <Card.Header> <Card.Title>登录</Card.Title> <Card.Description>输入账号信息以访问您的账户</Card.Description> </Card.Header> <Form onSubmit={onSubmit}> <Card.Content> <div className="flex flex-col gap-4"> <TextField name="email" type="email"> <Label>邮箱</Label> <Input placeholder="email@example.com" variant="secondary" /> </TextField> <TextField name="password" type="password"> <Label>密码</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"> 登录 </Button> <Link className="text-center text-sm" href="#"> 忘记密码？ </Link> </Card.Footer> </Form> </Card> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Check, Star} from "@gravity-ui/icons"; import {Button, Card} from "@heroui/react"; const PRO_FEATURES = ["无限项目与协作者", "优先支持，24 小时响应", "高级分析与导出"] as const; export function CustomStyles() { return ( <Card className="relative w-full max-w-md overflow-hidden border border-accent/20 bg-linear-to-br from-accent/12 via-surface to-surface-secondary shadow-lg shadow-accent/10 dark:border-accent/30 dark:from-accent/20 dark:via-surface dark:to-accent/8 dark:shadow-accent/5"> <div aria-hidden="true" className="pointer-events-none absolute -top-12 -right-12 size-40 rounded-full bg-accent/20 blur-3xl dark:bg-accent/30" /> <div aria-hidden="true" className="pointer-events-none absolute -bottom-8 -left-8 size-28 rounded-full bg-accent/10 blur-2xl dark:bg-accent/20" /> <Card.Header className="relative gap-3"> <span className="w-fit rounded-full bg-accent/15 px-2.5 py-0.5 text-xs font-medium tracking-wide text-accent dark:bg-accent/25 dark:text-accent-soft-foreground"> 推荐 </span> <div className="flex items-start gap-3"> <div className="flex size-10 shrink-0 items-center justify-center rounded-xl bg-accent/15 text-accent dark:bg-accent/20 dark:text-accent-soft-foreground"> <Star aria-hidden="true" className="size-5" /> </div> <div className="flex flex-col gap-1"> <Card.Title>升级到 Pro</Card.Title> <Card.Description>解锁面向成长型产品的团队工作流与洞察。</Card.Description> </div> </div> </Card.Header> <Card.Content className="relative"> <ul className="flex flex-col gap-2"> {PRO_FEATURES.map((feature) => ( <li key={feature} className="flex items-center gap-2 text-sm text-muted"> <Check aria-hidden="true" className="size-4 shrink-0 text-accent" /> {feature} </li> ))} </ul> </Card.Content> <Card.Footer className="relative flex-col gap-2 sm:flex-row"> <Button className="w-full shadow-md shadow-accent/20">立即升级</Button> <Button className="w-full" variant="secondary"> 对比方案 </Button> </Card.Footer> </Card> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Card 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .card--secondary { @apply bg-gradient-to-br from-blue-50 to-purple-50; } .card__title { @apply text-xl font-bold; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Card 使用 [BEM](https://getbem.com/) 命名以实现可预测的样式（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/card.css)）： #### 基础类 \[!toc] * `.card` - 带 padding 与边框的基础容器 * `.card__header` - 头部区域容器 * `.card__title` - 基础字号与字重的标题 * `.card__description` - 弱化描述文本 * `.card__content` - 灵活内容容器 * `.card__footer` - 行布局的页脚 #### 变体类 \[!toc] * `.card--transparent` - 最低 prominence，透明背景（对应 `transparent` 变体） * `.card--default` - 标准外观，surface-secondary（默认） * `.card--secondary` - 中等 prominence，surface-tertiary（对应 `secondary` 变体） * `.card--tertiary` - 更高 prominence，surface-tertiary（对应 `tertiary` 变体） ## API 参考 ### Card | Prop | 类型 | 默认值 | 描述 | | ----------- | --------------------------------------------------------- | ----------- | --------------------- | | `variant` | `"transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | 表示 prominence 级别的语义变体 | | `className` | `string` | - | 附加 CSS 类 | | `children` | `React.ReactNode` | - | 卡片内容 | ### Card.Header | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | -------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `React.ReactNode` | - | 头部内容 | ### Card.Title | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | -------------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `React.ReactNode` | - | 标题内容（渲染为 `h3`） | ### Card.Description | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ------------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `React.ReactNode` | - | 描述内容（渲染为 `p`） | ### Card.Content | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | -------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `React.ReactNode` | - | 主要内容 | ### Card.Footer | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | -------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `React.ReactNode` | - | 页脚内容 | ## 无障碍 ```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 </page> <page url="/cn/docs/react/components/separator"> # Separator 分隔符 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/separator **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(layout)/separator.mdx > 在内容区块之间进行视觉分隔。 ## 用法 ```tsx import { Separator } from '@heroui/react'; ``` ```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 组件</h4> <p className="text-small text-default-400">美观、快速、现代的 React UI 库。</p> </div> <Separator className="my-4" /> <div className="text-small flex h-5 items-center space-x-4"> <div>博客</div> <Separator orientation="vertical" /> <div>文档</div> <Separator orientation="vertical" /> <div>源码</div> </div> </div> ); } ``` ## 示例 ### 变体 ```tsx import {Separator} from "@heroui/react"; export function Variants() { return ( <div className="flex max-w-md flex-col items-center gap-3"> <div>默认变体</div> <Separator variant="default" /> <div>次要变体</div> <Separator variant="secondary" /> <div>第三变体</div> <Separator variant="tertiary" /> </div> ); } ``` ### 与 Surface 组合 Separator 组件会根据不同的表面背景自动适配，以获得更好的可见性。 ```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">默认表面</h3> <Separator /> <p className="text-sm text-muted">表面内容</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">次要表面</h3> <Separator variant="secondary" /> <p className="text-sm text-muted">表面内容</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">第三表面</h3> <Separator variant="tertiary" /> <p className="text-sm text-muted">表面内容</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">透明表面</h3> <Separator /> <p className="text-sm text-muted">表面内容</p> </Surface> </div> </div> ); } ``` ### 垂直方向 ```tsx import {Separator} from "@heroui/react"; export function Vertical() { return ( <div className="text-small flex h-5 items-center space-x-4"> <div>博客</div> <Separator orientation="vertical" /> <div>文档</div> <Separator orientation="vertical" /> <div>源码</div> </div> ); } ``` ### 带内容 ```tsx import {Separator} from "@heroui/react"; const items = [ { iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png", subtitle: "接收账户活动更新", title: "设置通知", }, { iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png", subtitle: "将浏览器连接到你的账户", title: "设置浏览器扩展", }, { iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png", subtitle: "创建你的第一件收藏品", title: "铸造收藏品", }, ]; 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> ); } ``` ### 装饰性分隔线 当分隔线仅用于视觉装饰（例如列表框分区之间的分隔线）时，使用 `isDecorative`。默认渲染带有 `aria-hidden` 和呈现性语义的 `div`，同时保留视觉样式。自定义渲染函数会接收装饰性属性和 ref。 ```tsx <Separator isDecorative /> ``` ### 渲染函数 ```tsx "use client"; import {Separator} from "@heroui/react"; export function RenderFunction() { return ( <div className="max-w-md"> <div className="space-y-1"> <h4 className="text-medium font-medium">HeroUI v3 组件</h4> <p className="text-small text-default-400">美观、快速、现代的 React UI 库。</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>博客</div> <Separator orientation="vertical" render={(props) => <div {...props} data-custom="foo" />} /> <div>文档</div> <Separator orientation="vertical" render={(props) => <div {...props} data-custom="foo" />} /> <div>源码</div> </div> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Separator} from "@heroui/react"; export function CustomStyles() { return ( <div className="max-w-xs space-y-4"> <p className="text-sm font-medium text-foreground">账户设置</p> <Separator className="bg-separator-secondary" /> <div className="flex items-center gap-3 text-sm text-muted"> <span>个人资料</span> <Separator className="h-4 bg-separator" orientation="vertical" /> <span>账单</span> <Separator className="h-4 bg-separator" orientation="vertical" /> <span>安全</span> </div> </div> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Separator 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/separator.css)）： #### 基础类与方向类 \[!toc] * `.separator` - 基础 Separator 样式，默认水平方向 * `.separator--horizontal` - 水平方向（全宽，高度 1px） * `.separator--vertical` - 垂直方向（全高，宽度 1px） #### 变体类 \[!toc] * `.separator--default` - 默认变体，标准对比度 * `.separator--secondary` - 次要变体，中等对比度 * `.separator--tertiary` - 第三级变体，较弱对比度 ## API 参考 ### Separator | Prop | 类型 | 默认值 | 描述 | | -------------- | ----------------------------------------------------------------- | -------------- | ----------------------- | | `isDecorative` | `boolean` | `false` | 对辅助技术隐藏纯装饰性分隔线，并移除分隔符语义 | | `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Separator 的方向 | | `variant` | `'default' \| 'secondary' \| 'tertiary'` | `'default'` | Separator 的视觉变体 | | `className` | `string` | - | 额外的 CSS 类名 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 | ## 相关组件 ## Related Components * **Card**: Content container with header, body, and footer * **Chip**: Compact elements for tags and filters * **Avatar**: Display user profile images </page> <page url="/cn/docs/react/components/surface"> # Surface 表面 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/surface **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(layout)/surface.mdx > 提供表面级样式与子组件上下文的容器组件。 ## 用法 ```tsx import { Surface } from '@heroui/react'; ``` ```tsx import {Surface} from "@heroui/react"; export function Basic() { return ( <Surface className="flex min-w-[320px] flex-col gap-3 rounded-3xl p-6" variant="default"> <h3 className="text-base font-semibold text-foreground">表面内容</h3> <p className="text-sm text-muted">这是默认表面变体，使用 bg-surface 样式。</p> </Surface> ); } ``` ## 示例 ### 变体 Surface 提供描述 prominence 层级的语义变体： * **`default`** - 标准表面外观（bg-surface） * **`secondary`** - 中等 prominence（bg-surface-secondary） * **`tertiary`** - 较高 prominence（bg-surface-tertiary） ```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">默认</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">表面内容</h3> <p className="text-sm text-muted">这是默认表面变体，使用 bg-surface 样式。</p> </Surface> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">次要</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">表面内容</h3> <p className="text-sm text-muted">这是次要表面变体，使用 bg-surface-secondary 样式。</p> </Surface> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">第三</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">表面内容</h3> <p className="text-sm text-muted">这是第三表面变体，使用 bg-surface-tertiary 样式。</p> </Surface> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">透明</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">表面内容</h3> <p className="text-sm text-muted"> 这是透明表面变体，无背景，适用于遮罩层和自定义背景的卡片。 </p> </Surface> </div> </div> ); } ``` ### 搭配表单 在 Surface 内使用表单组件时，请使用 `variant="secondary"` 以应用适合表面背景的低强调变体。 ```tsx "use client"; import {Input, Surface, TextArea} from "@heroui/react"; export function WithFormComponents() { return ( <Surface className="flex min-w-[320px] flex-col gap-4 rounded-3xl p-6" variant="default"> <Input placeholder="使用次要变体的输入框" variant="secondary" /> <TextArea placeholder="使用次要变体的文本域" variant="secondary" /> </Surface> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Surface} from "@heroui/react"; export function CustomStyles() { return ( <Surface className="w-full max-w-sm rounded-xl border border-accent/15 bg-linear-to-br from-accent/8 via-surface to-surface-secondary p-4" variant="default" > <h3 className="text-sm font-semibold text-foreground">账单概览</h3> <p className="text-sm text-muted">在此查看发票和支付方式。</p> </Surface> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Surface 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/surface.css)）： #### 基础类 \[!toc] * `.surface` - Surface 根容器 #### 变体类 \[!toc] * `.surface--default` - 默认 Surface 变体（bg-surface） * `.surface--secondary` - Secondary Surface 变体（bg-surface-secondary） * `.surface--tertiary` - Tertiary Surface 变体（bg-surface-tertiary） ## API 参考 ### Surface | Prop | 类型 | 默认值 | 描述 | | ----------- | ---------------------------------------------------------- | ----------- | -------------- | | `variant` | ` "transparent" \| "default" \| "secondary" \| "tertiary"` | `"default"` | Surface 的视觉变体。 | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `ReactNode` | - | Surface 内容。 | ## Context API ### SurfaceContext 子组件可通过 Surface 上下文读取当前变体： ```tsx import { useContext } from 'react'; import { SurfaceContext } from '@heroui/react'; function MyComponent() { const { variant } = useContext(SurfaceContext); // variant 为 "transparent" | "default" | "secondary" | "tertiary" | undefined } ``` ## 相关组件 ## Related Components * **CheckboxGroup**: Group of checkboxes with shared state * **Fieldset**: Group related form controls with legends * **InputOTP**: One-time password input </page> <page url="/cn/docs/react/components/toolbar"> # Toolbar 工具栏 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/toolbar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(layout)/toolbar.mdx > 用于承载可交互控件的容器，并支持方向键导航。 ## 用法 ```tsx import { Toolbar } from '@heroui/react'; ``` ```tsx import {Bold, Copy, Italic, Scissors, Underline} from "@gravity-ui/icons"; import { Button, ButtonGroup, Separator, ToggleButton, ToggleButtonGroup, Toolbar, } from "@heroui/react"; export function Basic() { return ( <Toolbar aria-label="文本格式"> <ToggleButtonGroup aria-label="文本样式" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> <Separator /> <ButtonGroup variant="tertiary"> <Button isIconOnly aria-label="复制"> <Copy /> </Button> <Button isIconOnly aria-label="剪切"> <ButtonGroup.Separator /> <Scissors /> </Button> </ButtonGroup> </Toolbar> ); } ``` ## 示例 ### 垂直方向 ```tsx import {ArrowUturnCcwLeft, ArrowUturnCwRight, Bold, Italic, Underline} from "@gravity-ui/icons"; import { Button, ButtonGroup, Separator, ToggleButton, ToggleButtonGroup, Toolbar, } from "@heroui/react"; export function Vertical() { return ( <Toolbar aria-label="工具" orientation="vertical"> <ToggleButtonGroup aria-label="文本样式" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> <Separator /> <ButtonGroup variant="tertiary"> <Button isIconOnly aria-label="撤销"> <ArrowUturnCcwLeft /> </Button> <Button isIconOnly aria-label="重做"> <ButtonGroup.Separator /> <ArrowUturnCwRight /> </Button> </ButtonGroup> </Toolbar> ); } ``` ### 组合模式 ```tsx import {Bold, Copy, Italic, Scissors, Underline} from "@gravity-ui/icons"; import { Button, ButtonGroup, Separator, ToggleButton, ToggleButtonGroup, Toolbar, } from "@heroui/react"; export function Attached() { return ( <Toolbar isAttached aria-label="文本格式"> <ToggleButtonGroup aria-label="文本样式" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> <Separator /> <ButtonGroup variant="tertiary"> <Button isIconOnly aria-label="复制"> <Copy /> </Button> <Button isIconOnly aria-label="剪切"> <ButtonGroup.Separator /> <Scissors /> </Button> </ButtonGroup> </Toolbar> ); } ``` ### 与 ButtonGroup 组合 ```tsx import { ArrowUturnCcwLeft, ArrowUturnCwRight, Bold, Italic, TextAlignCenter, TextAlignLeft, TextAlignRight, Underline, } from "@gravity-ui/icons"; import { Button, ButtonGroup, Separator, ToggleButton, ToggleButtonGroup, Toolbar, } from "@heroui/react"; export function WithButtonGroup() { return ( <Toolbar aria-label="编辑器工具栏"> <ButtonGroup variant="tertiary"> <Button> <ArrowUturnCcwLeft /> 撤销 </Button> <Button> <ButtonGroup.Separator /> <ArrowUturnCwRight /> 重做 </Button> </ButtonGroup> <Separator /> <ToggleButtonGroup aria-label="文本样式" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" id="italic"> <ToggleButtonGroup.Separator /> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" id="underline"> <ToggleButtonGroup.Separator /> <Underline /> </ToggleButton> </ToggleButtonGroup> <Separator /> <ButtonGroup variant="tertiary"> <Button isIconOnly aria-label="左对齐"> <TextAlignLeft /> </Button> <Button isIconOnly aria-label="居中"> <ButtonGroup.Separator /> <TextAlignCenter /> </Button> <Button isIconOnly aria-label="右对齐"> <ButtonGroup.Separator /> <TextAlignRight /> </Button> </ButtonGroup> </Toolbar> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Bold, Italic, Underline} from "@gravity-ui/icons"; import {ToggleButton, ToggleButtonGroup, Toolbar} from "@heroui/react"; const toggleClass = "rounded-lg data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground"; export function CustomStyles() { return ( <Toolbar aria-label="格式工具栏" className="gap-1 rounded-xl border border-border/80 bg-surface-secondary p-1.5" > <ToggleButtonGroup aria-label="文本样式" className="gap-0.5" selectionMode="multiple"> <ToggleButton isIconOnly aria-label="粗体" className={toggleClass} id="bold"> <Bold /> </ToggleButton> <ToggleButton isIconOnly aria-label="斜体" className={toggleClass} id="italic"> <Italic /> </ToggleButton> <ToggleButton isIconOnly aria-label="下划线" className={toggleClass} id="underline"> <Underline /> </ToggleButton> </ToggleButtonGroup> </Toolbar> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .toolbar { @apply gap-4 rounded-lg bg-surface p-3; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Toolbar 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toolbar.css)）： * `.toolbar` - 基础容器 * `.toolbar--horizontal` - 水平方向（默认） * `.toolbar--vertical` - 垂直方向 * `.toolbar--attached` - Attached 变体：surface 背景与完全圆角 ## API 参考 ### Toolbar 继承 [React Aria Toolbar](https://react-spectrum.adobe.com/react-aria/Toolbar.html)。 | Prop | 类型 | 默认值 | 描述 | | ----------------- | -------------------------------------------------------------------- | -------------- | ----------------------------- | | `isAttached` | `boolean` | `false` | Toolbar 是否使用带完全圆角的 surface 背景 | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Toolbar 的方向 | | `aria-label` | `string` | - | Toolbar 的无障碍标签 | | `aria-labelledby` | `string` | - | 用于标注该 Toolbar 的元素 id | | `children` | `React.ReactNode \| (values: ToolbarRenderProps) => React.ReactNode` | - | 内容或渲染 prop | | `className` | `string \| (values: ToolbarRenderProps) => string` | - | 额外的 CSS 类名 | ### ToolbarRenderProps 使用渲染 prop 模式时，会提供以下值： | Prop | 类型 | 描述 | | ------------- | ---------------------------- | -------------- | | `orientation` | `"horizontal" \| "vertical"` | 当前 Toolbar 的方向 | ## 相关组件 ## Related Components * **ButtonGroup**: Group related buttons together * **ToggleButtonGroup**: Group multiple toggle buttons into a unified control * **Separator**: Visual divider between content </page> <page url="/cn/docs/react/components/avatar-group"> # AvatarGroup 头像组 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/avatar-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(media)/avatar-group.mdx > 以叠放或网格展示多个头像，并支持溢出计数 ## 用法 ```tsx import { AvatarGroup, Avatar } from '@heroui/react'; ``` ```tsx import {Avatar, AvatarGroup} from "@heroui/react"; const users = [ { id: 1, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", name: "张明", }, { id: 2, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", name: "李华", }, { id: 3, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", name: "王芳", }, { id: 4, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", name: "刘洋", }, { id: 5, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", name: "陈静", }, ]; function initialsFromName(name: string) { const parts = name.split(/\s+/).filter(Boolean); if (parts.length >= 2) { return parts.map((n) => n[0]).join(""); } return name.slice(0, 2); } export function Basic() { return ( <AvatarGroup> {users.slice(0, 4).map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={`${user.name} 的头像`} src={user.image} /> <Avatar.Fallback>{initialsFromName(user.name)}</Avatar.Fallback> </Avatar> ))} </AvatarGroup> ); } ``` ## 组件结构 ```tsx import { AvatarGroup, Avatar } from '@heroui/react'; export default () => ( <AvatarGroup> <Avatar> <Avatar.Image /> <Avatar.Fallback /> </Avatar> <AvatarGroup.Count /> {/* 可选的显式子组件 */} </AvatarGroup> ); ``` ## 示例 ### 最大数量 ```tsx import {Avatar, AvatarGroup} from "@heroui/react"; const users = [ { id: 1, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", name: "张明", }, { id: 2, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", name: "李华", }, { id: 3, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", name: "王芳", }, { id: 4, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", name: "刘洋", }, { id: 5, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", name: "陈静", }, ]; function initialsFromName(name: string) { const parts = name.split(/\s+/).filter(Boolean); if (parts.length >= 2) { return parts.map((n) => n[0]).join(""); } return name.slice(0, 2); } export function Max() { return ( <AvatarGroup max={3}> {users.map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={`${user.name} 的头像`} src={user.image} /> <Avatar.Fallback>{initialsFromName(user.name)}</Avatar.Fallback> </Avatar> ))} </AvatarGroup> ); } ``` ### 自定义计数 ```tsx import {Avatar, AvatarGroup} from "@heroui/react"; const users = [ { id: 1, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", name: "张明", }, { id: 2, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", name: "李华", }, { id: 3, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", name: "王芳", }, { id: 4, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", name: "刘洋", }, { id: 5, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", name: "陈静", }, ]; function initialsFromName(name: string) { const parts = name.split(/\s+/).filter(Boolean); if (parts.length >= 2) { return parts.map((n) => n[0]).join(""); } return name.slice(0, 2); } export function Count() { const total = 12; return ( <AvatarGroup size="sm"> {users.slice(0, 3).map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={`${user.name} 的头像`} src={user.image} /> <Avatar.Fallback>{initialsFromName(user.name)}</Avatar.Fallback> </Avatar> ))} <AvatarGroup.Count>+{total - 3}</AvatarGroup.Count> </AvatarGroup> ); } ``` ### 尺寸 ```tsx import {Avatar, AvatarGroup} from "@heroui/react"; const users = [ { id: 1, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", name: "张明", }, { id: 2, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", name: "李华", }, { id: 3, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", name: "王芳", }, { id: 4, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", name: "刘洋", }, { id: 5, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", name: "陈静", }, ]; function initialsFromName(name: string) { const parts = name.split(/\s+/).filter(Boolean); if (parts.length >= 2) { return parts.map((n) => n[0]).join(""); } return name.slice(0, 2); } export function Sizes() { return ( <div className="flex flex-col items-center gap-6"> <div className="flex flex-col items-center gap-2"> <p className="text-sm text-muted">小号</p> <AvatarGroup size="sm"> {users.slice(0, 4).map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={`${user.name} 的头像`} src={user.image} /> <Avatar.Fallback>{initialsFromName(user.name)}</Avatar.Fallback> </Avatar> ))} </AvatarGroup> </div> <div className="flex flex-col items-center gap-2"> <p className="text-sm text-muted">中号（默认）</p> <AvatarGroup size="md"> {users.slice(0, 4).map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={`${user.name} 的头像`} src={user.image} /> <Avatar.Fallback>{initialsFromName(user.name)}</Avatar.Fallback> </Avatar> ))} </AvatarGroup> </div> <div className="flex flex-col items-center gap-2"> <p className="text-sm text-muted">大号</p> <AvatarGroup size="lg"> {users.slice(0, 4).map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={`${user.name} 的头像`} src={user.image} /> <Avatar.Fallback>{initialsFromName(user.name)}</Avatar.Fallback> </Avatar> ))} </AvatarGroup> </div> </div> ); } ``` ### 网格 ```tsx import {Avatar, AvatarGroup} from "@heroui/react"; const users = [ { id: 1, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", name: "张明", }, { id: 2, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", name: "李华", }, { id: 3, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", name: "王芳", }, { id: 4, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/orange.jpg", name: "刘洋", }, { id: 5, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg", name: "陈静", }, ]; function initialsFromName(name: string) { const parts = name.split(/\s+/).filter(Boolean); if (parts.length >= 2) { return parts.map((n) => n[0]).join(""); } return name.slice(0, 2); } export function Grid() { return ( <AvatarGroup isGrid max={5}> {users.map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={`${user.name} 的头像`} src={user.image} /> <Avatar.Fallback>{initialsFromName(user.name)}</Avatar.Fallback> </Avatar> ))} </AvatarGroup> ); } ``` ### 叠放样式（Overlap） ```tsx import type {ReactNode} from "react"; import {Avatar, AvatarGroup} from "@heroui/react"; const STRIPE_STYLES = ` @keyframes ag-stripes { to { background-position: 24px 24px; } } .ag-stripes { background-color: color-mix(in oklab, var(--danger) 6%, var(--surface)); background-image: repeating-linear-gradient( -45deg, transparent 0 10px, color-mix(in oklab, var(--danger) 12%, transparent) 10px 11px, transparent 11px 21px, color-mix(in oklab, var(--danger) 28%, transparent) 21px 22px ); background-size: 24px 24px; animation: ag-stripes 2.8s linear infinite; } `; function StripeBackdrop({children}: {children: ReactNode}) { return ( <div className="relative inline-flex rounded-xl p-6"> <div aria-hidden className="ag-stripes pointer-events-none absolute inset-0 rounded-xl" /> <div className="relative z-10">{children}</div> </div> ); } function DemoGroup({overlap}: {overlap: "clip" | "ring"}) { return ( <AvatarGroup overlap={overlap} size="lg"> <Avatar> <Avatar.Image alt="John" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Avatar> <Avatar.Fallback>AB</Avatar.Fallback> </Avatar> <Avatar> <Avatar.Image alt="Emily" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" /> <Avatar.Fallback>EC</Avatar.Fallback> </Avatar> <Avatar> <Avatar.Fallback>SM</Avatar.Fallback> </Avatar> <AvatarGroup.Count>+2</AvatarGroup.Count> </AvatarGroup> ); } export function Overlap() { return ( <div className="flex flex-col items-start gap-6"> <style>{STRIPE_STYLES}</style> <div className="flex flex-col gap-2"> <p className="text-sm text-muted">clip</p> <StripeBackdrop> <DemoGroup overlap="clip" /> </StripeBackdrop> </div> <div className="flex flex-col gap-2"> <p className="text-sm text-muted">ring</p> <StripeBackdrop> <DemoGroup overlap="ring" /> </StripeBackdrop> </div> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Person} from "@gravity-ui/icons"; import {Avatar, AvatarGroup} from "@heroui/react"; const assignees = [ { id: 1, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg", name: "张明", }, { id: 2, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/green.jpg", name: "李华", }, { id: 3, image: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg", name: "王芳", }, ] as const; export function CustomStyles() { return ( <div className="inline-flex items-center gap-2.5 rounded-full border border-border/70 bg-surface/95 py-1 pr-3 pl-1 shadow-sm ring-1 ring-black/[0.04] dark:border-border/80 dark:bg-surface/90 dark:ring-white/10"> <AvatarGroup aria-label="指派人" className="[--avatar-group-overlap:0.7rem] [--avatar-group-seam:2px]" overlap="clip" role="group" size="sm" > {assignees.map((user) => ( <Avatar key={user.id}> <Avatar.Image alt={`${user.name} 的头像`} src={user.image} /> <Avatar.Fallback>{user.name.slice(0, 1)}</Avatar.Fallback> </Avatar> ))} <Avatar> <Avatar.Fallback> <Person className="size-4 shrink-0" /> </Avatar.Fallback> </Avatar> <AvatarGroup.Count>+3</AvatarGroup.Count> </AvatarGroup> <span className="text-sm font-medium text-foreground">指派人</span> </div> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 AvatarGroup 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .avatar-group { --avatar-group-overlap: 0.75rem; --avatar-group-seam: 2px; } .avatar-group__count { @apply font-semibold; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 AvatarGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/avatar-group.css)）： #### 基础类 \[!toc] * `.avatar-group` - 头像组基础容器 * `.avatar-group--grid` - 网格布局修饰符（无叠放） * `.avatar-group--clip` - 沿相邻头像轮廓裁切出的透明缝（默认叠放） * `.avatar-group--ring` - 通过 `--background` 的实线 box-shadow 描边 * `.avatar-group__count` - 溢出计数头像 叠放布局在兄弟元素之间使用负外边距（`--avatar-group-overlap`，默认 `0.5rem`）。clip 模式对非末子头像做遮罩，并光学微调 fallback 字形；ring 模式使用 `--background` 细线 box-shadow 描边。 ## API 参考 ### AvatarGroup | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------- | -------- | ------------------------------------------------- | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 当子 Avatar 未指定 `size` 时应用到子头像（及溢出计数）；默认与 Avatar 一致 | | `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | 当子 Avatar 未指定 `color` 时，应用到子头像（及溢出计数）的颜色 | | `variant` | `'default' \| 'soft'` | - | 当子 Avatar 未指定 `variant` 时，应用到子头像（及溢出计数）的变体 | | `max` | `number` | - | 最多渲染的头像子项数量；省略则显示全部 | | `isGrid` | `boolean` | `false` | 是否使用无叠放的换行网格布局 | | `overlap` | `'clip' \| 'ring'` | `'clip'` | 叠放样式：透明缝裁切（默认）或 box-shadow 描边；`isGrid` 时忽略 | | `className` | `string` | - | 附加 CSS 类 | | `children` | `React.ReactNode` | - | 要组合的 Avatar 组件（以及可选的 `AvatarGroup.Count`） | ### AvatarGroup.Count 由 `Avatar` + `Avatar.Fallback` 组合而成，用于溢出指示。不受 `max` 截断。 | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------- | --- | ------------- | | `children` | `React.ReactNode` | - | 计数内容（例如 `+3`） | | `size` | `'sm' \| 'md' \| 'lg'` | - | 覆盖组的尺寸 | | `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | 覆盖组的颜色 | | `variant` | `'default' \| 'soft'` | - | 覆盖组的变体 | | `className` | `string` | - | 附加 CSS 类 | ## 注意事项 * AvatarGroup 通过 React Context 仅向**直接 Avatar 子组件**传递 `size`、`color` 与 `variant` * 设置 `max` 会截断可见头像并根据剩余子项自动计数；省略则显示全部 * 已知总量（例如来自服务端）时，渲染显式的 `AvatarGroup.Count` — 它不受 `max` 截断，并会抑制自动计数。请用 `Count` 替代已移除的 v2 `total` * `isGrid` 会禁用叠放，改为换行网格布局 * `overlap` 默认为 `"clip"`（透明缝裁切）；使用 `"ring"` 可改为实线描边；与 `isGrid` 同时使用时无效 * 默认不加 `role="group"` — 当叠放有语义（指派人、在看的人）时，自行加上 `role="group"`，并配合 `aria-label` 或 `aria-labelledby` ## 相关组件 ## Related Components * **Avatar**: Display user profile images * **Badge**: Small indicator positioned relative to another element * **Chip**: Compact elements for tags and filters </page> <page url="/cn/docs/react/components/avatar"> # Avatar 头像 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/avatar **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(media)/avatar.mdx > 显示用户头像，支持自定义 fallback 内容 ## 用法 ```tsx import { Avatar } from '@heroui/react'; ``` ```tsx import {Avatar} from "@heroui/react"; export function Basic() { return ( <div className="flex items-center gap-4"> <Avatar> <Avatar.Image alt="约翰·多伊" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3" /> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> <Avatar> <Avatar.Image alt="蓝色头像" 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> ); } ``` ## 组件结构 ```tsx import { Avatar } from '@heroui/react'; export default () => ( <Avatar> <Avatar.Image/> <Avatar.Fallback/> </Avatar> ) ``` ## 示例 ### 尺寸 ```tsx import {Avatar} from "@heroui/react"; export function Sizes() { return ( <div className="flex items-center gap-4"> <Avatar size="sm"> <Avatar.Image alt="小尺寸头像" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg" /> <Avatar.Fallback>SM</Avatar.Fallback> </Avatar> <Avatar size="md"> <Avatar.Image alt="中尺寸头像" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/purple.jpg" /> <Avatar.Fallback>MD</Avatar.Fallback> </Avatar> <Avatar size="lg"> <Avatar.Image alt="大尺寸头像" src="https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/red.jpg" /> <Avatar.Fallback>LG</Avatar.Fallback> </Avatar> </div> ); } ``` ### 颜色 ```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> ); } ``` ### 变体 ```tsx import {Person} from "@gravity-ui/icons"; import {Avatar, Separator} from "@heroui/react"; const colors = ["accent", "default", "success", "warning", "danger"] as const; const COLOR_LABELS: Record<(typeof colors)[number], string> = { accent: "强调", danger: "危险", default: "默认", success: "成功", warning: "警告", }; const variants = [ {content: "AG", label: "字母", type: "letter"}, {content: "AG", label: "柔和字母", type: "letter-soft"}, {content: <Person />, label: "图标", type: "icon"}, {content: <Person />, label: "柔和图标", 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: "图片", type: "img", }, ] as const; export function Variants() { return ( <div className="flex flex-col gap-4"> {/* 颜色列标题 */} <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">{COLOR_LABELS[color]}</span> </div> ))} </div> <Separator /> {/* 变体行 */} {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={`${COLOR_LABELS[color]} 头像`} src={Array.isArray(variant.content) ? variant.content[colorIndex] : ""} /> <Avatar.Fallback>{COLOR_LABELS[color].charAt(0)}</Avatar.Fallback> </> ) : ( <Avatar.Fallback>{variant.content}</Avatar.Fallback> )} </Avatar> </div> ))} </div> ))} </div> ); } ``` ### 回退内容 ```tsx import {Person} from "@gravity-ui/icons"; import {Avatar} from "@heroui/react"; export function Fallback() { return ( <div className="flex items-center gap-4"> {/* 文字回退 */} <Avatar> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> {/* 图标回退 */} <Avatar> <Avatar.Fallback> <Person /> </Avatar.Fallback> </Avatar> {/* 延迟显示回退 */} <Avatar> <Avatar.Image alt="延迟加载头像" src="https://invalid-url-to-show-fallback.com/image.jpg" /> <Avatar.Fallback delayMs={600}>NA</Avatar.Fallback> </Avatar> {/* 自定义样式回退 */} <Avatar> <Avatar.Fallback className="border-none bg-gradient-to-br from-pink-500 to-purple-500 text-white"> GB </Avatar.Fallback> </Avatar> </div> ); } ``` ## 自定义样式 ### 自定义图片组件 在 `Avatar.Image` 上使用 `asChild`，即可与自定义图片组件组合。以下示例使用 Next.js `Image` 以实现优化加载。请将 `src` 传给 `Avatar.Image`，以便跟踪加载状态，并在图片就绪前显示回退内容。 ```tsx import {Avatar} from "@heroui/react"; import Image from "next/image"; const SRC = "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/avatars/blue.jpg"; export function CustomImageComponent() { return ( <Avatar> <Avatar.Image asChild height={40} src={SRC} width={40}> <Image alt="约翰·多伊" src={SRC} /> </Avatar.Image> <Avatar.Fallback>JD</Avatar.Fallback> </Avatar> ); } ``` ### Tailwind CSS ```tsx import {Avatar} from "@heroui/react"; export function CustomStyles() { return ( <Avatar className="rounded-lg"> <Avatar.Image alt="张三" src="https://img.heroui.chat/image/avatar?w=400&h=400&u=3" /> <Avatar.Fallback className="rounded-lg">张三</Avatar.Fallback> </Avatar> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Avatar 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .avatar { @apply size-16 border-2 border-accent; } .avatar__fallback { @apply bg-gradient-to-br from-purple-500 to-pink-500; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Avatar 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/avatar.css)）： #### 基础类 \[!toc] * `.avatar` - 基础容器，默认尺寸（size-10） * `.avatar__image` - 图片元素，aspect-square 尺寸 * `.avatar__fallback` - 居中内容的 fallback 容器 #### 尺寸修饰符 \[!toc] * `.avatar--sm` - 小头像（size-8） * `.avatar--md` - 中头像（默认，无额外样式） * `.avatar--lg` - 大头像（size-12） #### 变体修饰符 \[!toc] * `.avatar--soft` - 浅色背景的 soft 变体 #### 颜色修饰符 \[!toc] * `.avatar__fallback--default` - 默认文字颜色 * `.avatar__fallback--accent` - 强调色文字 * `.avatar__fallback--success` - 成功色文字 * `.avatar__fallback--warning` - 警告色文字 * `.avatar__fallback--danger` - 危险色文字 ## API 参考 ### Avatar | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------- | ----------- | ------------- | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 头像尺寸 | | `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | `'default'` | Fallback 颜色主题 | | `variant` | `'default' \| 'soft'` | `'default'` | 视觉样式变体 | | `className` | `string` | - | 附加 CSS 类 | ### Avatar.Image | Prop | 类型 | 默认值 | 描述 | | ------------- | --------------------------------------------------- | ------- | ----------------------------------------- | | `src` | `string` | - | 图片 URL | | `srcSet` | `string` | - | 响应式图片的 `srcset` 属性 | | `sizes` | `string` | - | 响应式图片的 `sizes` 属性 | | `alt` | `string` | - | 图片替代文本 | | `asChild` | `boolean` | `false` | 将属性合并到子元素上（例如 `next/image`），而不是渲染原生 `img` | | `onLoad` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | 图片加载成功时的回调 | | `onError` | `(event: SyntheticEvent<HTMLImageElement>) => void` | - | 图片加载失败时的回调 | | `crossOrigin` | `'anonymous' \| 'use-credentials'` | - | 图片请求的 CORS 设置 | | `loading` | `'eager' \| 'lazy'` | - | 原生懒加载属性 | | `className` | `string` | - | 附加 CSS 类 | ### Avatar.Fallback | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------- | --- | ---------------------- | | `delayMs` | `number` | - | 显示 fallback 前的延迟（防止闪烁） | | `color` | `'default' \| 'accent' \| 'success' \| 'warning' \| 'danger'` | - | 覆盖父级颜色 | | `className` | `string` | - | 附加 CSS 类 | ## 相关组件 ## Related Components * **AvatarGroup**: Display a stacked or grid group of avatars * **Separator**: Visual divider between content * **Badge**: Small indicator positioned relative to another element </page> <page url="/cn/docs/react/components/accordion"> # Accordion 手风琴 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/accordion **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(navigation)/accordion.mdx > 用于在紧凑空间中组织信息的可折叠内容面板 ## 用法 ```tsx import { Accordion } from '@heroui/react'; ``` ```tsx import { ArrowsRotateLeft, Box, ChevronDown, CreditCard, PlanetEarth, Receipt, ShoppingBag, } from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; const items = [ { content: "浏览我们的商品，将商品加入购物车并前往结账。完成购买需要提供收货与支付信息。", icon: <ShoppingBag />, title: "如何下单？", }, { content: "可以，在订单发货前你可以修改或取消。订单一旦进入处理流程，将无法再更改。", icon: <Receipt />, title: "可以修改或取消订单吗？", }, { content: "我们接受主流信用卡，包括 Visa、Mastercard 和 American Express。", icon: <CreditCard />, title: "支持哪些支付方式？", }, { content: "运费因收货地址与订单体积而异。订单满 50 美元可享受免运费。", icon: <Box />, title: "运费如何计算？", }, { content: "是的，我们可向多数国家/地区发货。请查看运费说明与政策了解更多信息。", icon: <PlanetEarth />, title: "是否提供国际配送？", }, { content: "若对购买不满意，可在购买后 30 天内申请退款。请联系客服团队协助处理。", icon: <ArrowsRotateLeft />, title: "如何申请退款？", }, ]; 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="me-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> ); } ``` ## 组件结构 ```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> ) ``` ## 示例 ### 表面样式 ```tsx import { ArrowsRotateLeft, Box, ChevronDown, CreditCard, PlanetEarth, Receipt, ShoppingBag, } from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; const items = [ { content: "浏览我们的商品，将商品加入购物车并前往结账。完成购买需要提供收货与支付信息。", icon: <ShoppingBag />, title: "如何下单？", }, { content: "可以，在订单发货前你可以修改或取消。订单一旦进入处理流程，将无法再更改。", icon: <Receipt />, title: "可以修改或取消订单吗？", }, { content: "我们接受主流信用卡，包括 Visa、Mastercard 和 American Express。", icon: <CreditCard />, title: "支持哪些支付方式？", }, { content: "运费因收货地址与订单体积而异。订单满 50 美元可享受免运费。", icon: <Box />, title: "运费如何计算？", }, { content: "是的，我们可向多数国家/地区发货。请查看运费说明与政策了解更多信息。", icon: <PlanetEarth />, title: "是否提供国际配送？", }, { content: "若对购买不满意，可在购买后 30 天内申请退款。请联系客服团队协助处理。", icon: <ArrowsRotateLeft />, title: "如何申请退款？", }, ]; 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="me-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> ); } ``` ### 无分隔线 ```tsx import {ChevronDown, CreditCard, Receipt, ShoppingBag} from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; const items = [ { content: "浏览我们的商品，将商品加入购物车并前往结账。完成购买需要提供收货与支付信息。", icon: <ShoppingBag />, title: "如何下单？", }, { content: "可以，在订单发货前你可以修改或取消。订单一旦进入处理流程，将无法再更改。", icon: <Receipt />, title: "可以修改或取消订单吗？", }, { content: "我们接受主流信用卡，包括 Visa、Mastercard 和 American Express。", icon: <CreditCard />, title: "支持哪些支付方式？", }, ]; 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="me-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> ); } ``` ### 多项展开 ```tsx import {Accordion} from "@heroui/react"; export function Multiple() { return ( <Accordion allowsMultipleExpanded className="w-full max-w-md"> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> 快速开始 <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> 了解 HeroUI 的基础知识，以及如何将其集成到你的 React 项目中。本节涵盖安装、配置和你的第一个组件。 </Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> 核心概念 <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> 理解 HeroUI 背后的核心概念，包括复合组件模式、使用 Tailwind CSS 进行样式设计，以及无障碍特性。 </Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> 高级用法 <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> 探索高级特性，例如自定义变体、主题定制，以及与 React 生态中其他库的集成。 </Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> 最佳实践 <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> 遵循我们建议的最佳实践，使用 HeroUI 构建高性能、无障碍且易于维护的应用。 </Accordion.Body> </Accordion.Panel> </Accordion.Item> </Accordion> ); } ``` ### 禁用状态 ```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">整个手风琴禁用</h3> <Accordion isDisabled className="w-full max-w-md"> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> 禁用项 1 <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>手风琴禁用时无法查看此内容。</Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> 禁用项 2 <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>手风琴禁用时无法查看此内容。</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">单独禁用条目</h3> <Accordion className="w-full max-w-md"> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> 可用项 <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>此项可用，可正常展开与折叠。</Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item isDisabled> <Accordion.Heading> <Accordion.Trigger> 禁用项 <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>条目禁用时无法查看此内容。</Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item> <Accordion.Heading> <Accordion.Trigger> 另一可用项 <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>此项同样可用，可正常切换。</Accordion.Body> </Accordion.Panel> </Accordion.Item> </Accordion> </div> </div> ); } ``` ### 受控组件 ```tsx "use client"; import {ChevronDown, ChevronUp} from "@gravity-ui/icons"; import {Accordion, Button, useDisclosureGroupNavigation} from "@heroui/react"; import React from "react"; const items = [ { content: "了解 HeroUI 的基础知识，以及如何将其集成到你的 React 项目中。本节涵盖安装、配置和你的第一个组件。", id: "getting-started", title: "快速开始", }, { content: "理解 HeroUI 背后的核心概念，包括复合组件模式、使用 Tailwind CSS 进行样式设计，以及无障碍特性。", id: "core-concepts", title: "核心概念", }, { content: "探索高级特性，例如自定义变体、主题定制，以及与 React 生态中其他库的集成。", id: "advanced-usage", title: "高级用法", }, ]; export function Controlled() { const [expandedKeys, setExpandedKeys] = React.useState( new Set<string | number>(["getting-started"]), ); const itemIds = items.map((item) => item.id); const {isNextDisabled, isPrevDisabled, onNext, onPrevious} = useDisclosureGroupNavigation({ expandedKeys, itemIds, onExpandedChange: setExpandedKeys, }); return ( <div className="w-full max-w-md"> <div className="mb-4 flex items-center justify-between"> <p className="text-sm text-muted"> 已展开：<strong>{[...expandedKeys].join("、") || "无"}</strong> </p> <div className="flex gap-2"> <Button aria-label="上一项" isDisabled={isPrevDisabled} size="sm" variant="secondary" onPress={onPrevious} > <ChevronUp className="size-4" /> </Button> <Button aria-label="下一项" isDisabled={isNextDisabled} size="sm" variant="secondary" onPress={onNext} > <ChevronDown className="size-4" /> </Button> </div> </div> <Accordion expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}> {items.map((item) => ( <Accordion.Item key={item.id} id={item.id}> <Accordion.Heading> <Accordion.Trigger> {item.title} <Accordion.Indicator /> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>{item.content}</Accordion.Body> </Accordion.Panel> </Accordion.Item> ))} </Accordion> </div> ); } ``` ### 自定义指示器 ```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> 使用加号/减号图标 <Accordion.Indicator> {expandedKeys.has("1") ? <Minus /> : <Plus />} </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>折叠时显示加号图标，展开时切换为减号图标。</Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item id="2"> <Accordion.Heading> <Accordion.Trigger> 使用圆形箭头图标 <Accordion.Indicator> <CircleChevronDown /> </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body>此项使用圆形内的箭头作为指示器，旋转动画会自动应用。</Accordion.Body> </Accordion.Panel> </Accordion.Item> <Accordion.Item id="3"> <Accordion.Heading> <Accordion.Trigger> 使用双箭头图标 <Accordion.Indicator> <ChevronsDown /> </Accordion.Indicator> </Accordion.Trigger> </Accordion.Heading> <Accordion.Panel> <Accordion.Body> 此项使用双箭头图标。传入任意图标后，在条目展开时都会获得旋转动画。 </Accordion.Body> </Accordion.Panel> </Accordion.Item> </Accordion> ); } ``` ### 渲染函数 ```tsx "use client"; import { ArrowsRotateLeft, Box, ChevronDown, CreditCard, PlanetEarth, Receipt, ShoppingBag, } from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; const items = [ { content: "浏览我们的商品，将商品加入购物车并前往结账。完成购买需要提供收货与支付信息。", icon: <ShoppingBag />, title: "如何下单？", }, { content: "可以，在订单发货前你可以修改或取消。订单一旦进入处理流程，将无法再更改。", icon: <Receipt />, title: "可以修改或取消订单吗？", }, { content: "我们接受主流信用卡，包括 Visa、Mastercard 和 American Express。", icon: <CreditCard />, title: "支持哪些支付方式？", }, { content: "运费因收货地址与订单体积而异。订单满 50 美元可享受免运费。", icon: <Box />, title: "运费如何计算？", }, { content: "是的，我们可向多数国家/地区发货。请查看运费说明与政策了解更多信息。", icon: <PlanetEarth />, title: "是否提供国际配送？", }, { content: "若对购买不满意，可在购买后 30 天内申请退款。请联系客服团队协助处理。", icon: <ArrowsRotateLeft />, title: "如何申请退款？", }, ]; export function RenderFunction() { 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="me-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> ); } ``` ### 常见问题布局 ```tsx import {ChevronDown} from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; export function FAQ() { const categories = [ { items: [ { content: "浏览我们的商品，将商品加入购物车并前往结账。完成购买需要提供收货与支付信息。", title: "如何下单？", }, { content: "可以，在订单发货前你可以修改或取消。订单一旦进入处理流程，将无法再更改。", title: "可以修改或取消订单吗？", }, ], title: "常规", }, { items: [ { content: "你可以直接在官网购买许可证，选择适合的许可证类型后前往结账即可。", title: "如何购买许可证？", }, { content: "标准版适用于个人或小项目；专业版包含商业使用授权与优先支持。", title: "标准版与专业版有什么区别？", }, ], title: "许可", }, { items: [ { content: "可通过网站上的联系表单联系支持团队，或直接发送邮件至 support@example.com。", title: "如何获取支持？", }, ], title: "支持", }, ]; return ( <div className="flex w-full flex-col gap-6"> <div className="flex flex-col gap-1"> <h2 className="text-2xl font-bold">常见问题</h2> <p className="mb-4 text-lg font-medium text-muted"> 关于许可与使用，你需要了解的内容都在这里。 </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> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {ChevronDown} from "@gravity-ui/icons"; import {Accordion} from "@heroui/react"; const items = [ { content: "通过实时通知及时了解账户动态。", iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/bell-small.png", subtitle: "接收账户活动更新", title: "开启通知", }, { content: "安装我们的官方浏览器扩展，获得更顺畅的浏览体验。", iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/compass-small.png", subtitle: "将浏览器连接到你的账户", title: "安装浏览器扩展", }, { content: "创建你的第一件数字藏品，开启数字收藏之旅。", iconUrl: "https://heroui-assets.nyc3.cdn.digitaloceanspaces.com/docs/3dicons/mint-collective-small.png", subtitle: "创建你的第一件收藏品", title: "铸造收藏品", }, ]; 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="group/item first:**:data-[slot=accordion-trigger]:rounded-t-2xl last:[&:not(:has([data-slot=accordion-trigger][aria-expanded='true']))_[data-slot=accordion-trigger]]:rounded-b-2xl" > <Accordion.Heading> <Accordion.Trigger className="group flex items-center gap-2 transition-none hover:bg-surface"> {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> ); } ``` ### 全局 CSS 若要自定义 Accordion 组件类，可使用 `@layer components` 指令。 [了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Accordion 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/accordion.css)）： #### 基础类 \[!toc] * `.accordion` - Accordion 根容器 * `.accordion__body` - 正文容器 * `.accordion__heading` - 标题包裹层 * `.accordion__indicator` - 展开/收起指示图标 * `.accordion__item` - 单个 Accordion 项 * `.accordion__panel` - 可折叠面板容器 * `.accordion__trigger` - 可点击的触发按钮 #### 变体类 \[!toc] * `.accordion--outline` - 描边变体（边框与背景） #### 状态类 \[!toc] * `.accordion__trigger[aria-expanded="true"]` - 展开状态 * `.accordion__panel[aria-hidden="false"]` - 面板可见状态 ### 交互状态 该组件同时支持 CSS 伪类与 data 属性： * **悬停**：触发器上 `:hover` 或 `[data-hovered="true"]` * **聚焦**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]` * **禁用**：触发器上 `:disabled` 或 `[aria-disabled="true"]` * **展开**：触发器上 `[aria-expanded="true"]` ## API 参考 ### Accordion | Prop | 类型 | 默认值 | 描述 | | ------------------------ | ---------------------------------------------------------------------------- | ----------- | ---------------------- | | `allowsMultipleExpanded` | `boolean` | `false` | 是否允许多项同时展开 | | `defaultExpandedKeys` | `Iterable<Key>` | - | 初始展开的 key | | `expandedKeys` | `Iterable<Key>` | - | 受控的展开 key | | `onExpandedChange` | `(keys: Set<Key>) => void` | - | 展开 key 变化时调用的事件处理函数 | | `isDisabled` | `boolean` | `false` | 是否禁用整个 Accordion | | `variant` | `"default" \| "surface"` | `"default"` | Accordion 的视觉变体 | | `hideSeparator` | `boolean` | `false` | 是否隐藏 Accordion 项之间的分隔线 | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | - | Accordion 项 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Accordion.Item | Prop | 类型 | 默认值 | 描述 | | ------------------ | -------------------------------------------------------------------------------- | ------- | --------------------- | | `id` | `Key` | - | 该项的唯一标识 | | `isDisabled` | `boolean` | `false` | 是否禁用该项 | | `defaultExpanded` | `boolean` | `false` | 初始是否展开 | | `isExpanded` | `boolean` | - | 受控展开状态 | | `onExpandedChange` | `(isExpanded: boolean) => void` | - | 展开状态变化时调用的事件处理函数 | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | - | 项内容 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionItemRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Accordion.Trigger | Prop | 类型 | 默认值 | 描述 | | ------------ | -------------------------------------------------------------------------- | --- | --------------------- | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode \| RenderFunction` | - | 触发器内容或渲染函数 | | `onPress` | `() => void` | - | 额外的按下事件处理函数 | | `isDisabled` | `boolean` | - | 是否禁用触发器 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TriggerRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Accordion.Panel | Prop | 类型 | 默认值 | 描述 | | ----------- | --------------------------------------------------------------------------------- | --- | --------------------- | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | - | 面板内容 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, AccordionPanelRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Accordion.Indicator | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | --------- | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | - | 自定义指示图标 | ### Accordion.Body | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | --------- | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | - | 正文内容 | ## 相关组件 ## Related Components * **DisclosureGroup**: Group of collapsible panels * **Disclosure**: Single collapsible content section </page> <page url="/cn/docs/react/components/breadcrumbs"> # Breadcrumbs 面包屑 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/breadcrumbs **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(navigation)/breadcrumbs.mdx > 导航面包屑，显示当前页面在层级结构中的位置 ## 用法 ```tsx import { Breadcrumbs } from '@heroui/react'; ``` ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export default function BreadcrumbsBasic() { return ( <Breadcrumbs> <Breadcrumbs.Item href="#">首页</Breadcrumbs.Item> <Breadcrumbs.Item href="#">产品</Breadcrumbs.Item> <Breadcrumbs.Item href="#">电子产品</Breadcrumbs.Item> <Breadcrumbs.Item>笔记本电脑</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ## 组件结构 ```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> ) ``` ## 示例 ### 导航层级 ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export default function BreadcrumbsLevel2() { return ( <Breadcrumbs> <Breadcrumbs.Item href="#">首页</Breadcrumbs.Item> <Breadcrumbs.Item>当前页面</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export default function BreadcrumbsLevel3() { return ( <Breadcrumbs> <Breadcrumbs.Item href="#">首页</Breadcrumbs.Item> <Breadcrumbs.Item href="#">分类</Breadcrumbs.Item> <Breadcrumbs.Item>当前页面</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ### 禁用状态 ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export default function BreadcrumbsDisabled() { return ( <Breadcrumbs isDisabled> <Breadcrumbs.Item href="#">首页</Breadcrumbs.Item> <Breadcrumbs.Item href="#">产品</Breadcrumbs.Item> <Breadcrumbs.Item href="#">电子产品</Breadcrumbs.Item> <Breadcrumbs.Item>笔记本电脑</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ### 自定义分隔符 ```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="#">首页</Breadcrumbs.Item> <Breadcrumbs.Item href="#">产品</Breadcrumbs.Item> <Breadcrumbs.Item href="#">电子产品</Breadcrumbs.Item> <Breadcrumbs.Item>笔记本电脑</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ### 渲染函数 ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export function RenderFunction() { return ( <Breadcrumbs render={(props) => <ol {...props} data-custom="foo" />}> <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}> 首页 </Breadcrumbs.Item> <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}> 产品 </Breadcrumbs.Item> <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}> 电子产品 </Breadcrumbs.Item> <Breadcrumbs.Item render={(props) => <li {...(props as any)} data-custom="bar" />}> 笔记本电脑 </Breadcrumbs.Item> </Breadcrumbs> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {Breadcrumbs} from "@heroui/react"; export function CustomStyles() { return ( <Breadcrumbs className="rounded-lg bg-default-soft px-3 py-2"> <Breadcrumbs.Item className="text-muted hover:text-accent" href="#"> 首页 </Breadcrumbs.Item> <Breadcrumbs.Item className="text-muted hover:text-accent" href="#"> 产品 </Breadcrumbs.Item> <Breadcrumbs.Item className="font-medium text-foreground">笔记本电脑</Breadcrumbs.Item> </Breadcrumbs> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Breadcrumbs 组件类。 [了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Breadcrumbs 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/breadcrumbs.css)）： #### 基础类 \[!toc] * `.breadcrumbs` - 面包屑根容器 * `.breadcrumbs__item` - 单个面包屑项包装器 * `.breadcrumbs__link` - 面包屑链接元素 * `.breadcrumbs__separator` - 项之间的分隔符图标 #### 状态类 \[!toc] * `.breadcrumbs__link[data-current="true"]` - 当前页指示（非链接） ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Current**：链接上的 `[data-current="true"]`（表示当前页） * **Hover**：链接元素支持标准 hover 状态 * **Disabled**：`isDisabled` 属性禁用所有链接 ## API 参考 ### Breadcrumbs | Prop | 类型 | 默认值 | 描述 | | ------------ | ----------------------------------------------------------------- | ------------------ | -------------------------- | | `separator` | `ReactNode` | chevron-right icon | 面包屑项之间的自定义分隔符 | | `isDisabled` | `boolean` | `false` | 是否禁用所有面包屑链接 | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode` | - | 面包屑项 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, undefined>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Breadcrumbs.Item | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------------------------------------------------------- | --- | -------------------------- | | `href` | `string` | - | 链接 URL（当前页可省略） | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode \| RenderFunction` | - | 项内容或 render 函数 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, BreadcrumbRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ## 无障碍 Breadcrumbs 使用 React Aria Components 的 Breadcrumbs 原语，提供： * 导航地标的正确 ARIA 属性 * 通过 `aria-current="page"` 指示当前页 * 键盘导航支持 * 导航上下文的屏幕阅读器播报 最后一项（无 `href`）自动成为当前页指示。 ## 相关组件 ## Related Components * **Link**: Styled anchor links * **Separator**: Visual divider between content * **Tabs**: Organize content into tabbed views </page> <page url="/cn/docs/react/components/disclosure-group"> # DisclosureGroup 折叠面板组 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/disclosure-group **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(navigation)/disclosure-group.mdx > 管理多个 Disclosure 项展开状态的容器 ## 用法 ```tsx import { DisclosureGroup } from '@heroui/react'; ``` ```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="预览 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 /> 预览 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"> 使用手机相机扫描此二维码，即可预览 HeroUI Native 组件。 </p> <img alt="Expo Go 二维码" 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。</p> <Button className="mt-4" variant="primary"> <Icon className="[&_path]:fill-accent-foreground" icon="logos:expo-icon" /> 在 Expo Go 预览 </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> <Separator className="my-2" /> <Disclosure id="download"> <Disclosure.Heading aria-label="下载 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" /> 下载应用 </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"> 下载 HeroUI Native 应用，即可在设备上直接体验我们的移动端组件。 </p> <img alt="App Store 二维码" 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">支持 iOS 和 Android 设备。</p> <Button className="mt-4" variant="primary"> <Icon icon="tabler:brand-apple-filled" /> 在 App Store 下载 </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> </DisclosureGroup> </div> </div> ); } ``` ## 组件结构 ```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> ) ``` ## 示例 ### 受控组件 可使用 `expandedKeys` 与 `onExpandedChange` props 配合外部导航控件控制哪些 Disclosure 处于展开状态。 ```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="上一个折叠项" isDisabled={isPrevDisabled} size="sm" variant="secondary" onPress={onPrevious} > <ChevronUp className="size-4" /> </Button> <Button aria-label="下一个折叠项" isDisabled={isNextDisabled} size="sm" variant="secondary" onPress={onNext} > <ChevronDown className="size-4" /> </Button> </div> </div> <DisclosureGroup expandedKeys={expandedKeys} onExpandedChange={setExpandedKeys}> <Disclosure aria-label="预览 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 /> 预览 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"> 使用手机相机扫描此二维码，即可预览 HeroUI Native 组件。 </p> <img alt="Expo Go 二维码" 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。</p> <Button className="mt-4" variant="primary"> <Icon className="[&_path]:fill-accent-foreground" icon="logos:expo-icon" />在 Expo Go 预览 </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> <Separator className="my-2" /> <Disclosure id="download"> <Disclosure.Heading aria-label="下载 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" /> 下载 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"> 使用手机相机扫描此二维码，即可预览 HeroUI Native 组件。 </p> <img alt="Expo Go 二维码" 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。</p> <Button className="mt-4" variant="primary"> <Icon icon="tabler:brand-apple-filled" />在 App Store 下载 </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> </DisclosureGroup> </div> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {Button, Disclosure, DisclosureGroup, Separator} from "@heroui/react"; export function CustomStyles() { return ( <DisclosureGroup className="w-full max-w-sm rounded-xl bg-default-soft p-2"> <Disclosure id="billing"> <Disclosure.Heading> <Button className="w-full justify-between" slot="trigger" variant="ghost"> 账单 <Disclosure.Indicator className="text-muted" /> </Button> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="text-sm text-muted">发票将于每月 1 日开具。</Disclosure.Body> </Disclosure.Content> </Disclosure> <Separator className="my-1" /> <Disclosure id="support"> <Disclosure.Heading> <Button className="w-full justify-between" slot="trigger" variant="ghost"> 支持 <Disclosure.Indicator className="text-muted" /> </Button> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="text-sm text-muted"> 请通过 help@heroui.com 联系我们。通常会在一个工作日内回复。 </Disclosure.Body> </Disclosure.Content> </Disclosure> </DisclosureGroup> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 DisclosureGroup 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .disclosure-group { @apply w-full; /* Performance optimization */ contain: layout style; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 DisclosureGroup 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/disclosure-group.css)）： #### 基础类 \[!toc] * `.disclosure-group` - 基础容器样式，含布局 containment ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Disabled**：整个分组上 `:disabled` 或 `[aria-disabled="true"]` * **Expanded Management**：自动管理子 Disclosure 项上的 `[data-expanded]` 状态 ## API 参考 ### DisclosureGroup | Prop | 类型 | 默认值 | 描述 | | ------------------------ | ----------------------------- | ------- | ------------------- | | `expandedKeys` | `Set<Key>` | - | 当前展开项（受控） | | `defaultExpandedKeys` | `Iterable<Key>` | - | 初始展开项（非受控） | | `onExpandedChange` | `(keys: Set<Key>) => void` | - | 展开项变化时的回调 | | `allowsMultipleExpanded` | `boolean` | `false` | 是否允许多项同时展开 | | `isDisabled` | `boolean` | `false` | 是否禁用组内所有 Disclosure | | `children` | `ReactNode \| RenderFunction` | - | 要渲染的 Disclosure 项 | | `className` | `string` | - | 附加 CSS 类 | ### Render Props 使用 render prop 模式时，提供以下值： | Prop | 类型 | 描述 | | -------------- | ---------- | ---------- | | `expandedKeys` | `Set<Key>` | 当前展开项的 key | | `isDisabled` | `boolean` | 分组是否禁用 | ## 相关案例 ## 相关组件 ## Related Components * **Accordion**: Collapsible content sections * **Disclosure**: Single collapsible content section * **Button**: Allows a user to perform an action </page> <page url="/cn/docs/react/components/disclosure"> # Disclosure 折叠面板 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/disclosure **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(navigation)/disclosure.mdx > 可折叠区块，包含标题、触发按钮与内容面板 ## 用法 ```tsx import { Disclosure } from '@heroui/react'; ``` ```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 /> 预览 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"> 使用手机相机扫描此二维码，即可预览 HeroUI Native 组件。 </p> <img alt="Expo Go 二维码" 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。</p> <Button className="mt-4" variant="primary"> <Icon icon="tabler:brand-apple-filled" /> 在 App Store 下载 </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> </div> ); } ``` ## 组件结构 ```tsx import { Disclosure } from '@heroui/react'; export default () => ( <Disclosure> <Disclosure.Heading> <Disclosure.Trigger> <Disclosure.Indicator /> </Disclosure.Trigger> </Disclosure.Heading> <Disclosure.Content/> </Disclosure> ) ``` ## 示例 ### 渲染函数 ```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 RenderFunction() { 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 /> 预览 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"> 使用手机相机扫描此二维码，即可预览 HeroUI Native 组件。 </p> <img alt="Expo Go 二维码" 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。</p> <Button className="mt-4" variant="primary"> <Icon icon="tabler:brand-apple-filled" /> 在 App Store 下载 </Button> </Disclosure.Body> </Disclosure.Content> </Disclosure> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {ShoppingBag} from "@gravity-ui/icons"; import {Button, Disclosure} from "@heroui/react"; import {useState} from "react"; export function CustomStyles() { const [isExpanded, setIsExpanded] = useState(false); return ( <div className="w-full max-w-sm"> <Disclosure isExpanded={isExpanded} onExpandedChange={setIsExpanded}> <Disclosure.Heading> <Button className="w-full justify-between rounded-xl border border-border/70 bg-linear-to-b from-neutral-50/90 to-white px-4 py-3 font-medium text-foreground shadow-sm ring-1 ring-black/5 hover:bg-muted/30 dark:from-neutral-900/80 dark:to-neutral-900 dark:ring-white/10" slot="trigger" variant="ghost" > <span className="flex items-center gap-2"> <ShoppingBag className="size-4 text-muted" /> 配送详情 </span> <Disclosure.Indicator className="text-muted" /> </Button> </Disclosure.Heading> <Disclosure.Content> <Disclosure.Body className="mt-2 rounded-xl border border-border/70 bg-surface/50 p-4 text-sm leading-relaxed text-muted dark:bg-neutral-900/50"> 订单将在 2 个工作日内发货。标准配送需 3–5 天；结账时可选择加急配送。 </Disclosure.Body> </Disclosure.Content> </Disclosure> </div> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Disclosure 组件类。 [了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Disclosure 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/disclosure.css)）： #### 基础类 \[!toc] * `.disclosure` - 基础容器样式 * `.disclosure__heading` - 标题包裹层 * `.disclosure__trigger` - 触发按钮样式 * `.disclosure__indicator` - 箭头指示器样式 * `.disclosure__content` - 带动画的内容容器 ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Expanded**：指示器上 `[data-expanded="true"]` 用于旋转 * **Focus**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]` * **Disabled**：触发器上 `:disabled` 或 `[aria-disabled="true"]` * **Hidden**：内容上 `[aria-hidden="false"]` 控制可见性 ## API 参考 ### Disclosure | Prop | 类型 | 默认值 | 描述 | | ------------------ | ----------------------------------------------------------------------------- | ------- | -------------------------- | | `isExpanded` | `boolean` | `false` | 控制展开状态 | | `onExpandedChange` | `(isExpanded: boolean) => void` | - | 展开状态变化时的回调 | | `isDisabled` | `boolean` | `false` | 是否禁用 | | `children` | `ReactNode \| RenderFunction` | - | 要渲染的内容 | | `className` | `string` | - | 附加 CSS 类 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### DisclosureTrigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------- | --- | -------- | | `children` | `ReactNode \| RenderFunction` | - | 触发器内容 | | `className` | `string` | - | 附加 CSS 类 | ### DisclosureContent | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------------ | --- | -------------------------- | | `children` | `ReactNode` | - | 显示/隐藏的内容 | | `className` | `string` | - | 附加 CSS 类 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, DisclosureContentRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Render Props 使用 render prop 模式时，提供以下值： | Prop | 类型 | 描述 | | ------------ | --------- | ------ | | `isExpanded` | `boolean` | 当前展开状态 | | `isDisabled` | `boolean` | 是否禁用 | ## 相关案例 ## 相关组件 ## Related Components * **Accordion**: Collapsible content sections * **DisclosureGroup**: Group of collapsible panels * **Button**: Allows a user to perform an action </page> <page url="/cn/docs/react/components/link"> # Link 链接 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/link **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(navigation)/link.mdx > 用于导航的样式化锚点组件，内置图标支持。 ## 用法 ```tsx import { Link } from '@heroui/react'; ``` ```tsx import {Link} from "@heroui/react"; export function LinkBasic() { return ( <Link href="#"> 立即行动 <Link.Icon /> </Link> ); } ``` ## 组件结构 导入 Link 组件后，可通过点语法访问所有子部分。 ```tsx import { Link } from '@heroui/react'; export default () => ( <Link href="#"> Call to action <Link.Icon /> </Link> ); ``` ## 示例 ### 图标位置 ```tsx import {Link} from "@heroui/react"; export function LinkIconPlacement() { return ( <div className="flex flex-col gap-3"> <Link href="#"> 图标在末尾（默认） <Link.Icon /> </Link> <Link className="gap-1" href="#"> <Link.Icon /> 图标在开头 </Link> </div> ); } ``` ### 配合 Tailwind CSS 的文本装饰 Link 默认在悬浮时显示下划线。可使用 Tailwind CSS 的 text-decoration 工具类让下划线始终可见、完全移除，或自定义其颜色、样式、粗细与偏移。 ```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">默认悬浮下划线</p> <Link href="#"> 悬浮以查看下划线 <Link.Icon /> </Link> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">始终显示下划线</p> <Link className="underline" href="#"> 下划线始终可见 <Link.Icon /> </Link> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">无下划线</p> <Link className="no-underline" href="#"> 不带任何下划线的链接 <Link.Icon /> </Link> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">调整下划线偏移</p> <div className="flex flex-col gap-3"> <Link className="underline-offset-1" href="#"> 偏移 1（1px 间距） <Link.Icon /> </Link> <Link className="underline-offset-2" href="#"> 偏移 2（2px 间距） <Link.Icon /> </Link> <Link className="underline-offset-3" href="#"> 偏移 3（3px 间距） <Link.Icon /> </Link> <Link className="underline-offset-4" href="#"> 偏移 4（4px 间距） <Link.Icon /> </Link> </div> </div> </div> ); } ``` **文本装饰线：** * `underline` — 始终显示下划线 * `no-underline` — 移除下划线 * 默认 `Link` 样式 — 下划线在悬浮时显示 **文本装饰色：** * `decoration-accent`、`decoration-muted` 等 — 使用主题色设置下划线颜色 * `decoration-muted/50` — 使用透明度修饰符实现半透明下划线 **文本装饰样式：** * `decoration-solid` — 实线（默认） * `decoration-double` — 双线 * `decoration-dotted` — 点线 * `decoration-dashed` — 虚线 * `decoration-wavy` — 波浪线 **文本装饰粗细：** * `decoration-1`、`decoration-2`、`decoration-4` 等 — 控制下划线粗细 **下划线偏移：** * `underline-offset-1`、`underline-offset-2`、`underline-offset-4` 等 — 调整文本与下划线间距 更多说明见 Tailwind CSS 文档： * [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) 可用的 BEM 类： * 基础：`link` * 图标：`link__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="#"> 外部链接 <Link.Icon className="ms-1.5 size-3"> <ArrowUpRightFromSquare /> </Link.Icon> </Link> <Link className="gap-1" href="#"> 前往页面 <Link.Icon className="size-3"> <LinkIcon /> </Link.Icon> </Link> </div> ); } ``` ### 渲染函数 ```tsx "use client"; import {Link} from "@heroui/react"; export function RenderFunction() { return ( <Link href="#" render={(props) => <span {...props} data-custom="foo" />}> 立即行动 <Link.Icon /> </Link> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Link} from "@heroui/react"; export function CustomStyles() { return ( <Link className="font-medium text-neutral-700 underline decoration-neutral-300/80 underline-offset-4 transition-colors hover:text-neutral-900 dark:text-neutral-300 dark:decoration-neutral-600/80 dark:hover:text-neutral-100" href="#" > 立即行动 <Link.Icon /> </Link> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .link { @apply font-semibold no-underline hover:underline; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Link 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/link.css)）： #### 基础类 \[!toc] * `.link` — 链接基础样式 * `.link__icon` — 链接图标样式 ### 交互状态 组件同时支持 CSS 伪类与 data 属性，以获得更大灵活性： * **焦点**：`:focus-visible` 或 `[data-focus-visible="true"]` * **悬浮**：`:hover` 或 `[data-hovered="true"]` * **按下**：`:active` 或 `[data-pressed="true"]` * **禁用**：`:disabled` 或 `[aria-disabled="true"]` ## API 参考 ### Link | Prop | 类型 | 默认值 | 描述 | | ------------ | ----------------------------------------------------------------------- | --------- | --------------------- | | `href` | `string` | - | 锚点的目标 URL | | `target` | `string` | `"_self"` | 在何处打开链接文档 | | `rel` | `string` | - | 当前文档与链接文档的关系 | | `download` | `boolean \| string` | - | 触发下载而非导航 | | `isDisabled` | `boolean` | `false` | 禁用指针与键盘交互 | | `className` | `string` | - | 与默认样式合并的自定义类 | | `children` | `React.ReactNode` | - | 渲染在链接内部的内容 | | `onPress` | `(e: PressEvent) => void` | - | 链接被激活时触发 | | `autoFocus` | `boolean` | - | 元素挂载时是否应获得焦点 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, LinkRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Link.Icon | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ------------------- | | `children` | `React.ReactNode` | - | 自定义图标元素；省略时使用内置箭头图标 | | `className` | `string` | - | 附加的 CSS 类 | ### 与路由库配合使用 使用变体函数为框架专用链接（例如 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> ); } ``` ### 直接应用类 由于 HeroUI 使用 [BEM](https://getbem.com/) 类，你可以将 Link 样式直接应用到任意链接元素： ```tsx import NextLink from 'next/link'; // 直接使用 Tailwind 工具类 export default function Demo() { return ( <NextLink href="/about" className="link underline-offset-2"> About Page </NextLink> ); } // 或使用原生 <a> export default function NativeLink() { return ( <a href="/about" className="link underline decoration-accent underline-offset-4"> About Page <Link.Icon className="link__icon" /> </a> ); } ``` ## 相关组件 ## Related Components * **Breadcrumbs**: Display the user's current location within a hierarchy </page> <page url="/cn/docs/react/components/pagination"> # Pagination 分页 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/pagination **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(navigation)/pagination.mdx > 分页导航：可组合的页码链接、上一页/下一页按钮与省略号指示器。 ## 用法 ```tsx import { Pagination } from '@heroui/react'; ``` ```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>上一页</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>下一页</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ## 组件结构 导入 Pagination 组件后，可通过点号访问各个子部分。 ```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> ); ``` ## 示例 ### 尺寸 ```tsx "use client"; import {Pagination} from "@heroui/react"; import {useState} from "react"; const SIZE_LABELS = { lg: "大", md: "中", sm: "小", } as const; 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">{SIZE_LABELS[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>上一页</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>下一页</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> ); } ``` ### 禁用 ```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>上一页</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>下一页</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### 简化（上一页 / 下一页） ```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}–{endItem} 条，共 {totalItems} 张发票 </Pagination.Summary> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}> <Pagination.PreviousIcon /> <span>上一页</span> </Pagination.Previous> </Pagination.Item> <Pagination.Item> <Pagination.Next isDisabled={page === totalPages} onPress={() => setPage((p) => p + 1)}> <span>下一页</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### 受控组件 ```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> 显示第 {startItem}–{endItem} 条，共 {totalItems} 条结果 </Pagination.Summary> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}> <Pagination.PreviousIcon /> <span>上一页</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>下一页</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### 带省略号 ```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>上一页</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>下一页</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> </div> ); } ``` ### 带摘要 ```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> 显示第 {startItem}–{endItem} 条，共 {totalItems} 条结果 </Pagination.Summary> <Pagination.Content> <Pagination.Item> <Pagination.Previous isDisabled={page === 1} onPress={() => setPage((p) => p - 1)}> <Pagination.PreviousIcon /> <span>上一页</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>下一页</span> <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### 自定义图标 可通过向 `PreviousIcon` 与 `NextIcon` 传入自定义子元素来替换默认 chevron 图标。 ```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>返回</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>前进</span> <Pagination.NextIcon> <Icon icon="gravity-ui:arrow-right" /> </Pagination.NextIcon> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {Pagination} from "@heroui/react"; import {useState} from "react"; const linkClass = "text-muted hover:bg-surface hover:text-foreground"; const activeClass = "bg-accent text-accent-foreground hover:bg-accent-hover"; export function CustomStyles() { const [page, setPage] = useState(2); return ( <Pagination className="justify-center"> <Pagination.Content className="gap-1 rounded-xl bg-default p-1"> <Pagination.Item> <Pagination.Previous className={linkClass} isDisabled={page === 1} onPress={() => setPage((p) => p - 1)} > <Pagination.PreviousIcon /> </Pagination.Previous> </Pagination.Item> {[1, 2, 3].map((p) => ( <Pagination.Item key={p}> <Pagination.Link className={p === page ? activeClass : linkClass} isActive={p === page} onPress={() => setPage(p)} > {p} </Pagination.Link> </Pagination.Item> ))} <Pagination.Item> <Pagination.Next className={linkClass} isDisabled={page === 3} onPress={() => setPage((p) => p + 1)} > <Pagination.NextIcon /> </Pagination.Next> </Pagination.Item> </Pagination.Content> </Pagination> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Pagination 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/pagination.css)）： #### 基础与布局类 \[!toc] * `.pagination` - 根导航容器（flex 布局） * `.pagination__summary` - 左侧信息文本容器 * `.pagination__content` - 分页项容器 * `.pagination__item` - 单个分页项包裹层 * `.pagination__link` - 页码按钮（ghost 按钮样式） * `.pagination__link--nav` - 导航按钮修饰符（Previous/Next） * `.pagination__ellipsis` - 省略号指示器 #### 尺寸类 \[!toc] * `.pagination--sm` - 小尺寸变体 * `.pagination--md` - 中尺寸变体（默认） * `.pagination--lg` - 大尺寸变体 ### 交互状态 组件同时支持 CSS 伪类与 data 属性，便于灵活定制： * **Active page**：`[data-active="true"]` 或 `[aria-current="page"]` * **Hover**：`:hover` 或 `[data-hovered="true"]` * **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]` * **Disabled**：`:disabled` 或 `[aria-disabled="true"]` * **Pressed**：`:active` 或 `[data-pressed="true"]` ## API 参考 ### Pagination | Prop | 类型 | 默认值 | 描述 | | ----------- | ---------------------- | ------ | ----------------------- | | `size` | `"sm" \| "md" \| "lg"` | `"md"` | 分页控件的尺寸 | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | - | 分页部件（Summary、Content 等） | ### Pagination.Summary | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------------------ | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | - | 摘要内容（例如 "Showing 1-10 of 120"） | ### Pagination.Content | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | --------- | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | - | 分页项 | ### Pagination.Item | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ---------------------------------- | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | - | 项内容（Link、Previous、Next 或 Ellipsis） | ### Pagination.Link | Prop | 类型 | 默认值 | 描述 | | ------------ | ------------------------- | ------- | ----------------------- | | `isActive` | `boolean` | `false` | 是否为当前页 | | `isDisabled` | `boolean` | `false` | 是否禁用链接 | | `onPress` | `(e: PressEvent) => void` | - | 按下事件处理函数（来自 React Aria） | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | - | 页码内容 | ### Pagination.Previous / Pagination.Next | Prop | 类型 | 默认值 | 描述 | | ------------ | ------------------------- | ------- | --------------------------------- | | `isDisabled` | `boolean` | `false` | 是否禁用按钮 | | `onPress` | `(e: PressEvent) => void` | - | 按下事件处理函数（来自 React Aria） | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | - | 按钮内容（可与 PreviousIcon/NextIcon 组合） | ### Pagination.PreviousIcon / Pagination.NextIcon | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | ------------------- | --------------------- | | `className` | `string` | - | 额外的 CSS 类 | | `children` | `ReactNode` | Default chevron SVG | 用于替换默认 chevron 的自定义图标 | ### Pagination.Ellipsis | Prop | 类型 | 默认值 | 描述 | | ----------- | -------- | --- | --------- | | `className` | `string` | - | 额外的 CSS 类 | ## 说明 Pagination 按钮使用 `onPress` 而非 `onClick`。React Aria 的 `onPress` 处理函数会统一不同指针类型的按压行为，并内置无障碍改进。 ## 无障碍 Pagination 基于 [React Aria 的 Button](https://react-spectrum.adobe.com/react-aria/Button.html) 原语实现所有可交互元素，并提供： * 语义化 `<nav>` 元素，包含 `aria-label="pagination"` 与 `role="navigation"` * 通过在当前链接上使用 `aria-current="page"` 标示活动页 * 通过 Tab 键在全部可交互元素间进行键盘导航 * 通过 React Aria 在鼠标、触摸与键盘交互之间统一处理按下事件 * 键盘导航时通过 `:focus-visible` 显示焦点环 * 省略号使用 `aria-hidden="true"`，避免干扰屏幕阅读器 * 通过 `isDisabled` 向辅助技术正确传达禁用状态 > **说明：** Pagination 按钮请使用 `onPress` 而不是 `onClick`。React Aria 的 `onPress` 会规范化不同指针类型的按下行为，并提供开箱即用的无障碍改进。 ## 相关组件 ## Related Components * **Button**: Allows a user to perform an action * **Link**: Styled anchor links </page> <page url="/cn/docs/react/components/tabs"> # Tabs 标签页 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/tabs **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(navigation)/tabs.mdx > Tabs 将内容组织为多个区块，并允许用户在它们之间导航。 ## 用法 ```tsx import { Tabs } from '@heroui/react'; ``` ## 组件结构 导入 Tabs 组件后，可通过点语法访问所有子部分。 ```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> ) ``` ## 示例 ### 垂直布局 ### 溢出 当标签列表超出可用空间时，`Tabs.ListContainer` 会自动渲染滚动箭头与渐隐边缘，使用户可以导航到被隐藏的标签。水平与垂直方向均支持此行为。 ### 禁用 Tab ### 带分隔线 在每个 `<Tabs.Tab>` 内（第一项除外）添加 `<Tabs.Separator />`，用于在标签之间显示分隔线。 ### 次要类型 ### 次要类型（垂直） ### 对齐方式 标签内容默认居中。使用 `align` 可将其对齐到 `start` 或 `end`，这在垂直的侧边栏式导航中尤其有用。单个标签仍可通过 `Tabs.Tab` 上的 `className` 覆盖。 ### 渲染函数 ```tsx "use client"; import {Tabs} from "@heroui/react"; import Link from "next/link"; export function RenderFunction() { return ( <Tabs className="w-full max-w-md" render={(props) => <div {...props} data-custom="foo" />}> <Tabs.ListContainer> <Tabs.List aria-label="选项"> <Tabs.Tab href="/docs/react/getting-started" id="getting-started" render={(domProps: any) => <Link {...domProps} />} > 快速入门 <Tabs.Indicator /> </Tabs.Tab> <Tabs.Tab href="/docs/react/components" id="components" render={(domProps: any) => <Link {...domProps} />} > 组件 <Tabs.Indicator /> </Tabs.Tab> <Tabs.Tab href="/docs/react/releases" id="releases" render={(domProps: any) => <Link {...domProps} />} > 发布说明 <Tabs.Indicator /> </Tabs.Tab> </Tabs.List> </Tabs.ListContainer> <Tabs.Panel className="pt-4" id="overview"> <p>查看项目概览与近期活动。</p> </Tabs.Panel> <Tabs.Panel className="pt-4" id="analytics"> <p>跟踪指标并分析性能数据。</p> </Tabs.Panel> <Tabs.Panel className="pt-4" id="reports"> <p>生成并下载详细报告。</p> </Tabs.Panel> </Tabs> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Tabs} from "@heroui/react"; const listClassName = [ "rounded-xl border border-accent/10 bg-accent-soft/30 p-1", "**:data-[slot=tabs-tab]:rounded-lg", "**:data-[slot=tabs-tab]:bg-transparent", "**:data-[slot=tabs-tab]:text-muted", "**:data-[slot=tabs-tab]:opacity-100", "**:data-[slot=tabs-tab]:transition-colors", "**:data-[slot=tabs-tab]:data-[hovered=true]:not-data-[selected=true]:bg-accent-soft", "**:data-[slot=tabs-tab]:data-[hovered=true]:not-data-[selected=true]:text-accent-soft-foreground", "**:data-[slot=tabs-tab]:data-[pressed=true]:not-data-[selected=true]:bg-accent-soft-hover", "**:data-[slot=tabs-tab]:data-[focus-visible=true]:ring-2", "**:data-[slot=tabs-tab]:data-[focus-visible=true]:ring-accent/15", "**:data-[slot=tabs-tab]:data-[selected=true]:font-medium", "**:data-[slot=tabs-tab]:data-[selected=true]:text-accent-foreground", "**:data-[slot=tabs-tab]:shadow-none", "**:data-[slot=tabs-indicator]:rounded-lg", "**:data-[slot=tabs-indicator]:bg-accent", "**:data-[slot=tabs-indicator]:shadow-none", ].join(" "); export function CustomStyles() { return ( <Tabs className="w-full max-w-sm"> <Tabs.ListContainer className="rounded-none bg-transparent"> <Tabs.List aria-label="计费周期" className={listClassName}> <Tabs.Tab id="monthly"> 按月 <Tabs.Indicator /> </Tabs.Tab> <Tabs.Tab id="yearly"> 按年 <Tabs.Indicator /> </Tabs.Tab> </Tabs.List> </Tabs.ListContainer> <Tabs.Panel className="pt-3 text-sm text-muted" id="monthly"> 按月计费，随时可取消。 </Tabs.Panel> <Tabs.Panel className="pt-3 text-sm text-muted" id="yearly"> 年付可节省 20%。 </Tabs.Panel> </Tabs> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .tabs__list { @apply rounded-xl border border-border bg-surface p-1; } .tabs__tab { @apply rounded-lg font-medium; } .tabs__indicator { @apply rounded-lg bg-foreground shadow-sm; } .tabs--secondary > .tabs__list-container > .tabs__list { @apply border-b border-border bg-transparent p-0; } .tabs--secondary > .tabs__list-container .tabs__indicator { @apply rounded-none bg-accent; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Tabs 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tabs.css)）： #### 基础类 \[!toc] * `.tabs` - Tabs 根容器 * `.tabs__list-container` - 标签列表容器外层包裹 * `.tabs__list-container__scroller` - 标签列表的可滚动容器（处理溢出与渐隐边缘） * `.tabs__list-container__scroll-prev` - 向前（左 / 上）滚动的箭头按钮 * `.tabs__list-container__scroll-next` - 向后（右 / 下）滚动的箭头按钮 * `.tabs__list` - 标签列表容器 * `.tabs__tab` - 单个标签按钮 * `.tabs__separator` - 标签之间的分隔线 * `.tabs__panel` - 标签面板内容 * `.tabs__indicator` - 标签指示器 #### 方向属性 \[!toc] * `.tabs[data-orientation="horizontal"]` - 水平标签布局（默认） * `.tabs[data-orientation="vertical"]` - 垂直标签布局 #### 变体类 \[!toc] * `.tabs--secondary` - 次要类型变体，使用下划线指示器 #### 对齐类 \[!toc] * `.tabs--align-start` - 标签内容对齐到起始侧 * `.tabs--align-end` - 标签内容对齐到结束侧 ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Selected**：`[aria-selected="true"]` * **Hover**：`:hover` 或 `[data-hovered="true"]` * **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]` * **Disabled**：`[aria-disabled="true"]` ## API 参考 ### Tabs | Prop | 类型 | 默认值 | 描述 | | -------------------- | ----------------------------------------------------------------------- | -------------- | ----------------------------------------- | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉样式变体。Primary 使用填充指示器，Secondary 使用下划线指示器 | | `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | 标签布局方向 | | `align` | `"start" \| "center" \| "end"` | `"center"` | 每个标签内部内容的对齐方式 | | `selectedKey` | `string` | - | 受控选中标签的 key | | `defaultSelectedKey` | `string` | - | 默认选中标签的 key | | `onSelectionChange` | `(key: Key) => void` | - | 选中变化回调 | | `className` | `string` | - | 附加 CSS 类 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabsRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Tabs.List | Prop | 类型 | 默认值 | 描述 | | ------------ | -------------------------------------------------------------------------- | --- | -------------------------- | | `aria-label` | `string` | - | 标签列表的无障碍标签 | | `className` | `string` | - | 附加 CSS 类 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabListRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Tabs.Tab | Prop | 类型 | 默认值 | 描述 | | ------------ | ---------------------------------------------------------------------- | ------- | -------------------------- | | `id` | `string` | - | 标签唯一标识 | | `isDisabled` | `boolean` | `false` | 是否禁用该标签 | | `className` | `string` | - | 附加 CSS 类 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### Tabs.Separator | Prop | 类型 | 默认值 | 描述 | | ----------- | -------- | --- | -------- | | `className` | `string` | - | 附加 CSS 类 | ### Tabs.Panel | Prop | 类型 | 默认值 | 描述 | | ----------- | --------------------------------------------------------------------------- | --- | -------------------------- | | `id` | `string` | - | 与对应 Tab id 匹配的面板标识 | | `className` | `string` | - | 附加 CSS 类 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TabPanelRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ## 相关案例 ## 相关组件 ## Related Components * **Breadcrumbs**: Display the user's current location within a hierarchy </page> <page url="/cn/docs/react/components/alert-dialog"> # AlertDialog 警告对话框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/alert-dialog **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(overlays)/alert-dialog.mdx > 用于关键确认操作的模态对话框，需要用户关注并明确操作 ## 用法 ```tsx import { AlertDialog } from "@heroui/react"; ``` ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; export function Default() { return ( <AlertDialog> <Button variant="danger">删除项目</Button> <AlertDialog.Backdrop> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="danger" /> <AlertDialog.Heading>要永久删除项目吗？</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> 此操作将永久删除 <strong>我的精彩项目</strong> 及其全部数据，且无法撤销。 </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close" variant="danger"> 删除项目 </Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); } ``` ## 组件结构 ```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> ); ``` ## 示例 ### 状态类型 ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; export function Statuses() { const examples = [ { actions: { cancel: "保持登录", confirm: "退出登录", }, body: "退出后需要重新登录才能访问账户，未保存的更改将丢失。", classNames: "bg-accent-soft text-accent-soft-foreground", header: "要退出当前账户吗？", status: "accent", trigger: "退出登录", }, { actions: { cancel: "稍后再说", confirm: "标记完成", }, body: "将把该任务标记为完成并通知所有成员，任务会移入已完成列表。", classNames: "bg-success-soft text-success-soft-foreground", header: "要完成此任务吗？", status: "success", trigger: "完成任务", }, { actions: { cancel: "继续编辑", confirm: "放弃更改", }, body: "你有未保存的更改，放弃后将永久丢失。确定要放弃吗？", classNames: "bg-warning-soft text-warning-soft-foreground", header: "要放弃未保存的更改吗？", status: "warning", trigger: "放弃更改", }, { actions: { cancel: "取消", confirm: "删除账户", }, body: "将永久删除你的账户并从服务器移除全部数据，此操作不可恢复。", classNames: "bg-danger-soft text-danger-soft-foreground", header: "要删除账户吗？", status: "danger", trigger: "删除账户", }, ] 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> ); } ``` ### 弹出位置 ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; const PLACEMENT_LABELS = { auto: "自动", bottom: "底部", center: "居中", top: "顶部", } as const; 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_LABELS[placement]}</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" ? "自动定位" : `${PLACEMENT_LABELS[placement]}位置`} </AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> {placement === "auto" ? "在移动端默认靠近底部，在桌面端居中，以获得更合适的阅读与操作体验。" : `对话框将锚定在视口的「${PLACEMENT_LABELS[placement]}」区域。重要确认通常使用居中 placement 以吸引最多注意。`} </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close">确认</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ))} </div> ); } ``` ### 尺寸 ```tsx "use client"; import {Rocket} from "@gravity-ui/icons"; import {AlertDialog, Button} from "@heroui/react"; const SIZE_LABELS = { cover: "通栏", lg: "大", md: "中", sm: "小", xs: "超小", } as const; 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_LABELS[size]}</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_LABELS[size]}</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> {size === "cover" ? ( <> 此警告框使用 <code>cover</code> 尺寸：在移动端与桌面端保留边距（移动端约 16px、桌面端约 40px）铺满可视区域，仍保持圆角与标准内边距，适合需要最大宽度又保留对话框气质的关键确认。 </> ) : ( <> 此警告框使用 <code>{size}</code>{" "} 尺寸。在移动端各尺寸都会接近全宽以便阅读；在桌面端则对应不同的最大宽度，以适配不同信息量。 </> )} </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close">确认</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ))} </div> ); } ``` ### 受控模式 ```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">配合 React.useState()</h3> <p className="text-sm leading-relaxed text-pretty text-muted"> 使用 React 的 <code className="text-foreground">useState</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"> 状态：{" "} <span className="font-mono font-medium text-foreground"> {isOpen ? "打开" : "关闭"} </span> </p> </div> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}> 打开对话框 </Button> <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}> 切换 </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>由 useState() 控制</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> 该警告对话框由 React 的 <code>useState</code> 控制。将 <code>isOpen</code> 与{" "} <code>onOpenChange</code> 传入即可在外部管理状态。 </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close">确认</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">配合 useOverlayState()</h3> <p className="text-sm leading-relaxed text-pretty text-muted"> 使用 <code className="text-foreground">useOverlayState</code> 获得更简洁的 API，内置{" "} <code>open()</code>、<code>close()</code>、<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"> 状态：{" "} <span className="font-mono font-medium text-foreground"> {state.isOpen ? "打开" : "关闭"} </span> </p> </div> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={state.open}> 打开对话框 </Button> <Button size="sm" variant="tertiary" onPress={state.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>由 useOverlayState() 控制</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> <code>useOverlayState</code> 为常见操作提供专用方法，无需手写回调，直接使用{" "} <code>state.open()</code>、<code>state.close()</code> 或{" "} <code>state.toggle()</code> 即可。 </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close">确认</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </div> </div> ); } ``` ### 自定义图标 ```tsx "use client"; import {LockOpen} from "@gravity-ui/icons"; import {AlertDialog, Button} from "@heroui/react"; export function CustomIcon() { return ( <AlertDialog> <Button variant="secondary">重置密码</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>要重置密码吗？</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p>我们会向你的邮箱发送重置链接。你需要设置新密码以恢复账户访问。</p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close">发送重置链接</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); } ``` ### 自定义触发器 ```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">删除条目</p> <p className="text-xs text-muted">永久移除此条目</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>要删除此条目吗？</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> 使用 <code>AlertDialog.Trigger</code>{" "} 可在标准按钮之外自定义触发区域。此示例展示带图标与说明文字的卡片式触发器。 </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close" variant="danger"> 删除条目 </Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); } ``` ### 遮罩变体 ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; const VARIANT_LABELS = { blur: "模糊", opaque: "不透明", transparent: "透明", } as const; 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_LABELS[variant]}</Button> <AlertDialog.Backdrop variant={variant}> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.CloseTrigger /> <AlertDialog.Header> <AlertDialog.Icon status="accent" /> <AlertDialog.Heading>背景：{VARIANT_LABELS[variant]}</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> {variant === "opaque" ? "不透明的深色背景会完全遮挡背后内容，让用户把注意力集中在对话框上。" : variant === "blur" ? "模糊背景会柔和地虚化背后内容，同时保留一定的环境上下文。" : "透明背景会完整保留背后内容，适合重要性较低的确认场景。"} </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close">确认</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ))} </div> ); } ``` ### 自定义遮罩 ```tsx "use client"; import {TriangleExclamation} from "@gravity-ui/icons"; import {AlertDialog, Button} from "@heroui/react"; export function CustomBackdrop() { return ( <AlertDialog> <Button variant="danger">删除账户</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>要永久删除账户吗？</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> 此操作无法撤销。你的数据、设置与内容将从服务器永久清除。醒目的红色背景用于强调该决定的严重性与不可逆性。 </p> </AlertDialog.Body> <AlertDialog.Footer className="flex-col-reverse"> <Button className="w-full" slot="close"> 保留账户 </Button> <Button className="w-full" slot="close" variant="danger"> 永久删除 </Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); } ``` ### 关闭行为 ```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"> 控制是否允许通过点击遮罩关闭对话框。警告框通常需要明确操作，因此默认为 <code>false</code> 。对重要性较低的确认，可设为 <code>true</code>。 </p> <AlertDialog> <Button variant="secondary">打开警告对话框</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">点击遮罩不会关闭此对话框</p> </AlertDialog.Header> <AlertDialog.Body> <p>尝试点击遮罩区域——对话框不会关闭，必须通过底部操作按钮关闭。</p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close">确认</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"> 控制是否允许通过 ESC 关闭。警告框通常需要明确操作，因此默认为 <code>true</code>（禁用 ESC）。设为 <code>false</code> 时将允许 ESC 关闭。 </p> <AlertDialog> <Button variant="secondary">打开警告对话框</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 关闭</p> </AlertDialog.Header> <AlertDialog.Body> <p>按下 ESC 不会有任何反应，必须通过操作按钮关闭此对话框。</p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close">确认</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> </div> </div> ); } ``` ### 关闭方式 ```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"> 使用 <code className="text-sm">slot="close"</code> </h3> <p className="text-sm text-muted"> 最简单的关闭方式：在对话框内的任意 <code>Button</code> 上添加{" "} <code>slot="close"</code>，点击后会自动关闭对话框。 </p> <AlertDialog> <Button variant="secondary">打开对话框</Button> <AlertDialog.Backdrop> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> <AlertDialog.Header> <AlertDialog.Icon status="accent" /> <AlertDialog.Heading> 使用 <code className="text-sm">slot="close"</code> </AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> 点击下方任一按钮——它们都带有 <code>slot="close"</code> ，点击后会自动关闭对话框。 </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close">确认</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> </div> <div className="flex flex-col gap-2"> <h3 className="text-lg font-semibold">使用 Dialog 的 render props</h3> <p className="text-sm text-muted"> 通过 Dialog 的 render props 获取 <code>close</code>{" "} 方法，从而完全控制关闭时机与方式，便于在关闭前加入校验等自定义逻辑。 </p> <AlertDialog> <Button variant="secondary">打开对话框</Button> <AlertDialog.Backdrop> <AlertDialog.Container> <AlertDialog.Dialog className="sm:max-w-[400px]"> {(renderProps) => ( <> <AlertDialog.Header> <AlertDialog.Icon status="success" /> <AlertDialog.Heading>使用 Dialog render props</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p> 下方按钮使用 render props 提供的 <code>close</code> 方法。你可以在调用{" "} <code>renderProps.close()</code> 之前加入校验或其他逻辑。 </p> </AlertDialog.Body> <AlertDialog.Footer> <Button variant="tertiary" onPress={() => renderProps.close()}> 取消 </Button> <Button onPress={() => renderProps.close()}>确认</Button> </AlertDialog.Footer> </> )} </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> </div> </div> ); } ``` ### 自定义动画 ```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: "基于物理感的弹性缩放，模拟高阻尼弹簧：瞬态响应快、回落时间长，适合警告框与模态框。", icon: "gravity-ui:sparkles", name: "运动学缩放", }, { 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: "模拟在介质中运动并受流体阻力影响，避免机械式线性，更自然、更贴地，适合底部抽屉或 Toast。", icon: "gravity-ui:arrow-up-from-line", name: "流体滑入", }, ]; 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} 动画</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p className="mt-1">{description}</p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 关闭 </Button> <Button slot="close">再试一次</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); })} </div> ); } ``` ### 自定义 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"> 将警告对话框渲染到自定义容器，而不是 <code>document.body</code> </p> <p className="text-sm text-muted"> 为容器应用 <code className="rounded px-1 py-0.5 text-xs">transform: translateZ(0)</code>{" "} 可创建新的层叠上下文。 </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>打开警告对话框</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>自定义传送门</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body> <p className="text-sm text-muted"> 此段为示例占位文案，用于演示在自定义容器内渲染对话框时的滚动与排版效果。实际项目中请替换为真实说明内容。 </p> <p className="text-sm text-muted"> 通过将浮层挂载到局部容器，可以配合裁剪、缩放或卡片布局，避免遮挡整个页面，同时仍保持焦点管理与无障碍行为。 </p> <p className="text-sm text-muted"> 若容器存在 <code>transform</code> 或 <code>filter</code>{" "} 等属性，请注意浏览器会为其创建新的包含块，从而影响定位与层级关系。 </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 取消 </Button> <Button slot="close">确认</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> )} </div> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {AlertDialog, Button} from "@heroui/react"; export function CustomStyles() { return ( <AlertDialog> <Button variant="secondary">退出登录</Button> <AlertDialog.Backdrop className="bg-overlay/50 dark:bg-overlay/60" variant="blur"> <AlertDialog.Container> <AlertDialog.Dialog className="relative overflow-hidden border border-border/80 bg-surface shadow-2xl ring-1 ring-accent/10 sm:max-w-[400px] dark:border-border/90 dark:bg-surface dark:ring-accent/15"> <div aria-hidden="true" className="pointer-events-none absolute inset-x-0 top-0 h-24 bg-linear-to-b from-accent/6 to-transparent dark:from-accent/10" /> <div aria-hidden="true" className="pointer-events-none absolute inset-x-8 top-0 h-px bg-linear-to-r from-transparent via-accent/35 to-transparent dark:via-accent/45" /> <AlertDialog.Header className="relative"> <AlertDialog.Icon status="accent" /> <AlertDialog.Heading>确定要退出账户吗？</AlertDialog.Heading> </AlertDialog.Header> <AlertDialog.Body className="relative"> <p className="text-muted"> 您将在此设备上退出登录。除非已保存到云端，否则{" "} <strong className="text-foreground">Acme 工作区</strong> 中未保存的工作可能会丢失。 </p> </AlertDialog.Body> <AlertDialog.Footer> <Button slot="close" variant="tertiary"> 保持登录 </Button> <Button slot="close">退出登录</Button> </AlertDialog.Footer> </AlertDialog.Dialog> </AlertDialog.Container> </AlertDialog.Backdrop> </AlertDialog> ); } ``` ### 全局 CSS 若要自定义 AlertDialog 组件类，可使用 `@layer components` 指令。 [了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 AlertDialog 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/alert-dialog.css)）： #### 基础类 \[!toc] * `.alert-dialog__trigger` - 打开警告对话框的触发元素 * `.alert-dialog__backdrop` - 对话框背后的遮罩层 * `.alert-dialog__container` - 支持 placement 的定位包裹层 * `.alert-dialog__dialog` - 对话框内容容器 * `.alert-dialog__header` - 图标与标题的头部区域 * `.alert-dialog__heading` - 标题文本样式 * `.alert-dialog__body` - 主内容区域 * `.alert-dialog__footer` - 操作按钮的底部区域 * `.alert-dialog__icon` - 带状态色的图标容器 * `.alert-dialog__close-trigger` - 关闭按钮元素 #### 遮罩变体 \[!toc] * `.alert-dialog__backdrop--opaque` - 不透明彩色遮罩（默认） * `.alert-dialog__backdrop--blur` - 带玻璃效果的模糊遮罩 * `.alert-dialog__backdrop--transparent` - 透明遮罩（无覆盖层） #### 状态变体（图标）\[!toc] * `.alert-dialog__icon--default` - 默认灰色状态 * `.alert-dialog__icon--accent` - 强调蓝色状态 * `.alert-dialog__icon--success` - 成功绿色状态 * `.alert-dialog__icon--warning` - 警告橙色状态 * `.alert-dialog__icon--danger` - 危险红色状态 ### 交互状态 该组件支持以下交互状态： * **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]` — 应用于 trigger、dialog 和 close 按钮 * **Hover**：`:hover` 或 `[data-hovered="true"]` — 应用于 close 按钮悬停时 * **Active**：`:active` 或 `[data-pressed="true"]` — 应用于 close 按钮按下时 * **Entering**：`[data-entering]` — 对话框打开动画期间 * **Exiting**：`[data-exiting]` — 对话框关闭动画期间 * **Placement**：`[data-placement="*"]` — 根据对话框位置应用（auto、top、center、bottom） ## API 参考 ### AlertDialog | Prop | 类型 | 默认值 | 描述 | | ---------- | ----------- | --- | -------- | | `children` | `ReactNode` | - | 触发器与容器元素 | ### AlertDialog.Trigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | -------- | | `children` | `ReactNode` | - | 自定义触发器内容 | | `className` | `string` | - | CSS 类 | ### AlertDialog.Backdrop | Prop | 类型 | 默认值 | 描述 | | --------------------------- | ------------------------------------- | ---------- | ------------- | | `variant` | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | 遮罩覆盖层样式 | | `isDismissable` | `boolean` | `false` | 点击遮罩是否关闭 | | `isKeyboardDismissDisabled` | `boolean` | `true` | 是否禁用 ESC 键关闭 | | `isOpen` | `boolean` | - | 受控的打开状态 | | `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化处理函数 | | `className` | `string \| (values) => string` | - | 遮罩 CSS 类 | | `UNSTABLE_portalContainer` | `HTMLElement` | - | 自定义 portal 容器 | ### AlertDialog.Container | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------------------- | -------- | ----------------- | | `placement` | `"auto" \| "center" \| "top" \| "bottom"` | `"auto"` | 对话框在屏幕上的位置 | | `size` | `"xs" \| "sm" \| "md" \| "lg" \| "cover"` | `"md"` | Alert Dialog 尺寸变体 | | `className` | `string \| (values) => string` | - | 容器 CSS 类 | ### AlertDialog.Dialog | Prop | 类型 | 默认值 | 描述 | | ------------------ | ------------------------------------- | --------------- | --------- | | `children` | `ReactNode \| ({close}) => ReactNode` | - | 内容或渲染函数 | | `className` | `string` | - | CSS 类 | | `role` | `string` | `"alertdialog"` | ARIA role | | `aria-label` | `string` | - | 无障碍标签 | | `aria-labelledby` | `string` | - | 标签元素的 ID | | `aria-describedby` | `string` | - | 描述元素的 ID | ### AlertDialog.Header | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------------ | | `children` | `ReactNode` | - | 头部内容（通常为 Icon 和 Heading） | | `className` | `string` | - | CSS 类 | ### AlertDialog.Heading | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ----- | | `children` | `ReactNode` | - | 标题文本 | | `className` | `string` | - | CSS 类 | ### AlertDialog.Body | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ----- | | `children` | `ReactNode` | - | 正文内容 | | `className` | `string` | - | CSS 类 | ### AlertDialog.Footer | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------- | | `children` | `ReactNode` | - | 底部内容（通常为操作按钮） | | `className` | `string` | - | CSS 类 | ### AlertDialog.Icon | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------- | ---------- | ------- | | `children` | `ReactNode` | - | 自定义图标元素 | | `status` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"danger"` | 状态颜色变体 | | `className` | `string` | - | CSS 类 | ### AlertDialog.CloseTrigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------ | --- | ------- | | `children` | `ReactNode` | - | 自定义关闭按钮 | | `className` | `string \| (values) => string` | - | CSS 类 | ### 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 ``` ## 无障碍 实现 [WAI-ARIA AlertDialog 模式](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/)： * **焦点陷阱**：焦点锁定在警告对话框内 * **键盘**：`ESC` 关闭（启用时）、`Tab` 循环切换元素 * **屏幕阅读器**：使用 `role="alertdialog"` 的正确 ARIA 属性 * **滚动锁定**：打开时禁用 body 滚动 * **必需操作**：默认需要用户明确操作（不可通过遮罩/ESC 关闭） ## 相关组件 ## Related Components * **Button**: Allows a user to perform an action * **CloseButton**: Button for dismissing overlays </page> <page url="/cn/docs/react/components/drawer"> # Drawer 抽屉 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/drawer **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(overlays)/drawer.mdx > 用于补充内容与操作的滑出面板 ## 用法 ```tsx import { Drawer, Button } from "@heroui/react"; ``` ```tsx import {Button, Drawer} from "@heroui/react"; export function Basic() { return ( <Drawer> <Button variant="secondary">打开抽屉</Button> <Drawer.Backdrop> <Drawer.Content placement="right"> <Drawer.Dialog> <Drawer.Header> <Drawer.Heading>抽屉标题</Drawer.Heading> </Drawer.Header> <Drawer.Body> <p> 这是一个基于 React Aria Modal 组件构建的抽屉。它会从屏幕边缘滑入，并通过流畅的 CSS 过渡呈现动画效果。 </p> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> 取消 </Button> <Button slot="close">确认</Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ## 组件结构 ```tsx import { Drawer, Button } from "@heroui/react"; export default () => ( <Drawer> <Button>Open Drawer</Button> <Drawer.Backdrop> <Drawer.Content> <Drawer.Dialog> <Drawer.Handle /> {/* Optional: Drag handle */} <Drawer.CloseTrigger /> {/* Optional: Close button */} <Drawer.Header> <Drawer.Heading /> </Drawer.Header> <Drawer.Body /> <Drawer.Footer /> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); ``` ## 示例 ### 弹出位置 ```tsx import {Button, Drawer} from "@heroui/react"; const PLACEMENT_LABELS = { bottom: "底部", left: "左侧", right: "右侧", top: "顶部", } as const; export function Placements() { const placements = ["bottom", "top", "left", "right"] as const; return ( <div className="flex flex-wrap gap-4"> {placements.map((placement) => ( <Drawer key={placement}> <Button variant="secondary">{PLACEMENT_LABELS[placement]}</Button> <Drawer.Backdrop> <Drawer.Content placement={placement}> <Drawer.Dialog> <Drawer.CloseTrigger /> {placement === "bottom" && <Drawer.Handle />} <Drawer.Header> <Drawer.Heading>{PLACEMENT_LABELS[placement]}抽屉</Drawer.Heading> </Drawer.Header> <Drawer.Body> <p> 此抽屉从屏幕<strong>{PLACEMENT_LABELS[placement]}</strong>边缘滑入。 </p> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> 取消 </Button> <Button slot="close">完成</Button> </Drawer.Footer> {placement === "top" && <Drawer.Handle />} </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ))} </div> ); } ``` ### 不可关闭 在 `Drawer.Backdrop` 上设置 `isDismissable={false}` 可阻止点击外部或拖拽关闭。用户必须通过抽屉内的操作按钮交互。 ```tsx import {Button, Drawer} from "@heroui/react"; export function NonDismissable() { return ( <Drawer> <Button variant="secondary">重要操作</Button> <Drawer.Backdrop isDismissable={false}> <Drawer.Content> <Drawer.Dialog> <Drawer.Header> <Drawer.Heading>确认操作</Drawer.Heading> </Drawer.Header> <Drawer.Body> <p>此抽屉无法通过点击外部或拖拽关闭。你必须使用下方按钮之一来完成操作。</p> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> 取消 </Button> <Button slot="close">确认</Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ### 可滚动内容 `Drawer.Body` 通过原生滚动自动处理溢出。拖拽关闭在 body 区域被排除，以避免与滚动冲突。 ```tsx import {Button, Drawer} from "@heroui/react"; export function ScrollableContent() { return ( <Drawer> <Button variant="secondary">条款与条件</Button> <Drawer.Backdrop> <Drawer.Content> <Drawer.Dialog> <Drawer.Handle /> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading>条款与条件</Drawer.Heading> </Drawer.Header> <Drawer.Body> {Array.from({length: 20}).map((_, i) => ( <p key={i} className="mb-3"> 段落 {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> ))} </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> 拒绝 </Button> <Button slot="close">接受</Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ### 受控模式 ```tsx "use client"; import {Button, Drawer, 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">配合 React.useState()</h3> <p className="text-sm leading-relaxed text-pretty text-muted"> 使用 React 的 <code className="text-foreground">useState</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"> 状态：{" "} <span className="font-mono font-medium text-foreground"> {isOpen ? "打开" : "关闭"} </span> </p> </div> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}> 打开抽屉 </Button> <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}> 切换 </Button> </div> </div> <Drawer.Backdrop isOpen={isOpen} onOpenChange={setIsOpen}> <Drawer.Content placement="right"> <Drawer.Dialog> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading>由 useState() 控制</Drawer.Heading> </Drawer.Header> <Drawer.Body> <p> 该抽屉由 React 的 <code>useState</code> 控制。将 <code>isOpen</code> 与{" "} <code>onOpenChange</code> 传入即可在外部管理状态。 </p> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> 关闭 </Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </div> <div className="flex flex-col gap-3"> <h3 className="text-lg font-semibold text-foreground">配合 useOverlayState()</h3> <p className="text-sm leading-relaxed text-pretty text-muted"> 使用 <code className="text-foreground">useOverlayState</code> 获得更简洁的 API，内置{" "} <code>open()</code>、<code>close()</code>、<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"> 状态：{" "} <span className="font-mono font-medium text-foreground"> {state.isOpen ? "打开" : "关闭"} </span> </p> </div> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={state.open}> 打开抽屉 </Button> <Button size="sm" variant="tertiary" onPress={state.toggle}> 切换 </Button> </div> </div> <Drawer.Backdrop isOpen={state.isOpen} onOpenChange={state.setOpen}> <Drawer.Content placement="right"> <Drawer.Dialog> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading>由 useOverlayState() 控制</Drawer.Heading> </Drawer.Header> <Drawer.Body> <p> <code>useOverlayState</code> 为常见操作提供专用方法，无需手写回调，直接使用{" "} <code>state.open()</code>、<code>state.close()</code> 或{" "} <code>state.toggle()</code> 即可。 </p> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> 关闭 </Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </div> </div> ); } ``` ### 搭配表单 ```tsx import {Button, Drawer, Input, Label, TextField} from "@heroui/react"; export function WithForm() { return ( <Drawer> <Button variant="secondary">编辑资料</Button> <Drawer.Backdrop> <Drawer.Content placement="right"> <Drawer.Dialog> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading>编辑资料</Drawer.Heading> </Drawer.Header> <Drawer.Body> <form className="flex flex-col gap-4"> <TextField className="w-full" name="name" type="text"> <Label>姓名</Label> <Input placeholder="输入你的姓名" variant="secondary" /> </TextField> <TextField className="w-full" name="email" type="email"> <Label>邮箱</Label> <Input placeholder="输入你的邮箱" variant="secondary" /> </TextField> <TextField className="w-full" name="bio"> <Label>简介</Label> <Input placeholder="介绍一下你自己" variant="secondary" /> </TextField> </form> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> 取消 </Button> <Button slot="close">保存更改</Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ### 导航抽屉 ```tsx import type {ComponentType, SVGProps} from "react"; import {Bars, Bell, Envelope, Gear, House, Magnifier, Person} from "@gravity-ui/icons"; import {Button, Drawer} from "@heroui/react"; export function Navigation() { const navItems: {icon: ComponentType<SVGProps<SVGSVGElement>>; label: string}[] = [ {icon: House, label: "首页"}, {icon: Magnifier, label: "搜索"}, {icon: Bell, label: "通知"}, {icon: Envelope, label: "消息"}, {icon: Person, label: "个人资料"}, {icon: Gear, label: "设置"}, ]; return ( <Drawer> <Button variant="secondary"> <Bars /> 菜单 </Button> <Drawer.Backdrop> <Drawer.Content placement="left"> <Drawer.Dialog> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading>导航</Drawer.Heading> </Drawer.Header> <Drawer.Body> <nav className="flex flex-col gap-1"> {navItems.map((item) => ( <button key={item.label} className="flex items-center gap-3 rounded-xl px-3 py-2.5 text-sm text-foreground transition-colors hover:bg-default" type="button" > <item.icon className="size-5 text-muted" /> {item.label} </button> ))} </nav> </Drawer.Body> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ### 遮罩变体 ```tsx import {Button, Drawer} from "@heroui/react"; const VARIANT_LABELS = { blur: "模糊", opaque: "不透明", transparent: "透明", } as const; export function BackdropVariants() { const variants = ["opaque", "blur", "transparent"] as const; return ( <div className="flex flex-wrap gap-4"> {variants.map((variant) => ( <Drawer key={variant}> <Button variant="secondary">{VARIANT_LABELS[variant]}</Button> <Drawer.Backdrop variant={variant}> <Drawer.Content> <Drawer.Dialog> <Drawer.Handle /> <Drawer.CloseTrigger /> <Drawer.Header> <Drawer.Heading>背景：{VARIANT_LABELS[variant]}</Drawer.Heading> </Drawer.Header> <Drawer.Body> <p> 此抽屉使用 <code>{variant}</code> 背景变体。 </p> </Drawer.Body> <Drawer.Footer> <Button className="w-full" slot="close"> 关闭 </Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ))} </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Button, Drawer} from "@heroui/react"; export function CustomStyles() { return ( <Drawer> <Button variant="secondary">打开筛选</Button> <Drawer.Backdrop variant="blur"> <Drawer.Content placement="right"> <Drawer.Dialog className="border-l border-border/80 bg-surface"> <Drawer.Header> <Drawer.Heading className="text-foreground">筛选</Drawer.Heading> </Drawer.Header> <Drawer.Body> <p className="text-sm text-muted">按状态、负责人或日期缩小结果范围。</p> </Drawer.Body> <Drawer.Footer> <Button slot="close" variant="secondary"> 取消 </Button> <Button slot="close">应用</Button> </Drawer.Footer> </Drawer.Dialog> </Drawer.Content> </Drawer.Backdrop> </Drawer> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Drawer 组件类。 [了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .drawer__backdrop { @apply bg-gradient-to-br from-black/50 to-black/70; } .drawer__dialog { @apply rounded-2xl border border-white/10 shadow-2xl; } .drawer__header { @apply text-center; } .drawer__close-trigger { @apply rounded-full bg-white/10 hover:bg-white/20; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Drawer 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/drawer.css)）： #### 基础类 \[!toc] * `.drawer__trigger` - 打开抽屉的触发元素 * `.drawer__backdrop` - 抽屉背后的遮罩层 * `.drawer__content` - 抽屉面板的定位包裹层 * `.drawer__dialog` - 抽屉面板本身 * `.drawer__header` - 标题区域 * `.drawer__heading` - 主标题文本 * `.drawer__body` - 主可滚动内容区域 * `.drawer__footer` - 操作按钮区域 * `.drawer__handle` - 视觉拖拽手柄指示器 * `.drawer__close-trigger` - 关闭按钮元素 #### 遮罩变体 \[!toc] * `.drawer__backdrop--opaque` - 不透明彩色遮罩（默认） * `.drawer__backdrop--blur` - 模糊遮罩，玻璃效果 * `.drawer__backdrop--transparent` - 透明遮罩（无覆盖层） #### 位置变体 \[!toc] * `.drawer__content--bottom` - 从底部边缘滑入（默认） * `.drawer__content--top` - 从顶部边缘滑入 * `.drawer__content--left` - 从左侧边缘滑入 * `.drawer__content--right` - 从右侧边缘滑入 #### 对话框变体 \[!toc] * `.drawer__dialog--top` - 从顶部边缘滑入 * `.drawer__dialog--bottom` - 从底部边缘滑入 * `.drawer__dialog--left` - 从左侧边缘滑入 * `.drawer__dialog--right` - 从右侧边缘滑入 ### 交互状态 组件支持以下交互状态： * **Focus**：`:focus-visible` 或 `[data-focus-visible="true"]` - 应用于触发器与关闭按钮 * **Hover**：`:hover` 或 `[data-hovered="true"]` - 悬停时应用于关闭按钮 * **Active**：`:active` 或 `[data-pressed="true"]` - 按下时应用于触发器与关闭按钮 * **Entering**：`[data-entering]` - 抽屉打开动画期间 * **Exiting**：`[data-exiting]` - 抽屉关闭动画期间 * **Placement**：`[data-placement="*"]` - 根据抽屉位置（top、bottom、left、right）应用 ## API 参考 ### Drawer | Prop | 类型 | 默认值 | 描述 | | ---------- | ----------------------- | --- | ---------------- | | `children` | `ReactNode` | - | 触发器与 backdrop 元素 | | `state` | `UseOverlayStateReturn` | - | 受控 overlay 状态 | ### Drawer.Trigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | -------- | | `children` | `ReactNode` | - | 自定义触发器内容 | | `className` | `string` | - | CSS 类 | ### Drawer.Backdrop | Prop | 类型 | 默认值 | 描述 | | --------------------------- | ------------------------------------- | ---------- | -------------- | | `variant` | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | 遮罩覆盖层样式 | | `isDismissable` | `boolean` | `true` | 点击 backdrop 关闭 | | `isKeyboardDismissDisabled` | `boolean` | `false` | 禁用 ESC 关闭 | | `isOpen` | `boolean` | - | 受控打开状态 | | `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化处理函数 | | `className` | `string \| (values) => string` | - | Backdrop CSS 类 | ### Drawer.Content | Prop | 类型 | 默认值 | 描述 | | ----------- | ---------------------------------------- | ---------- | ------------- | | `placement` | `"top" \| "bottom" \| "left" \| "right"` | `"bottom"` | 抽屉滑入的边缘 | | `className` | `string \| (values) => string` | - | Content CSS 类 | ### Drawer.Dialog | Prop | 类型 | 默认值 | 描述 | | ----------------- | ----------- | ---------- | --------- | | `children` | `ReactNode` | - | Dialog 内容 | | `className` | `string` | - | CSS 类 | | `role` | `string` | `"dialog"` | ARIA role | | `aria-label` | `string` | - | 无障碍标签 | | `aria-labelledby` | `string` | - | 标签元素 ID | ### Drawer.Header | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | --------- | | `children` | `ReactNode` | - | Header 内容 | | `className` | `string` | - | CSS 类 | ### Drawer.Heading | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ----- | | `children` | `ReactNode` | - | 标题文本 | | `className` | `string` | - | CSS 类 | ### Drawer.Body | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------- | | `children` | `ReactNode` | - | Body 内容 | | `className` | `string` | - | CSS 类 | ### Drawer.Footer | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | --------- | | `children` | `ReactNode` | - | Footer 内容 | | `className` | `string` | - | CSS 类 | ### Drawer.Handle | Prop | 类型 | 默认值 | 描述 | | ----------- | -------- | --- | ----- | | `className` | `string` | - | CSS 类 | ### Drawer.CloseTrigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------ | --- | ------- | | `children` | `ReactNode` | - | 自定义关闭按钮 | | `className` | `string \| (values) => string` | - | CSS 类 | ### 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 drawer state.close(); // Close drawer state.toggle(); // Toggle state state.setOpen(); // Set state directly ``` ## 无障碍 实现 [WAI-ARIA Dialog 模式](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)： * **焦点陷阱**：打开时焦点锁定在抽屉内 * **键盘**：`ESC` 关闭（可关闭时），`Tab` 循环元素 * **屏幕阅读器**：通过 React Aria 提供正确的 ARIA 属性 * **滚动锁定**：打开时禁用 body 滚动 * **拖拽关闭**：在 handle、header 和 footer 区域支持指针拖拽手势 ## 相关组件 ## Related Components * **Modal**: Displays content in a modal overlay * **Button**: Allows a user to perform an action * **CloseButton**: Button for dismissing overlays </page> <page url="/cn/docs/react/components/modal"> # Modal 模态框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/modal **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(overlays)/modal.mdx > 用于聚焦用户交互与重要内容的对话框遮罩层。 ## 用法 ```tsx import { Modal } from "@heroui/react"; ``` ```tsx "use client"; import {Rocket} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function Default() { return ( <Modal> <Button variant="secondary">打开模态框</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>欢迎使用 HeroUI</Modal.Heading> </Modal.Header> <Modal.Body> <p>一套美观、快速、现代的 React UI 库，可轻松构建无障碍且高度可定制的 Web 应用。</p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="close"> 继续 </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); } ``` ## 组件结构 导入 Modal 组件后，可通过点语法访问所有子部分。 ```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> ); ``` ## 示例 ### 尺寸 ```tsx "use client"; import {Rocket} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; const SIZE_LABELS = { cover: "通栏", full: "全屏", lg: "大", md: "中", sm: "小", xs: "超小", } as const; 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_LABELS[size]}</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_LABELS[size]}</Modal.Heading> </Modal.Header> <Modal.Body> <p> {size === "cover" ? ( <> 此模态框使用 <code>cover</code> 尺寸：在移动端与桌面端保留边距（移动端约 16px、桌面端约 40px）铺满可视区域，仍保持圆角与标准内边距，适合需要最大宽度又保留模态框气质的内容展示。 </> ) : size === "full" ? ( <> 此模态框使用 <code>full</code>{" "} 尺寸，占满整个视口，无边距、圆角或阴影，提供真正的全屏体验，适合沉浸式内容或全页交互。 </> ) : ( <> 此模态框使用 <code>{size}</code>{" "} 尺寸。在移动端各尺寸都会接近全宽以便阅读；在桌面端则对应不同的最大宽度，以适配不同信息量。 </> )} </p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> 取消 </Button> <Button slot="close">确认</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ))} </div> ); } ``` ### 位置 ```tsx "use client"; import {Rocket} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; const PLACEMENT_LABELS = { auto: "自动", bottom: "底部", center: "居中", top: "顶部", } as const; 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_LABELS[placement]}</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 === "auto" ? "自动定位" : `${PLACEMENT_LABELS[placement]}位置`} </Modal.Heading> </Modal.Header> <Modal.Body> <p> {placement === "auto" ? "在移动端默认靠近底部，在桌面端居中，以获得更合适的阅读与操作体验。" : `模态框将锚定在视口的「${PLACEMENT_LABELS[placement]}」区域。可尝试不同 placement 查看屏幕上的定位效果。`} </p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="close"> 继续 </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ))} </div> ); } ``` ### 滚动行为 ```tsx "use client"; import {Button, 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.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 内部 </Radio.Content> </Radio> <Radio value="outside"> <Radio.Content> <Radio.Control> <Radio.Indicator /> </Radio.Control> 外部 </Radio.Content> </Radio> </RadioGroup> <Modal> <Button variant="secondary"> 打开模态框（{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 === "inside" ? "滚动：内部" : "滚动：外部"}</Modal.Heading> <p className="text-sm leading-5 text-muted"> 对比滚动行为——内部在模态框内滚动内容，外部允许页面滚动 </p> </Modal.Header> <Modal.Body> {Array.from({length: 30}).map((_, i) => ( <p key={i} className="mb-3"> 段落 {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"> 取消 </Button> <Button slot="close">确认</Button> </Modal.Footer> <Modal.CloseTrigger /> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> </div> ); } ``` ### 受控状态 ```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">配合 React.useState()</h3> <p className="text-sm leading-relaxed text-pretty text-muted"> 使用 React 的 <code className="text-foreground">useState</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"> 状态：{" "} <span className="font-mono font-medium text-foreground"> {isOpen ? "打开" : "关闭"} </span> </p> </div> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}> 打开模态框 </Button> <Button size="sm" variant="tertiary" onPress={() => setIsOpen(!isOpen)}> 切换 </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>由 useState() 控制</Modal.Heading> </Modal.Header> <Modal.Body> <p> 该模态框由 React 的 <code>useState</code> 控制。将 <code>isOpen</code> 与{" "} <code>onOpenChange</code> 传入即可在外部管理状态。 </p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> 取消 </Button> <Button slot="close">确认</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">配合 useOverlayState()</h3> <p className="text-sm leading-relaxed text-pretty text-muted"> 使用 <code className="text-foreground">useOverlayState</code> 获得更简洁的 API，内置{" "} <code>open()</code>、<code>close()</code>、<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"> 状态：{" "} <span className="font-mono font-medium text-foreground"> {state.isOpen ? "打开" : "关闭"} </span> </p> </div> <div className="flex gap-2"> <Button size="sm" variant="secondary" onPress={state.open}> 打开模态框 </Button> <Button size="sm" variant="tertiary" onPress={state.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>由 useOverlayState() 控制</Modal.Heading> </Modal.Header> <Modal.Body> <p> <code>useOverlayState</code> 为常见操作提供专用方法，无需手写回调，直接使用{" "} <code>state.open()</code>、<code>state.close()</code> 或{" "} <code>state.toggle()</code> 即可。 </p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> 取消 </Button> <Button slot="close">确认</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </div> </div> ); } ``` ### 搭配表单 ```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">打开联系表单</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>联系我们</Modal.Heading> <p className="mt-1.5 text-sm leading-5 text-muted"> 填写下方表单，我们会尽快回复。在移动端弹出键盘时，模态框会自动适配。 </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>姓名</Label> <Input placeholder="输入你的姓名" /> </TextField> <TextField className="w-full" name="email" type="email"> <Label>邮箱</Label> <Input placeholder="输入你的邮箱" /> </TextField> <TextField className="w-full" name="phone" type="tel"> <Label>电话</Label> <Input placeholder="输入你的电话号码" /> </TextField> <TextField className="w-full" name="company"> <Label>公司</Label> <Input placeholder="输入公司名称" /> </TextField> <TextField className="w-full" name="message"> <Label>留言</Label> <Input placeholder="输入留言内容" /> </TextField> </form> </Surface> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> 取消 </Button> <Button slot="close">发送消息</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); } ``` ### 自定义触发器 ```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">设置</p> <p className="text-xs text-muted">管理你的偏好设置</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>设置</Modal.Heading> </Modal.Header> <Modal.Body> <p> 使用 <code>Modal.Trigger</code>{" "} 可在标准按钮之外创建自定义触发器。此示例展示带图标与说明文字的卡片式触发器。 </p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> 取消 </Button> <Button slot="close">保存</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); } ``` ### 遮罩变体 ```tsx "use client"; import {Rocket} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; const VARIANT_LABELS = { blur: "模糊", opaque: "不透明", transparent: "透明", } as const; 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_LABELS[variant]}</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>背景：{VARIANT_LABELS[variant]}</Modal.Heading> </Modal.Header> <Modal.Body> <p> {variant === "opaque" ? "不透明背景会完全遮挡背后内容，让用户把注意力集中在模态框上。" : variant === "blur" ? "模糊背景会柔和地虚化背后内容，同时保留一定的环境上下文。" : "透明背景会完整保留背后内容，适合重要性较低的交互场景。"} </p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="close"> 继续 </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ))} </div> ); } ``` ### 自定义遮罩 ```tsx "use client"; import {Sparkles} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function CustomBackdrop() { return ( <Modal> <Button variant="secondary">自定义背景</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>高级背景</Modal.Heading> </Modal.Header> <Modal.Body> <p> 此背景采用从底部深色过渡到顶部完全透明的精致渐变，并配合柔和的模糊效果。渐变会在浅色与深色模式下自动调整强度，以获得最佳对比度。 </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"> 关闭 </Button> </Modal.Footer> <Modal.CloseTrigger /> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); } ``` ### 关闭行为 ```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"> 控制是否允许通过点击遮罩关闭模态框。默认为 <code>true</code>。设为 <code>false</code>{" "} 时需通过明确操作关闭。 </p> <Modal> <Button variant="secondary">打开模态框</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">点击遮罩不会关闭此模态框</p> </Modal.Header> <Modal.Body> <p>尝试点击遮罩区域——模态框不会关闭，必须使用关闭按钮或按 ESC 键关闭。</p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="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"> 控制是否允许通过 ESC 关闭模态框。设为 <code>true</code> 时将禁用 ESC，用户须通过明确操作关闭。 </p> <Modal> <Button variant="secondary">打开模态框</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 键</p> </Modal.Header> <Modal.Body> <p>按 ESC 无反应。必须使用关闭按钮或点击遮罩才能关闭此模态框。</p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="close"> 关闭 </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> </div> </div> ); } ``` ### 关闭方式 ```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">使用 slot="close"</h3> <p className="text-sm text-muted"> 关闭模态框的最简方式：为模态框内任意 Button 添加 <code>slot="close"</code> ，点击即可自动关闭。 </p> <Modal> <Button variant="secondary">打开模态框</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>使用 slot="close"</Modal.Heading> </Modal.Header> <Modal.Body> <p> 点击下方任一按钮——它们都带有 <code>slot="close"</code>，会自动关闭模态框。 </p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="secondary"> 取消 </Button> <Button slot="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">使用 Dialog 渲染属性</h3> <p className="text-sm text-muted"> 通过 Dialog 的渲染属性访问 <code>close</code>{" "} 方法，可完全控制关闭时机与方式，并在关闭前加入自定义逻辑。 </p> <Modal> <Button variant="secondary">打开模态框</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>使用 Dialog 渲染属性</Modal.Heading> </Modal.Header> <Modal.Body> <p> 下方按钮使用渲染属性中的 <code>close</code> 方法。可在调用{" "} <code>renderProps.close()</code> 前进行校验或其他逻辑。 </p> </Modal.Body> <Modal.Footer> <Button variant="secondary" onPress={() => renderProps.close()}> 取消 </Button> <Button onPress={() => renderProps.close()}>确认</Button> </Modal.Footer> </> )} </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> </div> </div> ); } ``` ### 自定义动画 ```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: "基于物理的弹性缩放，模拟高阻尼弹簧系统：快速瞬态响应与较长 settling 时间。适用于模态框与弹出层。", icon: "gravity-ui:sparkles", name: "运动缩放", }, { 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: "模拟流体阻力中的运动，摆脱机械式线性动画，呈现更自然、沉稳的质感。适用于底部抽屉或 Toast。", icon: "gravity-ui:arrow-up-from-line", name: "流体滑入", }, ]; 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} 动画</Modal.Heading> </Modal.Header> <Modal.Body> <p className="mt-1">{description}</p> </Modal.Body> <Modal.Footer> <Button slot="close" variant="tertiary"> 关闭 </Button> <Button slot="close">再试一次</Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); })} </div> ); } ``` ### 自定义 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"> 在自定义容器内渲染模态框，而非 <code>document.body</code> </p> <p className="text-sm text-muted"> 为容器应用 <code className="rounded px-1 py-0.5 text-xs">transform: translateZ(0)</code>{" "} 以创建新的层叠上下文。 </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>打开模态框</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>自定义 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"> 关闭 </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> )} </div> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import {CircleCheck} from "@gravity-ui/icons"; import {Button, Modal} from "@heroui/react"; export function CustomStyles() { return ( <Modal> <Button variant="secondary">打开</Button> <Modal.Backdrop className="bg-overlay/50 dark:bg-overlay/65" variant="blur"> <Modal.Container> <Modal.Dialog className="relative overflow-hidden border border-border/80 bg-surface/90 shadow-2xl ring-1 ring-black/5 backdrop-blur-xl sm:max-w-[340px] dark:border-border/90 dark:bg-surface/85 dark:ring-white/10"> <div aria-hidden="true" className="pointer-events-none absolute inset-x-0 top-0 h-20 bg-linear-to-b from-neutral-500/8 to-transparent dark:from-neutral-400/10" /> <div aria-hidden="true" className="pointer-events-none absolute inset-x-10 top-0 h-px bg-linear-to-r from-transparent via-neutral-400/40 to-transparent dark:via-neutral-500/35" /> <Modal.CloseTrigger /> <Modal.Header className="relative"> <Modal.Icon className="bg-neutral-100 text-neutral-700 dark:bg-neutral-800 dark:text-neutral-200"> <CircleCheck className="size-5" /> </Modal.Icon> <Modal.Heading>更改已保存</Modal.Heading> </Modal.Header> <Modal.Body className="relative"> <p className="text-sm text-muted">你的草稿已在各设备间同步。</p> </Modal.Body> <Modal.Footer> <Button className="w-full" slot="close"> 完成 </Button> </Modal.Footer> </Modal.Dialog> </Modal.Container> </Modal.Backdrop> </Modal> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Modal 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/modal.css)）： #### 基础类 \[!toc] * `.modal__trigger` — 打开 Modal 的触发元素 * `.modal__backdrop` — Modal 背后的遮罩层 * `.modal__container` — 支持 placement 的定位包裹层 * `.modal__dialog` — Modal 内容容器 * `.modal__header` — 标题与图标区域 * `.modal__body` — 主内容区域 * `.modal__footer` — 操作区域 * `.modal__close-trigger` — 关闭按钮元素 #### 遮罩变体 \[!toc] * `.modal__backdrop--opaque` — 不透明有色遮罩（默认） * `.modal__backdrop--blur` — 带玻璃效果的模糊遮罩 * `.modal__backdrop--transparent` — 透明遮罩（无叠加层） #### 滚动变体 \[!toc] * `.modal__container--scroll-outside` — 允许整个 Modal 滚动 * `.modal__dialog--scroll-inside` — 限制 Modal 高度，由 body 区域滚动 * `.modal__body--scroll-inside` — 仅 body 区域可滚动 * `.modal__body--scroll-outside` — 允许整页滚动 ### 交互状态 组件支持以下交互状态： * **焦点**：`:focus-visible` 或 `[data-focus-visible="true"]` — 应用于触发器、对话框与关闭按钮 * **悬停**：`:hover` 或 `[data-hovered="true"]` — 应用于关闭按钮悬停 * **按下**：`:active` 或 `[data-pressed="true"]` — 应用于关闭按钮按下 * **进入**：`[data-entering]` — Modal 打开动画期间 * **离开**：`[data-exiting]` — Modal 关闭动画期间 * **位置**：`[data-placement="*"]` — 基于 Modal 位置（auto、top、center、bottom） ## API 参考 ### Modal | Prop | 类型 | 默认值 | 描述 | | ---------- | ----------- | --- | -------- | | `children` | `ReactNode` | - | 触发器与容器元素 | ### Modal.Trigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------- | | `children` | `ReactNode` | - | 自定义触发内容 | | `className` | `string` | - | CSS 类 | ### Modal.Backdrop | Prop | 类型 | 默认值 | 描述 | | --------------------------- | ------------------------------------- | ---------- | ------------- | | `variant` | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | 遮罩叠加样式 | | `isDismissable` | `boolean` | `true` | 点击遮罩是否关闭 | | `isKeyboardDismissDisabled` | `boolean` | `false` | 是否禁用 ESC 关闭 | | `isOpen` | `boolean` | - | 受控打开状态 | | `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化处理函数 | | `className` | `string \| (values) => string` | - | 遮罩 CSS 类 | | `UNSTABLE_portalContainer` | `HTMLElement` | - | 自定义 portal 容器 | ### Modal.Container | Prop | 类型 | 默认值 | 描述 | | ----------- | --------------------------------------------------- | ---------- | ------------- | | `placement` | `"auto" \| "center" \| "top" \| "bottom"` | `"auto"` | Modal 在屏幕上的位置 | | `scroll` | `"inside" \| "outside"` | `"inside"` | 滚动行为 | | `size` | `"xs" \| "sm" \| "md" \| "lg" \| "cover" \| "full"` | `"md"` | Modal 尺寸变体 | | `className` | `string \| (values) => string` | - | 容器 CSS 类 | ### Modal.Dialog | Prop | 类型 | 默认值 | 描述 | | ------------------ | ------------------------------------- | ---------- | --------- | | `children` | `ReactNode \| ({close}) => ReactNode` | - | 内容或渲染函数 | | `className` | `string \| (values) => string` | - | CSS 类 | | `role` | `string` | `"dialog"` | ARIA role | | `aria-label` | `string` | - | 无障碍标签 | | `aria-labelledby` | `string` | - | 标签元素的 id | | `aria-describedby` | `string` | - | 描述元素的 id | ### Modal.Header | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ----- | | `children` | `ReactNode` | - | 头部内容 | | `className` | `string` | - | CSS 类 | ### Modal.Body | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ----- | | `children` | `ReactNode` | - | 正文内容 | | `className` | `string` | - | CSS 类 | ### Modal.Footer | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ----- | | `children` | `ReactNode` | - | 底部内容 | | `className` | `string` | - | CSS 类 | ### Modal.CloseTrigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------ | --- | ------- | | `children` | `ReactNode` | - | 自定义关闭按钮 | | `className` | `string \| (values) => string` | - | CSS 类 | ### useOverlayState Hook ```tsx import {useOverlayState} from "@heroui/react"; const state = useOverlayState({ defaultOpen: false, onOpenChange: (isOpen) => console.log(isOpen), }); state.isOpen; // 当前状态 state.open(); // 打开 modal state.close(); // 关闭 modal state.toggle(); // 切换状态 state.setOpen(); // 直接设置状态 ``` ## 无障碍 实现 [WAI-ARIA Dialog 模式](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)： * **焦点陷阱**：焦点锁定在 Modal 内 * **键盘**：`ESC` 关闭（启用时）、`Tab` 在元素间循环 * **屏幕阅读器**：正确的 ARIA 属性 * **滚动锁定**：打开时禁用 body 滚动 ## 相关组件 ## Related Components * **Button**: Allows a user to perform an action * **Tooltip**: Contextual information on hover or focus * **Select**: Dropdown select control </page> <page url="/cn/docs/react/components/popover"> # Popover 弹出框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/popover **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(overlays)/popover.mdx > 在由按钮或任意自定义元素触发后，于 portal 中展示丰富内容。 ## 用法 ```tsx import { Popover } from '@heroui/react'; ``` ```tsx import {Button, Popover} from "@heroui/react"; export function PopoverBasic() { return ( <div className="flex items-center gap-4"> <Popover> <Button>点击我</Button> <Popover.Content className="max-w-64"> <Popover.Dialog> <Popover.Heading>弹出层标题</Popover.Heading> <p className="mt-2 text-sm text-muted">这是弹出层内容，你可以在这里放置任何内容。</p> </Popover.Dialog> </Popover.Content> </Popover> </div> ); } ``` ## 组件结构 ```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> ) ``` ## 示例 ### 带箭头 ```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">带箭头</Button> <Popover.Content className="max-w-64"> <Popover.Dialog> <Popover.Arrow /> <Popover.Heading>带箭头的弹出层</Popover.Heading> <p className="mt-2 text-sm text-muted">箭头指向触发弹出层的元素。</p> </Popover.Dialog> </Popover.Content> </Popover> <Popover> <Button isIconOnly aria-label="更多选项" variant="tertiary"> <Ellipsis /> </Button> <Popover.Content className="max-w-64" offset={10}> <Popover.Dialog> <Popover.Arrow /> <Popover.Heading>带箭头的弹出层</Popover.Heading> <p className="mt-2 text-sm text-muted">箭头指向触发弹出层的元素。</p> </Popover.Dialog> </Popover.Content> </Popover> </div> ); } ``` ### 可交互内容 ```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="用户资料"> <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 ? "已关注" : "关注"} </Button> </div> </Popover.Heading> <p className="mt-3 text-sm text-muted">产品设计师兼创意总监，打造有意义的美好体验。</p> <div className="mt-3 flex gap-4"> <div> <span className="font-semibold">892</span> <span className="ms-1 text-sm text-muted">关注中</span> </div> <div> <span className="font-semibold">12.5K</span> <span className="ms-1 text-sm text-muted">粉丝</span> </div> </div> </Popover.Dialog> </Popover.Content> </Popover> </div> ); } ``` ### 位置 ```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">顶部位置</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">左侧位置</p> </Popover.Dialog> </Popover.Content> </Popover> <div className="flex items-center justify-center"> <span className="text-sm text-muted">点击按钮</span> </div> <Popover> <Button className="w-full" variant="tertiary"> Right </Button> <Popover.Content placement="right"> <Popover.Dialog> <Popover.Arrow /> <p className="text-sm">右侧位置</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">底部位置</p> </Popover.Dialog> </Popover.Content> </Popover> <div /> </div> ); } ``` ### 渲染函数 ```tsx "use client"; import {Button, Popover} from "@heroui/react"; export function RenderFunction() { return ( <div className="flex items-center gap-4"> <Popover> <Button>点击我</Button> <Popover.Content className="max-w-64" render={(props) => <div {...props} data-custom="foo" />} > <Popover.Dialog> <Popover.Heading>弹出层标题</Popover.Heading> <p className="mt-2 text-sm text-muted">这是弹出层内容，你可以在这里放置任何内容。</p> </Popover.Dialog> </Popover.Content> </Popover> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Button, Popover} from "@heroui/react"; export function CustomStyles() { return ( <Popover> <Button variant="secondary">详情</Button> <Popover.Content className="max-w-56 overflow-hidden rounded-xl border border-border/80 bg-surface/90 p-0 shadow-xl ring-1 ring-black/5 backdrop-blur-xl dark:border-border/90 dark:bg-surface/85 dark:ring-white/10"> <Popover.Dialog className="relative p-4"> <div aria-hidden="true" className="pointer-events-none absolute inset-x-0 top-0 h-12 bg-linear-to-b from-neutral-500/6 to-transparent dark:from-neutral-400/8" /> <Popover.Heading className="relative font-medium text-neutral-800 dark:text-neutral-100"> 键盘快捷键 </Popover.Heading> <dl className="relative mt-3 space-y-2 text-sm"> <div className="flex justify-between gap-4"> <dt className="text-muted">保存</dt> <dd className="font-mono text-neutral-700 dark:text-neutral-300">⌘ S</dd> </div> <div className="flex justify-between gap-4"> <dt className="text-muted">搜索</dt> <dd className="font-mono text-neutral-700 dark:text-neutral-300">⌘ K</dd> </div> </dl> </Popover.Dialog> </Popover.Content> </Popover> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Popover 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/popover.css)）： #### 基础类 \[!toc] * `.popover` - Popover 根容器样式 * `.popover__dialog` - 对话框内容包裹层 * `.popover__heading` - 标题文本样式 * `.popover__trigger` - 触发元素样式 ### 交互状态 组件支持以下动画相关状态： * **进入**：`[data-entering]` — Popover 出现过程中应用 * **离开**：`[data-exiting]` — Popover 消失过程中应用 * **位置**：`[data-placement="*"]` — 根据 Popover 位置应用 * **焦点**：`:focus-visible` 或 `[data-focus-visible="true"]` ## API 参考 ### Popover | Prop | 类型 | 默认值 | 描述 | | -------------- | --------------------------- | ------- | ------------------- | | `children` | `React.ReactNode` | - | 触发器与内容元素 | | `isOpen` | `boolean` | - | 控制 Popover 是否可见（受控） | | `defaultOpen` | `boolean` | `false` | 初始打开状态（非受控） | | `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化时调用 | ### Popover.Content | Prop | 类型 | 默认值 | 描述 | | ------------ | -------------------------------------------------------------------------- | ---------- | ---------------------- | | `children` | `React.ReactNode` | - | 在 Popover 中展示的内容 | | `placement` | `"top" \| "bottom" \| "left" \| "right"` (及变体) | `"bottom"` | Popover 的位置 | | `offset` | `number` | `8` | 与触发元素的距离 | | `shouldFlip` | `boolean` | `true` | 是否允许 Popover 改变方向以适配空间 | | `className` | `string` | - | 额外的 CSS 类名 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, PopoverRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 | ### Popover.Dialog | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ---------- | | `children` | `React.ReactNode` | - | 对话框内容 | | `className` | `string` | - | 额外的 CSS 类名 | ### Popover.Trigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | -------------- | | `children` | `React.ReactNode` | - | 触发 Popover 的元素 | | `className` | `string` | - | 额外的 CSS 类名 | ### Popover.Arrow | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------- | --- | ---------------------- | | `children` | `React.ReactNode` | - | 自定义箭头元素 | | `className` | `string` | - | 额外的 CSS 类名 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, OverlayArrowRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 | ## 相关组件 ## Related Components * **Button**: Allows a user to perform an action * **Tooltip**: Contextual information on hover or focus * **Select**: Dropdown select control </page> <page url="/cn/docs/react/components/sheet"> # Sheet 面板 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/sheet **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(overlays)/sheet.mdx > 支持原生滚动吸附、分段展开和嵌套的滑动面板 ## 用法 ```tsx import {Button, Sheet} from "@heroui/react"; ``` ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function Basic() { return ( <Sheet> <Sheet.Trigger> <Button variant="secondary">打开面板</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-h-[95vh] max-w-[420px]"> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger aria-label="关闭面板" /> <Sheet.Header> <Sheet.Heading>面板标题</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> 这是一个具有流畅拖动关闭动画的底部面板。向下拖动手柄或点击关闭按钮即可关闭。 </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">取消</Button> </Sheet.Close> <Sheet.Close> <Button variant="secondary">确认</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ## 组件结构 ```tsx import {Button, Sheet} from "@heroui/react"; export default () => ( <Sheet> <Sheet.Trigger> <Button>打开面板</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger /> <Sheet.Header> <Sheet.Heading>详情</Sheet.Heading> </Sheet.Header> <Sheet.Body>面板内容</Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button>完成</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); ``` `Sheet.Root` 是 `Sheet` 的别名。将 `Sheet.Trigger` 直接放在根组件内，并包裹一个可按压元素（如 `Button`）。通过 `Sheet.Heading`、`aria-label` 或 `aria-labelledby` 为对话框提供无障碍名称。使用 `Sheet.Close`、`Sheet.CloseTrigger` 或带有 `slot="close"` 的按钮支持键盘关闭；拖动手柄对辅助技术隐藏。 ## 示例 ### 位置 根组件的 `placement` 支持 `bottom`（默认）、`top`、`left` 和 `right`。 ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function Placements() { const placements = ["bottom", "top", "left", "right"] as const; const labels = {bottom: "底部", left: "左侧", right: "右侧", top: "顶部"}; return ( <div className="flex flex-wrap gap-4"> {placements.map((p) => ( <Sheet key={p} placement={p}> <Sheet.Trigger> <Button variant="secondary">{labels[p]}</Button> </Sheet.Trigger> <Sheet.Backdrop variant="blur"> <Sheet.Content className={p === "left" || p === "right" ? "w-[400px]" : undefined}> <Sheet.Dialog> <Sheet.CloseTrigger aria-label="关闭面板" /> {p === "bottom" && <Sheet.Handle />} <Sheet.Header> <Sheet.Heading>{labels[p]}面板</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> 此面板以流畅的动画从屏幕的<strong>{labels[p]}</strong>滑入。 </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">取消</Button> </Sheet.Close> <Sheet.Close> <Button variant="secondary">完成</Button> </Sheet.Close> </Sheet.Footer> {p === "top" && <Sheet.Handle />} </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ))} </div> ); } ``` ### 吸附点 数字表示**像素**，而不是比例。字符串表示 CSS 长度；百分比相对于面板尺寸。面板初始停留在第一个吸附点，完整展开位置始终隐式存在。末尾的 `1`、`"1"` 或 `"100%"` 会被忽略。其他数字仍以像素为单位。 ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; const snapPointValues = ["148px", "355px"]; export function SnapPoints() { return ( <Sheet snapPoints={snapPointValues}> <Sheet.Trigger> <Button variant="secondary">吸附点</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content> <Sheet.Dialog> <Sheet.Handle /> <Sheet.Header> <Sheet.Heading>吸附点</Sheet.Heading> </Sheet.Header> <Sheet.Body> <div className="flex flex-col gap-4"> <p className="text-sm text-muted"> 此面板初始显示 148px，并可吸附至 355px。拖过最后一个吸附点后，面板将完全展开，背景也会逐渐淡入。 </p> {Array.from({length: 6}).map((_, i) => ( <p key={i} className="text-sm text-muted"> {i === 0 ? "向上滑动以显示更多内容，并使背景逐渐淡入。" : `此位置的更多内容（${i + 1}）。`} </p> ))} </div> </Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### 连续吸附点 一次滑动可以跨越多个吸附点。完全展开位置隐式存在，无需额外的连续吸附属性。 ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; const snapPointValues = ["148px", "355px"]; export function SnapPointsSequential() { return ( <Sheet snapPoints={snapPointValues}> <Sheet.Trigger> <Button variant="secondary">连续吸附点</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content> <Sheet.Dialog> <Sheet.Handle /> <Sheet.Header> <Sheet.Heading>吸附点</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> 一次滑动可以跨越多个吸附点。完全展开是手势的最终位置，因此无需将其单独列为吸附点。 </p> </Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### 吸附点（遮罩渐显） 经过部分展开的吸附点时，背景保持透明；越过最后一个吸附点并继续展开时，背景逐渐显现。此行为由 React Aria 管理，不支持 `fadeFromIndex`。 ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; const fadeSnapPoints = ["150px", "300px", "450px"]; export function SnapPointsCustomFade() { return ( <Sheet snapPoints={fadeSnapPoints}> <Sheet.Trigger> <Button variant="secondary">背景渐变</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content> <Sheet.Dialog> <Sheet.Handle /> <Sheet.Header> <Sheet.Heading>背景渐变</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> 经过各个吸附点时，背景保持透明。越过最后一个吸附点并继续完全展开面板时，背景才逐渐显现。 </p> </Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### 遮罩变体 ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function BackdropVariants() { const variants = ["opaque", "blur", "transparent"] as const; const labels = {blur: "模糊", opaque: "不透明", transparent: "透明"}; return ( <div className="flex flex-wrap gap-4"> {variants.map((v) => ( <Sheet key={v}> <Sheet.Trigger> <Button variant="secondary">{labels[v]}</Button> </Sheet.Trigger> <Sheet.Backdrop variant={v}> <Sheet.Content className="mx-auto max-h-[95vh] max-w-[420px]"> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger aria-label="关闭面板" /> <Sheet.Header> <Sheet.Heading>背景：{labels[v]}</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> 此面板使用 <code className="text-foreground">{v}</code> 背景变体。 </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button className="w-full">关闭</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ))} </div> ); } ``` ### 不可关闭 `isDismissable={false}` 阻止点击外部、Escape 和滑动关闭。显式关闭按钮仍然可用。 ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function NonDismissable() { return ( <Sheet isDismissable={false}> <Sheet.Trigger> <Button variant="secondary">重要操作</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog> <Sheet.Header> <Sheet.Heading>确认操作</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> 此面板无法通过点击外部或拖动关闭，请使用下方的按钮。 </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">取消</Button> </Sheet.Close> <Sheet.Close> <Button variant="secondary">确认</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### 可滚动内容 在部分展开时，滑动会展开面板；完全展开后，`Sheet.Body` 才滚动内部内容。`Sheet.Handle` 也支持鼠标拖动。 ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function ScrollableContent() { return ( <Sheet> <Sheet.Trigger> <Button variant="secondary">条款与条件</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-h-[95vh] max-w-[420px]"> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger aria-label="关闭面板" /> <Sheet.Header> <Sheet.Heading>条款与条件</Sheet.Heading> </Sheet.Header> <Sheet.Body> {Array.from({length: 20}).map((_, i) => ( <p key={i} className="mb-3 text-sm text-muted"> 第 {i + 1}{" "} 段：使用本服务前，请仔细阅读相关条款与条件。继续使用即表示您已了解并同意这些条款。我们会持续改进服务，如有变更，将及时通知您。 </p> ))} </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">拒绝</Button> </Sheet.Close> <Sheet.Close> <Button variant="secondary">接受</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### 搭配表单 在 `Sheet.Body` 内组合表单字段。在面板表面使用次要样式的输入框。 ```tsx "use client"; import {Button, Input, Label, Sheet, TextField} from "@heroui/react"; export function WithForm() { return ( <Sheet placement="right"> <Sheet.Trigger> <Button variant="secondary">编辑个人资料</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="w-[400px]"> <Sheet.Dialog> <Sheet.CloseTrigger aria-label="关闭面板" /> <Sheet.Header> <Sheet.Heading>编辑个人资料</Sheet.Heading> </Sheet.Header> <Sheet.Body> <form className="flex flex-col gap-4"> <TextField className="w-full" name="name" type="text"> <Label>姓名</Label> <Input placeholder="输入姓名" variant="secondary" /> </TextField> <TextField className="w-full" name="email" type="email"> <Label>邮箱</Label> <Input placeholder="输入邮箱" variant="secondary" /> </TextField> <TextField className="w-full" name="bio"> <Label>个人简介</Label> <Input placeholder="介绍一下自己" variant="secondary" /> </TextField> </form> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">取消</Button> </Sheet.Close> <Sheet.Close> <Button variant="secondary">保存更改</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### 悬浮面板 `isDetached` 在屏幕边缘与面板之间添加间距，并将所有角设为圆角。 ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function Detached() { const placements = ["bottom", "top", "left", "right"] as const; const labels = {bottom: "底部", left: "左侧", right: "右侧", top: "顶部"}; return ( <div className="flex flex-wrap gap-4"> {placements.map((p) => ( <Sheet key={p} isDetached placement={p}> <Sheet.Trigger> <Button variant="secondary">{labels[p]}</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className={p === "left" || p === "right" ? "w-[310px]" : "mx-auto max-w-[420px]"} > <Sheet.Dialog className={p === "left" || p === "right" ? "h-full" : undefined}> {p === "bottom" && <Sheet.Handle />} <Sheet.Body className="flex flex-col gap-4 py-5"> <Sheet.Heading>悬浮面板：{labels[p]}</Sheet.Heading> <p className="text-sm text-muted">面板悬浮于视口边缘内侧，四个角均为圆角。</p> </Sheet.Body> {p === "top" && <Sheet.Handle />} </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ))} </div> ); } ``` ### 受控状态 组合使用 `isOpen` 和 `onOpenChange`，或用 `defaultOpen` 设置非受控初始状态。受控面板可以省略 `Sheet.Trigger`。 ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const [isOpen, setIsOpen] = useState(false); return ( <div className="flex flex-col items-start gap-4"> <div className="flex items-center gap-3"> <Button size="sm" variant="secondary" onPress={() => setIsOpen(true)}> 打开面板 </Button> <Button size="sm" variant="secondary" onPress={() => setIsOpen(!isOpen)}> 切换 </Button> <p className="text-xs text-muted"> 状态：{" "} <span className="font-mono font-medium text-foreground"> {isOpen ? "已打开" : "已关闭"} </span> </p> </div> <Sheet isOpen={isOpen} onOpenChange={setIsOpen}> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger aria-label="关闭面板" /> <Sheet.Header> <Sheet.Heading>受控面板</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> 通过 <code>isOpen</code> 和 <code>onOpenChange</code>{" "} 属性控制面板，由父组件在外部管理状态。 </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button>关闭</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> </div> ); } ``` ### 拖动手柄 手柄提供可见的拖动提示，并支持指针拖动。面板完全展开前，触摸滑动也可作用于面板本身，并不限于手柄区域。 ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; export function HandleOnly() { return ( <Sheet> <Sheet.Trigger> <Button variant="secondary">拖动手柄</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog> <Sheet.Handle /> <Sheet.CloseTrigger aria-label="关闭面板" /> <Sheet.Header> <Sheet.Heading>滑动面板</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> 手柄提供可拖动的视觉提示。面板完全展开前，可以在面板任意位置滑动；完全展开后，滑动会滚动内容，而不再移动面板。 </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">完成</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### 嵌套面板 将 `Sheet.NestedRoot` 放在另一个面板内。React Aria 管理堆叠和焦点恢复，只有最底层面板使页面背景变暗。 ```tsx "use client"; import {Button, Sheet} from "@heroui/react"; const NESTED_DIALOG_HEIGHT = "h-[320px]"; export function Nested() { return ( <Sheet> <Sheet.Trigger> <Button variant="secondary">打开父面板</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog className={NESTED_DIALOG_HEIGHT}> <Sheet.Handle /> <Sheet.CloseTrigger aria-label="关闭面板" /> <Sheet.Header> <Sheet.Heading>父面板</Sheet.Heading> </Sheet.Header> <Sheet.Body className="flex flex-col justify-between pb-4"> <p className="mb-4 text-sm text-muted"> 这是父面板。打开嵌套面板时，父面板会缩小，子面板滑入其上方。 </p> <Sheet.NestedRoot> <Sheet.Trigger> <Button className="w-full" variant="secondary"> 打开嵌套面板 </Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog className={NESTED_DIALOG_HEIGHT}> <Sheet.Handle /> <Sheet.CloseTrigger aria-label="关闭面板" /> <Sheet.Header> <Sheet.Heading>嵌套面板</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="mb-4 text-sm text-muted"> 这是位于父面板上方的嵌套面板。向下拖动即可关闭并返回父面板。 </p> <Sheet.NestedRoot> <Sheet.Trigger> <Button className="w-full" variant="secondary"> 继续深入 </Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-[420px]"> <Sheet.Dialog className={NESTED_DIALOG_HEIGHT}> <Sheet.Handle /> <Sheet.CloseTrigger aria-label="关闭面板" /> <Sheet.Header> <Sheet.Heading>第三层</Sheet.Heading> </Sheet.Header> <Sheet.Body> <p className="text-sm text-muted"> 已经到达第三层！下一层打开时，其父面板会缩小，形成堆叠效果。 </p> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button className="w-full">关闭</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet.NestedRoot> </Sheet.Body> <Sheet.Footer> <Sheet.Close> <Button variant="secondary">返回</Button> </Sheet.Close> </Sheet.Footer> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet.NestedRoot> </Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ); } ``` ### 职业选择器 在初始吸附点为 355px 的面板中组合搜索框和虚拟列表。选择职业后更新所选值并关闭面板。 ```tsx "use client"; import { Button, EmptyState, Label, ListBox, ListLayout, SearchField, Sheet, Virtualizer, } from "@heroui/react"; import {Icon} from "@iconify/react"; import {useMemo, useState} from "react"; const PROFESSIONS = [ "会计师和审计师", "演员", "精算师", "行政服务经理", "广告和推广经理", "广告销售代理", "航空航天工程师", "农业工程师", "空中交通管制员", "飞机机械师和维修技术员", "救护车司机和随车人员", "麻醉科医生", "动物管理人员", "动画师", "仲裁员和调解员", "建筑师（景观和船舶建筑除外）", "建筑与工程经理", "档案管理员", "艺术总监", "运动防护师", "大气与空间科学家", "听力学家", "汽车车身维修工", "汽车维修技术员和机械师", "行李搬运员和酒店行李员", "面包师", "理发师", "调酒师", "自行车维修工", "账单与记账文员", "生物化学家和生物物理学家", "生物医学工程师", "簿记、会计和审计文员", "砖石砌筑工", "广播技术员", "预算分析师", "公交车司机", "业务运营专员", "屠宰工和肉类切割工", "橱柜制作工和木工", "电视、视频和电影摄影师", "心血管技术人员", "货运代理", "木匠", "收银员", "水泥和混凝土修整工", "厨师长和主厨", "化学工程师", "化学家", "首席执行官", "儿童、家庭和学校社会工作者", "脊椎治疗师", "土木工程师", "理赔核算员、审查员和调查员", "临床检验技术人员", "教练和球探", "商业飞行员", "社区卫生工作者", "薪酬福利经理", "计算机与信息系统经理", "计算机硬件工程师", "计算机网络架构师", "程序员", "计算机系统分析师", "自然资源保护科学家", "建筑工人", "建筑项目经理", "惩教人员和监狱看守", "成本估算师", "咨询师", "法庭记录员和实时字幕员", "信用分析师", "策展人", "客服代表", "网络安全分析师", "数据科学家", "数据库管理员", "牙科助理", "口腔卫生师", "牙医", "侦探和刑事调查员", "医学超声诊断技师", "膳食与营养师", "宗教活动和教育负责人", "唱片骑师", "调度员", "经济学家", "编辑", "教育行政人员", "电气工程师", "电工", "小学教师", "应急管理负责人", "急救技术员和护理人员", "环境工程师", "环境科学家和专员", "流行病学家", "活动策划师", "运动生理学家", "时装设计师", "影视剪辑师", "金融分析师", "金融审查员", "财务经理", "消防检查员和调查员", "消防员", "健身教练和有氧运动指导员", "空乘人员", "花艺设计师", "食品科学家和技术人员", "法医学技术员", "筹款专员", "殡葬服务人员", "总经理和运营经理", "遗传咨询师", "地理学家", "地球科学家", "玻璃安装工", "平面设计师", "美发师、发型师和美容师", "健康与安全工程师", "医疗社会工作者", "供暖、空调和制冷维修工", "高中教师", "历史学家", "居家健康和个人护理员", "人力资源经理", "人力资源专员", "水文学家", "工业设计师", "工业工程师", "工业机械维修工", "信息安全分析师", "保险评估师", "保险销售代理", "保险核保员", "室内设计师", "口译和笔译人员", "保洁员", "珠宝和宝石加工人员", "新闻工作者", "法官", "幼儿园教师", "景观建筑师", "律师", "图书管理员和媒体馆藏专员", "执业护士", "信贷员", "锁匠和保险柜维修工", "物流专员", "机器学习工程师", "机械加工工人", "家政和客房清洁员", "管理分析师", "轮机工程师和船舶设计师", "市场研究分析师", "市场营销经理", "婚姻和家庭治疗师", "按摩治疗师", "数学家", "机械工程师", "医疗助理", "病案管理专员", "医学科学家", "微生物学家", "初中教师", "工业设备安装工", "采矿和地质工程师", "音乐总监和作曲家", "音乐家和歌手", "网络与计算机系统管理员", "核工程师", "麻醉专科护士", "高级执业护士", "护理助理", "职业健康与安全专员", "作业治疗师", "配镜师", "验光师", "正畸医生", "律师助理和法律助理", "停车执法人员", "病理科医生", "儿科医生", "个人理财顾问", "害虫防治人员", "药剂师", "药房技术员", "采血员", "摄影师", "物理治疗助理", "物理治疗师", "医师助理", "内外科医生", "物理学家", "工业管道和蒸汽管道安装工", "水管工", "足病医生", "警察", "政治学家", "邮递员", "高等教育教师", "学前教育教师", "私家侦探和调查员", "缓刑监督官", "制片人和导演", "产品经理", "物业经理", "口腔修复医生", "精神科技术人员", "精神科医生", "心理学家", "公关经理", "公关专员", "采购经理", "放射治疗师", "放射技术人员", "房地产经纪人", "接待员和咨询文员", "文体活动工作者", "娱乐治疗师", "注册护士", "康复咨询师", "记者和通讯员", "呼吸治疗师", "餐厅厨师", "屋顶施工工人", "销售工程师", "销售经理", "校车司机", "学校心理学家", "保安", "钣金工", "治安官和副治安官", "护肤专员", "社会与社区服务经理", "社会工作者", "软件开发人员", "软件质量保证分析师", "音响工程技术员", "特殊教育教师", "言语语言治疗师", "统计学家", "建筑钢铁结构工", "成瘾问题咨询师", "外科医生", "调查研究员", "测量师", "税务审查和征收人员", "报税服务人员", "出租车和专职司机", "技术文档撰写员", "电信设备安装工", "银行柜员", "培训与发展经理", "培训与发展专员", "旅行代理", "城市与区域规划师", "用户体验设计师", "兽医", "兽医技术人员", "餐厅服务员", "水处理设备操作员", "网页开发人员", "焊接、切割和钎焊工", "作家", "动物学家和野生生物学家", ].map((name, i) => ({id: i, name})); const professionSheetSnaps = ["355px"]; export function ProfessionsPicker() { const [isOpen, setIsOpen] = useState(false); const [search, setSearch] = useState(""); const [selected, setSelected] = useState<string | null>(null); const filtered = useMemo(() => { if (!search) return PROFESSIONS; const q = search.toLowerCase(); return PROFESSIONS.filter((p) => p.name.toLowerCase().includes(q)); }, [search]); return ( <div className="flex flex-col items-center gap-3"> <Sheet isOpen={isOpen} snapPoints={professionSheetSnaps} onOpenChange={(open) => { setIsOpen(open); if (!open) setSearch(""); }} > <Sheet.Trigger> <Button variant="secondary">选择职业</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-h-[95vh] max-w-[420px]"> <Sheet.Dialog aria-label="选择职业"> <Sheet.Handle /> <Sheet.Body className="flex min-h-0 flex-col gap-0 overflow-hidden p-0"> <div className="px-4 pt-1 pb-2"> <SearchField aria-label="搜索职业" value={search} variant="secondary" onChange={setSearch} > <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> </div> {filtered.length === 0 ? ( <EmptyState className="flex min-h-32 flex-1 flex-col items-center justify-center gap-2"> <Icon className="size-5 text-muted" icon="gravity-ui:magnifier" /> <p className="text-sm text-muted">未找到职业。</p> </EmptyState> ) : ( <Virtualizer layout={ListLayout} layoutOptions={{padding: 12, rowHeight: 36}}> <ListBox aria-label="职业" className="min-h-0 flex-1 overflow-y-auto p-0" items={filtered} selectionMode="single" onAction={(key) => { const prof = PROFESSIONS.find((p) => p.id === Number(key)); if (prof) { setSelected(prof.name); setIsOpen(false); } }} > {(item) => ( <ListBox.Item id={item.id} textValue={item.name}> <Label>{item.name}</Label> </ListBox.Item> )} </ListBox> </Virtualizer> )} </Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> <p className="text-sm text-muted"> 已选择： <span className="font-medium text-foreground">{selected}</span> </p> </div> ); } ``` ## 自定义样式 通过各部分的 `className` 或 `@layer components` 中的 `sheet__*` BEM 类自定义样式。保留 React Aria 的滚动定位，不要叠加独立的位移动画。 ### Tailwind CSS 通过 `className` 为各部分添加 Tailwind CSS 工具类。 ```tsx <Sheet> <Sheet.Trigger> <Button variant="secondary">打开面板</Button> </Sheet.Trigger> <Sheet.Backdrop> <Sheet.Content className="mx-auto max-w-lg"> <Sheet.Dialog className="rounded-t-3xl border border-border"> <Sheet.Handle /> <Sheet.CloseTrigger aria-label="关闭面板" /> <Sheet.Header className="text-center"> <Sheet.Heading>详情</Sheet.Heading> </Sheet.Header> <Sheet.Body className="px-6 pb-6">面板内容</Sheet.Body> </Sheet.Dialog> </Sheet.Content> </Sheet.Backdrop> </Sheet> ``` ### 全局 CSS 使用 `@layer components` 自定义 Sheet 的 BEM 类。 ```css @layer components { .sheet__dialog { @apply border border-border; } .sheet__header { @apply text-center; } .sheet__body { @apply px-6 pb-6; } } ``` ## 样式参考 HeroUI 使用 [BEM](https://getbem.com/) 命名规范，使组件样式易于复用和自定义。 ### CSS 类 #### 基础类 \[!toc] * `.sheet__overlay` - 模态遮罩容器 * `.sheet__backdrop` - 面板后方的背景遮罩 * `.sheet__content` - 控制面板尺寸与堆叠的容器 * `.sheet__dialog` - 对话框表面 * `.sheet__header` - 头部区域 * `.sheet__heading` - 对话框标题 * `.sheet__body` - 完全展开后可滚动的内容区域 * `.sheet__footer` - 底部操作区域 * `.sheet__handle` - 可拖动的手柄区域 * `.sheet__handle-bar` - 默认手柄指示条 * `.sheet__close-trigger` - 关闭按钮 #### 遮罩变体 \[!toc] * `.sheet__backdrop--opaque` - 暗色遮罩（默认） * `.sheet__backdrop--blur` - 模糊背景遮罩 * `.sheet__backdrop--transparent` - 透明背景遮罩 嵌套时，仅最底层面板显示背景遮罩。 #### 位置变体 \[!toc] * `.sheet__content--bottom`, `.sheet__dialog--bottom` - 底部（默认） * `.sheet__content--top`, `.sheet__dialog--top` - 顶部 * `.sheet__content--left`, `.sheet__dialog--left` - 左侧 * `.sheet__content--right`, `.sheet__dialog--right` - 右侧 ### 交互状态 * `[data-focus-visible="true"]` - 关闭按钮的键盘焦点；原生回退选择器为 `:focus-visible:not([data-focused])` * `:hover`, `[data-hovered="true"]` - 关闭按钮悬停 * `:disabled`, `[aria-disabled="true"]` - 关闭按钮禁用 * `[data-dragging]` - 正在拖动手柄 * `[data-expanded]` - 面板完全展开，启用内容滚动 * `[data-has-descendants]` - 存在已打开的嵌套面板 * `[data-detached]` - 面板与边缘留有间距，并使用圆角 * `[data-snap-points]` - 面板配置了部分展开吸附点 * `[data-entering]`, `[data-exiting]` - 打开与关闭的生命周期状态 * `[data-closed]` - 保留的已关闭遮罩，禁用指针交互 ### 数据属性 DOM 部分提供以下 `data-slot`：`sheet-overlay`、`sheet-backdrop`、`sheet-content`、`sheet-dialog`、`sheet-header`、`sheet-heading`、`sheet-body`、`sheet-footer`、`sheet-handle`、`sheet-handle-bar` 和 `sheet-close-trigger`。根组件、Trigger 和 Close 不添加 DOM 元素。 `Sheet.Content` 还提供 `data-placement`、`data-detached` 和 `data-snap-points`。React Aria 在相应部分提供 `data-position`、`data-expanded`、`data-stack-index`、`data-has-descendants`、`data-entering` 和 `data-exiting`。 ## API 参考 ### Sheet / Sheet.Root / Sheet.NestedRoot | 属性 | 类型 | 默认值 | 说明 | | ---------------- | ---------------------------------------- | ---------- | --------------------- | | `children` | `ReactNode` | — | 组合部分。 | | `isOpen` | `boolean` | — | 受控打开状态。 | | `defaultOpen` | `boolean` | `false` | 非受控初始状态。 | | `onOpenChange` | `(open: boolean) => void` | — | 请求打开或关闭时调用。 | | `onClose` | `() => void` | — | 请求关闭时调用。 | | `onAnimationEnd` | `(open: boolean) => void` | — | 进入或退出结束后调用。 | | `placement` | `"bottom" \| "top" \| "left" \| "right"` | `"bottom"` | 屏幕的物理边缘。 | | `isDismissable` | `boolean` | `true` | 允许外部交互、Escape 和滑动关闭。 | | `isDetached` | `boolean` | `false` | 面板与屏幕边缘保持间距。 | | `snapPoints` | `(number \| string)[]` | — | 部分展开的吸附位置；完整展开位置隐式存在。 | `Sheet.NestedRoot` 必须在父 Sheet 内使用。根组件的 `isNested` 为内部标记；嵌套时使用 `NestedRoot`。 ### Sheet.Trigger | 属性 | 类型 | 默认值 | 说明 | | ---------- | -------------- | --- | -------------------------------- | | `children` | `ReactElement` | — | 一个可按压的子元素，如 Button。直接放在 Sheet 内。 | ### Sheet.Close | 属性 | 类型 | 默认值 | 说明 | | ---------- | -------------- | --- | -------------------------------- | | `children` | `ReactElement` | — | 一个可按压的子元素；其 onPress 回调与关闭操作组合执行。 | ### Sheet.Backdrop | 属性 | 类型 | 默认值 | 说明 | | ----------- | ------------------------------------- | ---------- | ---------------- | | `children` | `ReactNode` | — | 要渲染的内容。 | | `className` | `string` | — | CSS 类名。 | | `variant` | `"opaque" \| "blur" \| "transparent"` | `"opaque"` | 遮罩外观。 | | `isExiting` | `boolean` | — | 关闭后保留内容，直到清除此标记。 | 其他属性继承自 React Aria SheetOverlay，但不包含由根组件控制的状态、位置、吸附点和 `style`。关闭仍会释放模态焦点限制和页面滚动锁定。不再需要保留内容时，请清除 `isExiting`。 ### Sheet.Content | 属性 | 类型 | 默认值 | 说明 | | ----------- | -------------------------------------------------------- | --- | ------------------------- | | `children` | `ReactNode \| ((values: SheetRenderProps) => ReactNode)` | — | 内容或接收 React Aria 面板状态的函数。 | | `className` | `string` | — | CSS 类名。 | 其余属性继承自 React Aria Sheet。HeroUI 管理堆叠动画与过度滚动留白；`stackAnimation` 和 `overscrollPadding` 无法通过此组件覆盖。 ### Sheet.Dialog | 属性 | 类型 | 默认值 | 说明 | | ------------------ | --------------------------- | ---------- | --------------- | | `children` | `ReactNode` | — | 要渲染的内容。 | | `className` | `string` | — | CSS 类名。 | | `role` | `"dialog" \| "alertdialog"` | `"dialog"` | 对话框无障碍角色。 | | `aria-label` | `string` | — | 没有可见标题时的无障碍名称。 | | `aria-labelledby` | `string` | — | 为对话框提供名称的元素 ID。 | | `aria-describedby` | `string` | — | 描述对话框的元素 ID。 | 其余属性与 ref 继承自 React Aria SheetContent。 ### Sheet.Header | 属性 | 类型 | 默认值 | 说明 | | ----------- | ----------- | --- | ------- | | `children` | `ReactNode` | — | 头部内容。 | | `className` | `string` | — | CSS 类名。 | 支持标准 div 属性、事件处理函数和 ref。 ### Sheet.Heading | 属性 | 类型 | 默认值 | 说明 | | ----------- | ----------- | --------- | ---------- | | `children` | `ReactNode` | — | 对话框标题。 | | `className` | `string` | — | CSS 类名。 | | `slot` | `string` | `"title"` | 将标题关联到对话框。 | 其余属性与 ref 继承自 React Aria Heading。 ### Sheet.Body | 属性 | 类型 | 默认值 | 说明 | | ----------- | ----------- | --- | --------- | | `children` | `ReactNode` | — | 可滚动的主体内容。 | | `className` | `string` | — | CSS 类名。 | 支持标准 div 属性、事件处理函数和 ref。 ### Sheet.Footer | 属性 | 类型 | 默认值 | 说明 | | ----------- | ----------- | --- | ------- | | `children` | `ReactNode` | — | 底部操作。 | | `className` | `string` | — | CSS 类名。 | 支持标准 div 属性、事件处理函数和 ref。 ### Sheet.Handle | 属性 | 类型 | 默认值 | 说明 | | ----------- | ----------- | --- | ----------------- | | `children` | `ReactNode` | — | 自定义手柄；省略时渲染默认指示条。 | | `className` | `string` | — | CSS 类名。 | 支持标准 div 属性、事件处理函数和 ref。 ### Sheet.CloseTrigger | 属性 | 类型 | 默认值 | 说明 | | ------------ | --------------------------------------------------------- | --------- | ---------------- | | `children` | `ReactNode \| ((values: ButtonRenderProps) => ReactNode)` | — | 自定义内容；默认显示关闭图标。 | | `className` | `string` | — | CSS 类名。 | | `isDisabled` | `boolean` | `false` | 禁用关闭按钮。 | | `aria-label` | `string` | `"Close"` | 无障碍名称；按需提供本地化文本。 | | `onPress` | `(event: PressEvent) => void` | — | 与面板关闭操作一起调用。 | 其余属性与 ref 继承自 CloseButton。 命名导出包括 `SheetRoot`、`SheetTrigger` 等各部分、对应的属性类型、`SheetProps`、`SheetNestedRootProps`、`sheetVariants` 和 `SheetVariants`。组合属性类型使用索引访问，例如 `Sheet["Props"]` 和 `Sheet["ContentProps"]`。 ## Sheet 与 Drawer Sheet 使用 React Aria 原生滚动手势，支持部分吸附位置和嵌套堆叠。Drawer 保留原有 API 和行为；新增 Sheet 不会迁移或弃用 Drawer。 ## 无障碍 * **无障碍名称**：使用 `Sheet.Heading`、`aria-label` 或 `aria-labelledby` 为对话框提供名称。 * **焦点管理**：打开时将焦点移入面板并限制在当前模态面板内。关闭后，焦点返回触发器；关闭嵌套面板后返回父面板。 * **键盘**：使用 `Tab` 和 `Shift+Tab` 在控件间移动；允许关闭时，`Escape` 关闭面板。 * **关闭控件**：`Sheet.Close` 和 `Sheet.CloseTrigger` 支持键盘操作，即使 `isDismissable={false}` 也可关闭面板。 * **滚动锁定**：模态面板打开时锁定页面滚动。完全展开后，`Sheet.Body` 可滚动。保留的已关闭内容不会继续锁定页面。 * **拖动手柄**：手柄对辅助技术隐藏，不可通过键盘拖动。请提供可访问的关闭控件，不要仅依赖滑动手势。 ## 相关组件 ## Related Components * **Drawer**: Slide-out panel for supplementary content and actions * **Modal**: Displays content in a modal overlay * **Button**: Allows a user to perform an action </page> <page url="/cn/docs/react/components/toast"> # Toast 轻提示 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/toast **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(overlays)/toast.mdx > 向用户展示临时通知与消息，支持自动消失与可定制的放置位置。 ## 用法 ```tsx import { Toast, toast } from '@heroui/react'; ``` ```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={() => { const id = toast("您已被邀请加入团队", { actionProps: { children: "忽略", onPress: () => toast.close(id), variant: "tertiary", }, description: "Bob 邀请您加入 HeroUI 团队", indicator: <Persons />, variant: "default", }); }} > 显示 Toast </Button> </div> ); } ``` ## 组件结构 ```tsx <Toast.Provider> <Toast> <Toast.Indicator /> <Toast.Content> <Toast.Title /> <Toast.Description /> </Toast.Content> <Toast.ActionButton /> <Toast.CloseButton /> </Toast> </Toast.Provider> ``` ## 示例 ### 变体 ```tsx "use client"; import {HardDrive, Persons} from "@gravity-ui/icons"; import {Button, toast} from "@heroui/react"; 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={() => { const id = toast("您已被邀请加入团队", { actionProps: { children: "忽略", onPress: () => toast.close(id), variant: "tertiary", }, description: "Bob 邀请您加入 HeroUI 团队", indicator: <Persons />, variant: "default", }); }} > 默认 Toast </Button> <Button size="sm" variant="secondary" onPress={() => { const id = toast.info("您还剩 2 个积分", { actionProps: {children: "升级", onPress: () => toast.close(id)}, description: "升级付费方案以获取更多积分", }); }} > 强调 Toast </Button> <Button className="text-success" size="sm" variant="tertiary" onPress={() => { const id = toast.success("您已升级方案", { actionProps: { children: "账单", className: "bg-success text-success-foreground", onPress: () => toast.close(id), }, description: "您可以继续使用 HeroUI Chat", }); }} > 成功 Toast </Button> <Button className="text-warning" size="sm" variant="tertiary" onPress={() => { const id = toast.warning("您的积分已用完", { actionProps: { children: "升级", className: "bg-warning text-warning-foreground", onPress: () => toast.close(id), }, description: "升级付费方案以继续使用", }); }} > 警告 Toast </Button> <Button size="sm" variant="danger-soft" onPress={() => { const id = toast.danger("存储空间已满", { actionProps: {children: "删除", onPress: () => toast.close(id), variant: "danger"}, description: "删除文件以释放空间。此处增加更多文字以演示较长内容的显示效果", indicator: <HardDrive />, }); }} > 危险 Toast </Button> </div> </div> ); } ``` ### 放置位置 ```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: "活动已创建", title: "活动已创建", 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> ); } ``` ### 展开堆叠 ```tsx "use client"; import {Button, Toast, ToastQueue} from "@heroui/react"; const queue = new ToastQueue(); export function Expanded() { return ( <div className="flex h-full max-w-xl flex-col items-center justify-center"> <Toast.Provider isExpanded aria-label="展开的通知" placement="bottom" queue={queue} /> <Button size="sm" variant="secondary" onPress={() => { queue.add({ title: "简单消息", variant: "default", }); setTimeout(() => { queue.add({ title: "操作已完成", variant: "success", }); }, 400); setTimeout(() => { queue.add({ title: "有新更新可用", variant: "accent", }); }, 800); }} > 显示 3 条 Toast </Button> </div> ); } ``` ### 简单 Toast ```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("简单消息")}> 默认 </Button> <Button size="sm" variant="secondary" onPress={() => toast.success("操作已完成")}> 成功 </Button> <Button size="sm" variant="secondary" onPress={() => toast.info("有新更新可用")}> 信息 </Button> <Button size="sm" variant="secondary" onPress={() => toast.warning("请检查您的设置")}> 警告 </Button> <Button size="sm" variant="secondary" onPress={() => toast.danger("出了点问题")}> 错误 </Button> </div> </div> ); } ``` ### 自定义指示器 ```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("自定义图标指示器", { indicator: <Star />, }) } > 自定义指示器 </Button> </div> ); } ``` ### 自定义 Toast 渲染 ```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 pe-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 end-2 top-1/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: "使用自定义渲染函数", title: "自定义布局 Toast", variant: "default", }); }} > 自定义 Toast </Button> </div> ); } ``` ### Promise 与加载中 ```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("网络错误，请重试。")), 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("保存数据失败")); } }, 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">使用 toast.promise()</h3> <p className="text-xs text-muted">自动处理加载、成功和错误状态</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: "上传文件失败", loading: "正在上传文件…", success: (data) => `文件 ${data.filename} 已上传（${data.size}KB）`, }); }} > 上传文件 </Button> <Button size="sm" variant="secondary" onPress={() => { toast.promise(createEvent(), { error: (err) => err.message, loading: "正在创建活动…", success: "活动已创建", }); }} > 创建活动（错误） </Button> <Button size="sm" variant="secondary" onPress={() => { toast.promise(saveData(), { error: (err) => err.message, loading: "正在保存更改…", success: (data) => `已保存 ${data.count} 项`, }); }} > 保存数据（随机） </Button> <Button size="sm" variant="secondary" onPress={() => { toast.promise(fetchUser(), { error: "获取用户失败", loading: "正在加载用户…", success: (data) => `欢迎回来，${data.name}！`, }); }} > 获取用户 </Button> </div> </div> {/* Manual Loading Section */} <div className="w-full space-y-3"> <div className="text-center"> <h3 className="text-sm font-medium">手动加载状态</h3> <p className="text-xs text-muted">使用 isLoading 属性手动控制加载状态</p> </div> <div className="flex w-full flex-wrap items-center justify-center gap-4"> <Button size="sm" variant="secondary" onPress={() => { const loadingId = toast("正在上传文件…", { description: "请稍候，正在上传您的文件", isLoading: true, timeout: 0, }); setTimeout(() => { toast.update(loadingId, "文件已上传", { description: "您的文件已成功上传", variant: "success", }); }, 3000); }} > 上传（含加载） </Button> <Button size="sm" variant="secondary" onPress={() => { const loadingId = toast("正在处理付款…", { isLoading: true, timeout: 0, }); setTimeout(() => { toast.update(loadingId, "付款已处理", { description: "您的付款已成功处理", variant: "success", }); }, 2500); }} > 付款处理 </Button> <Button size="sm" variant="secondary" onPress={() => { const loadingId = toast("正在保存更改…", { isLoading: true, timeout: 0, }); setTimeout(() => { toast.update(loadingId, "保存失败", { description: "请重试", variant: "danger", }); }, 2000); }} > 加载后显示错误 </Button> </div> </div> </div> ); } ``` ### 回调 ```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("文件已保存", { onClose: () => { addToHistory("文件已保存（3 秒后关闭）"); }, timeout: 3000, }) } > 自定义超时（3 秒） </Button> <Button size="sm" variant="secondary" onPress={() => toast("更改已保存", { onClose: () => { addToHistory("更改已保存（10 秒后关闭）"); }, timeout: 10000, }) } > 自定义超时（10 秒） </Button> <Button size="sm" variant="secondary" onPress={() => toast.success("活动已创建", { onClose: () => { addToHistory("活动已创建（默认超时后关闭）"); }, }) } > 使用 onClose 回调 </Button> <Button size="sm" variant="secondary" onPress={() => toast("重要通知", { description: "此 Toast 将保持显示直至关闭", onClose: () => { addToHistory("重要通知（手动关闭）"); }, timeout: 0, }) } > 持久显示 Toast </Button> </div> {/* 关闭历史 Panel */} <div className="w-full space-y-2"> <div className="flex items-center justify-between"> <h3 className="text-sm font-medium">关闭历史</h3> {closedHistory.length > 0 && ( <Button className="h-6 text-xs" size="sm" variant="tertiary" onPress={() => setClosedHistory([])} > 清空 </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">尚无已关闭的 Toast。请尝试关闭上方的 Toast！</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="ms-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> ); } ``` ### 自定义队列 ```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: "您有一条新消息", title: "新通知", variant: "default", }); }} > 添加通知（最多 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: "保存更改失败", title: "发生错误", variant: "danger", }); }} > 添加错误（最多 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: `操作 ${Date.now()}`, title: "成功！", variant: "success", }); }} > 添加成功（最多 1 条） </Button> </div> </div> ); } ``` ### 配置 在应用根节点渲染 Provider。 ```tsx import { Toast, Button, toast } from '@heroui/react'; function App() { return ( <div> <Toast.Provider /> <Button onPress={() => toast("Simple message")}> Show toast </Button> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx "use client"; import type {ToastContentValue} from "@heroui/react"; import { Button, Toast, ToastContent, ToastDescription, ToastIndicator, ToastQueue, ToastTitle, } from "@heroui/react"; export function CustomStyles() { const queue = new ToastQueue(); return ( <div className="flex flex-col items-center gap-4"> <Toast.Provider placement="bottom" queue={queue}> {({toast: toastItem}) => { const content = toastItem.content as ToastContentValue; return ( <Toast className="rounded-xl border border-border/80 bg-surface shadow-lg ring-1 ring-black/5 dark:ring-white/10" toast={toastItem} variant={content.variant} > <ToastContent> <div className="flex items-center gap-2.5"> <ToastIndicator className="text-neutral-600 dark:text-neutral-400" variant={content.variant} /> <div className="flex flex-col gap-0.5"> {content.title ? ( <ToastTitle className="text-sm font-medium text-neutral-900 dark:text-neutral-50"> {content.title} </ToastTitle> ) : null} {content.description ? ( <ToastDescription className="text-sm text-neutral-600 dark:text-neutral-400"> {content.description} </ToastDescription> ) : null} </div> </div> </ToastContent> </Toast> ); }} </Toast.Provider> <Button size="sm" variant="secondary" onPress={() => { queue.add({ description: "草稿已同步", title: "已保存", variant: "default", }); }} > 显示提示 </Button> </div> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Toast 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/toast.css)）： #### 基础类 \[!toc] * `.toast` — Toast 根容器 * `.toast-region` — Toast 区域容器 * `.toast__content` — 包裹标题与说明的内容容器 * `.toast__indicator` — 图标/指示器容器 * `.toast__title` — Toast 标题文本 * `.toast__description` — Toast 说明文本 * `.toast__action` — 操作按钮容器 * `.toast__close-button` — 关闭按钮容器 #### 变体类 \[!toc] * `.toast--default` — 默认灰色变体 * `.toast--accent` — 强调蓝色变体 * `.toast--success` — 成功绿色变体 * `.toast--warning` — 警告黄/橙色变体 * `.toast--danger` — 危险红色变体 ### 交互状态 组件支持多种状态： * **最前**：`[data-frontmost]` — 应用于堆叠中最上层可见的 Toast * **索引**：`[data-index]` — 基于 Toast 在堆叠中的位置 * **放置**：`[data-placement="*"]` — 基于 Toast 区域的放置位置 * **进入中**：`[data-entering]` — Toast 首次绘制时应用 * **退出中**：`[data-exiting]` — 关闭中的 Toast 播放退出过渡时应用 * **展开**：`[data-expanded]` — 堆叠展开时应用于每个 Toast * **隐藏**：`[data-hidden]` — 应用于超出 `maxVisibleToasts` 的 Toast ## API 参考 ### Toast.Provider | Prop | 类型 | 默认值 | 描述 | | ------------------ | --------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `placement` | `"top start" \| "top" \| "top end" \| "bottom start" \| "bottom" \| "bottom end"` | `"bottom"` | Toast 区域的放置位置 | | `gap` | `number` | `12` | Toast 之间的间距（像素） | | `isExpanded` | `boolean` | `false` | 强制堆叠保持展开布局（不会暂停计时器） | | `maxVisibleToasts` | `number` | `3` | 同时最多显示的 Toast 数量 | | `hotkey` | `string[]` | `["altKey", "KeyT"]` | 将焦点移入 Toast 区域并展开堆叠的快捷键。修饰键使用 `KeyboardEvent` 布尔属性名（如 `"altKey"`），其他按键使用 `event.code`（如 `"KeyT"`）。未列出的修饰键必须处于松开状态，因此 `Alt`+`T` 不会在 `Ctrl`+`Alt`+`T` 时触发。传 `[]` 可禁用 | | `scaleFactor` | `number` | `0.05` | 堆叠 Toast 的缩放系数（0–1） | | `width` | `number \| string` | `460` | Toast 宽度（像素或 CSS 值） | | `queue` | `ToastQueue<T>` | - | 自定义 Toast 队列实例 | | `children` | `ReactNode \| ((props: {toast: QueuedToast<T>}) => ReactNode)` | - | 自定义渲染函数或子节点 | | `className` | `string` | - | 附加的 CSS 类 | ### Toast | Prop | 类型 | 默认值 | 描述 | | ------------- | ------------------------------------------------------------- | ----------- | --------------------------------------- | | `toast` | `QueuedToast<T>` | - | 来自队列的 Toast 数据（必填） | | `variant` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | Toast 的视觉变体 | | `placement` | `ToastVariants["placement"]` | - | 放置位置（继承自 Provider） | | `scaleFactor` | `number` | - | 缩放系数（继承自 Provider） | | `className` | `string` | - | 附加的 CSS 类 | | `children` | `ReactNode` | - | Toast 内容（ToastContent、ToastIndicator 等） | ### Toast.Content | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------------------------------- | | `children` | `ReactNode` | - | 内容（通常为 ToastTitle 与 ToastDescription） | | `className` | `string` | - | 附加的 CSS 类 | ### Toast.Indicator | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------- | --- | ----------------- | | `variant` | `ToastVariants["variant"]` | - | 默认图标的变体 | | `children` | `ReactNode` | - | 自定义指示图标（默认使用变体图标） | | `className` | `string` | - | 附加的 CSS 类 | ### Toast.Title | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | --------- | | `children` | `ReactNode` | - | 标题文本 | | `className` | `string` | - | 附加的 CSS 类 | ### Toast.Description | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | --------- | | `children` | `ReactNode` | - | 说明文本 | | `className` | `string` | - | 附加的 CSS 类 | ### Toast.ActionButton | Prop | 类型 | 默认值 | 描述 | | ------------------ | ----------- | --- | --------------------- | | `children` | `ReactNode` | - | 操作按钮内容 | | `className` | `string` | - | 附加的 CSS 类 | | All `Button` props | - | - | 接受 Button 组件的全部 props | ### Toast.CloseButton | Prop | 类型 | 默认值 | 描述 | | ----------------------- | -------- | --- | -------------------------- | | `className` | `string` | - | 附加的 CSS 类 | | All `CloseButton` props | - | - | 接受 CloseButton 组件的全部 props | ### ToastQueue `ToastQueue` 用于管理 `<Toast.Provider>` 的状态。状态存放在 React 之外，因此你可以在应用的任意位置触发 Toast。 #### 构造选项 | Option | 类型 | 默认值 | 描述 | | ------------------ | -------------------------- | ----- | --------------------------------------------------------------------------- | | `exitDuration` | `number` | `300` | 关闭中的 Toast 为播放退出动画而保持挂载的时长（0 表示立即移除） | | `maxVisibleToasts` | `number` | `3` | 同时最多显示的 Toast 数量（仅视觉） | | `wrapUpdate` | `(fn: () => void) => void` | - | 包裹状态更新的函数（例如 `document.startViewTransition`）；默认直接应用更新并由 CSS transition 驱动动画 | #### 方法 | Method | 参数 | 返回值 | 描述 | | ----------- | ------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------------------------------- | | `add` | `(content: T, options?: ToastOptions)` | `string` | 将 Toast 加入队列，返回 Toast key | | `update` | `(key: string, content: T, options?: {timeout?: number; onClose?: () => void})` | `boolean` | 原地更新 Toast，保持其在堆叠中的位置；`timeout` 重新开始倒计时（0 表示保持打开），省略则沿用当前倒计时。Toast 已不存在时返回 `false` | | `close` | `(key: string)` | `void` | 按 key 关闭 Toast | | `pauseAll` | `()` | `void` | 暂停所有 Toast 计时器 | | `resumeAll` | `()` | `void` | 恢复所有 Toast 计时器 | | `clear` | `()` | `void` | 关闭所有 Toast（每个 Toast 播放退出动画并触发各自的 `onClose`） | | `subscribe` | `(fn: () => void)` | `() => void` | 订阅队列变化，返回取消订阅函数 | ### toast 函数 默认 `toast` 函数提供便捷方法用于显示 Toast： ```tsx import { toast } from '@heroui/react'; // 基础 toast（默认约 4 秒后自动消失） toast("Event has been created"); // 变体方法（默认同样约 4 秒后自动消失） toast.success("File saved"); toast.info("New update available"); toast.warning("Please check your settings"); toast.danger("Something went wrong"); // 传入 options。利用返回的 id，操作按钮可以关闭它所属的 Toast。 const eventId = toast("Event has been created", { description: "Your event has been scheduled for tomorrow", variant: "default", timeout: 5000, // 自定义超时：5 秒 onClose: () => console.log("Closed"), actionProps: { children: "View", onPress: () => toast.close(eventId), }, indicator: <CustomIcon />, }); // 原地更新已有 Toast（保持其在堆叠中的位置）。 // 省略的选项会被继承，因此若原 Toast 是持久的，需要显式传入 `timeout` 才会开始倒计时。 const id = toast("Saving…", { timeout: 0 }); toast.update(id, "Saved", { variant: "success", timeout: 4000 }); // Promise 支持（自动显示加载指示）。Promise 结束时加载 Toast 会原地更新 — // 同一个 Toast、同一个堆叠位置；自动关闭倒计时从这一刻开始。 toast.promise( uploadFile(), { loading: "Uploading file...", success: (data) => `File ${data.filename} uploaded`, error: "Failed to upload file", } ); // 手动加载状态（持久 toast：不自动消失） const loadingId = toast("Creating event...", { isLoading: true, timeout: 0, // 持久 toast：不自动消失 }); // 随后原地更新，并开始自动关闭倒计时 toast.update(loadingId, "Event created", { variant: "success", timeout: 4000 }); // 队列方法 toast.close(key); toast.clear(); toast.pauseAll(); toast.resumeAll(); ``` #### toast Options | Option | 类型 | 默认值 | 描述 | | ------------- | ------------------------------------------------------------- | ----------- | ------------------------------------------------- | | `title` | `ReactNode` | - | Toast 标题（变体方法的第一个参数） | | `description` | `ReactNode` | - | 可选说明文本 | | `variant` | `"default" \| "accent" \| "success" \| "warning" \| "danger"` | `"default"` | 视觉变体 | | `indicator` | `ReactNode` | - | 自定义指示图标（`null` 可隐藏） | | `actionProps` | `ButtonProps` | - | 操作按钮 props | | `isLoading` | `boolean` | `false` | 使用加载指示替代指示器 | | `timeout` | `number` | `4000` | 自动消失超时（毫秒）。默认 4000ms（4 秒）。设为 `0` 表示持久 Toast，不自动消失 | | `onClose` | `() => void` | - | Toast 被关闭时触发（此时退出动画开始播放） | #### toast.promise Options | Option | 类型 | 默认值 | 描述 | | --------- | -------------------------------------------- | --- | ---------------------- | | `loading` | `ReactNode` | - | Promise pending 时显示的消息 | | `success` | `ReactNode \| ((data: T) => ReactNode)` | - | 成功时显示的消息（可为函数） | | `error` | `ReactNode \| ((error: Error) => ReactNode)` | - | 失败时显示的消息（可为函数） | ## 无障碍 每个 Toast 实现 [WAI-ARIA AlertDialog 模式](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/)，并分组渲染在带标签的地标区域中： * **地标区域**：Toast 渲染在可通过 `F6` 到达的带标签地标区域中；`Alt` + `T` 可将焦点直接移入。快捷键可通过 `hotkey` prop 配置，传空数组可禁用；区域标签可通过 `aria-label` 覆盖 * **键盘**：`Tab` 可到达可见 Toast 的控件，`Escape` 折叠展开的堆叠；关闭聚焦的 Toast 时焦点会移至最近的剩余 Toast * **屏幕阅读器**：每个 Toast 使用 `role="alertdialog"` 并关联标题与描述；新 Toast 会自动播报 * **计时器**：悬停或聚焦堆叠时、以及页面处于后台标签页时，自动关闭计时会暂停 ## 相关组件 ## Related Components * **Button**: Allows a user to perform an action * **Alert**: Display important messages and notifications * **CloseButton**: Button for dismissing overlays </page> <page url="/cn/docs/react/components/tooltip"> # Tooltip 工具提示 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/tooltip **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(overlays)/tooltip.mdx > 当用户悬停或聚焦某个元素时，展示提示性文本。 ## 用法 ```tsx import { Tooltip } from '@heroui/react'; ``` ```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">悬停查看</Button> <Tooltip.Content> <p>这是一个工具提示</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Button isIconOnly aria-label="更多信息" variant="tertiary"> <CircleInfo /> </Button> <Tooltip.Content> <p>更多信息</p> </Tooltip.Content> </Tooltip> </div> ); } ``` ## 组件结构 ```tsx import { Tooltip, Button } from '@heroui/react'; export default () => ( <Tooltip> <Tooltip.Trigger> <Button>Hover for tooltip</Button> </Tooltip.Trigger> <Tooltip.Content> <Tooltip.Arrow /> 关于此元素的有用信息 </Tooltip.Content> </Tooltip> ) ``` ## 示例 ### 位置 ```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>顶部位置</p> </Tooltip.Content> </Tooltip> <div /> <Tooltip delay={0}> <Button className="w-full" variant="tertiary"> Left </Button> <Tooltip.Content showArrow placement="left"> <Tooltip.Arrow /> <p>左侧位置</p> </Tooltip.Content> </Tooltip> <div className="flex items-center justify-center"> <span className="text-sm text-muted">悬停按钮</span> </div> <Tooltip delay={0}> <Button className="w-full" variant="tertiary"> Right </Button> <Tooltip.Content showArrow placement="right"> <Tooltip.Arrow /> <p>右侧位置</p> </Tooltip.Content> </Tooltip> <div /> <Tooltip delay={0}> <Button className="w-full" variant="tertiary"> Bottom </Button> <Tooltip.Content showArrow placement="bottom"> <Tooltip.Arrow /> <p>底部位置</p> </Tooltip.Content> </Tooltip> <div /> </div> ); } ``` ### 带箭头 ```tsx import {Button, Tooltip} from "@heroui/react"; export function TooltipWithArrow() { return ( <div className="flex items-center gap-4"> <Tooltip delay={0}> <Button variant="secondary">带箭头</Button> <Tooltip.Content showArrow> <Tooltip.Arrow /> <p>带箭头指示器的工具提示</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Button variant="primary">自定义偏移</Button> <Tooltip.Content showArrow offset={12}> <Tooltip.Arrow /> <p>与触发器的自定义偏移</p> </Tooltip.Content> </Tooltip> </div> ); } ``` ### 自定义触发 ```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="用户头像"> <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="状态标签"> <Chip color="success"> <CircleCheckFill width={12} /> <Chip.Label>活跃</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 当前在线</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Tooltip.Trigger aria-label="信息图标"> <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">帮助信息</p> <p className="text-sm text-muted">这是包含有关此功能更详细信息的实用工具提示。</p> </div> </Tooltip.Content> </Tooltip> </div> ); } ``` ### 渲染函数 ```tsx "use client"; import {CircleInfo} from "@gravity-ui/icons"; import {Button, Tooltip} from "@heroui/react"; export function RenderFunction() { return ( <div className="flex items-center gap-4"> <Tooltip delay={0}> <Button variant="secondary">悬停查看</Button> <Tooltip.Content render={(props) => <div {...props} data-custom="foo" />}> <p>这是一个工具提示</p> </Tooltip.Content> </Tooltip> <Tooltip delay={0}> <Button isIconOnly aria-label="更多信息" variant="tertiary"> <CircleInfo /> </Button> <Tooltip.Content render={(props) => <div {...props} data-custom="foo" />}> <p>更多信息</p> </Tooltip.Content> </Tooltip> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Button, Tooltip} from "@heroui/react"; export function CustomStyles() { return ( <Tooltip delay={0}> <Button variant="secondary">分享链接</Button> <Tooltip.Content className="rounded-lg border border-border/80 bg-surface px-2.5 py-1 text-xs text-foreground shadow-sm"> <p>已复制到剪贴板</p> </Tooltip.Content> </Tooltip> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### 全局延迟配置 你可以通过定义 CSS 变量，为应用中所有 Tooltip 设置默认的显示与隐藏延迟： ```css /* 在你的全局 CSS 文件中 */ :root { --tooltip-delay: 1500ms; --tooltip-close-delay: 500ms; } /* 也可以为浅色/深色主题设置不同的值 */ .light, [data-theme="light"] { --tooltip-delay: 1200ms; } .dark, [data-theme="dark"] { --tooltip-close-delay: 300ms; } ``` 值支持 `ms`、`s` 等 CSS 时间单位。在单个 Tooltip 上指定 `delay` 或 `closeDelay` 时，会覆盖这些全局设置。 ### CSS 类 Tooltip 使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/tooltip.css)）： #### 基础类 \[!toc] * `.tooltip` - 带动画的基础 Tooltip 样式 * `.tooltip__trigger` - 触发元素样式 ### 交互状态 组件支持以下动画相关状态： * **进入**：`[data-entering]` — Tooltip 出现过程中应用 * **离开**：`[data-exiting]` — Tooltip 消失过程中应用 * **位置**：`[data-placement="*"]` — 根据 Tooltip 位置应用 ## API 参考 ### Tooltip | Prop | 类型 | 默认值 | 描述 | | --------------------- | -------------------- | --------------- | ---------------------------------------------------------- | | `children` | `React.ReactNode` | - | 触发元素与内容 | | `delay` | `number` | `1500` 或 CSS 变量 | 显示 Tooltip 前的延迟（毫秒）；可通过 `--tooltip-delay` CSS 变量全局配置 | | `closeDelay` | `number` | `500` 或 CSS 变量 | 隐藏 Tooltip 前的延迟（毫秒）；可通过 `--tooltip-close-delay` CSS 变量全局配置 | | `trigger` | `"hover" \| "focus"` | `"hover"` | Tooltip 的触发方式 | | `isDisabled` | `boolean` | `false` | 是否禁用 Tooltip | | `shouldSkipAnimation` | `boolean` | `false` | 在多个 Tooltip 之间快速切换时，是否跳过进入与退出动画 | ### Tooltip.Content | Prop | 类型 | 默认值 | 描述 | | ----------- | -------------------------------------------------------------------------- | ------------ | ---------------------- | | `children` | `React.ReactNode` | - | 在 Tooltip 中展示的内容 | | `showArrow` | `boolean` | `false` | 是否显示箭头指示器 | | `offset` | `number` | `3`（带箭头时为 7） | 与触发元素的距离 | | `placement` | `"top" \| "bottom" \| "left" \| "right"` (及变体) | `"top"` | Tooltip 的位置 | | `className` | `string` | - | 额外的 CSS 类名 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, TooltipRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 | ### Tooltip.Trigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | -------------- | | `children` | `React.ReactNode` | - | 触发 Tooltip 的元素 | | `className` | `string` | - | 额外的 CSS 类名 | ### Tooltip.Arrow | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------- | --- | ---------------------- | | `children` | `React.ReactNode` | - | 自定义箭头元素 | | `className` | `string` | - | 额外的 CSS 类名 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, OverlayArrowRenderProps>` | - | 通过自定义渲染函数覆盖默认的 DOM 元素。 | ## 相关组件 ## Related Components * **Button**: Allows a user to perform an action * **Popover**: Displays content in context with a trigger </page> <page url="/cn/docs/react/components/autocomplete"> # Autocomplete 自动完成 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/autocomplete **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(pickers)/autocomplete.mdx > 结合选择与过滤，让用户从选项列表中搜索并选择 ## 用法 ```tsx import { Autocomplete, useFilter } from "@heroui/react"; ``` ```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="选择州/省" selectionMode="multiple" value={selectedKeys} onChange={(keys: Key | Key[] | null) => setSelectedKeys(keys as Key[])} > <Label>计划前往的州</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 aria-label="搜索选项" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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> ); } ``` ## 组件结构 ```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> ); ``` ## 示例 ### 变体 Autocomplete 组件支持两种视觉变体： * **`primary`**（默认）- 标准样式带阴影，适用于大多数场景 * **`secondary`** - 低强调变体无阴影，适用于 Surface 组件内 ```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: "选项 1"}, {id: "option2", name: "选项 2"}, {id: "option3", name: "选项 3"}, {id: "option4", name: "选项 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">单选变体</h3> <div className="flex flex-col gap-4"> <Autocomplete className="w-[256px]" placeholder="请选择一项" selectionMode="single" value={selectedKey1} variant="primary" onChange={setSelectedKey1} > <Label>主色（primary）变体</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索选项" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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="请选择一项" selectionMode="single" value={selectedKey2} variant="secondary" onChange={setSelectedKey2} > <Label>次色（secondary）变体</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索选项" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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">多选变体</h3> <div className="flex flex-col gap-4"> <Autocomplete className="w-[256px]" placeholder="选择多项" selectionMode="multiple" value={selectedKeys1} variant="primary" onChange={(keys) => setSelectedKeys1(keys as Key[])} > <Label>主色（primary）变体</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 aria-label="搜索选项" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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="选择多项" selectionMode="multiple" value={selectedKeys2} variant="secondary" onChange={(keys) => setSelectedKeys2(keys as Key[])} > <Label>次色（secondary）变体</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 aria-label="搜索选项" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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> ); } ``` ### 宽度充满 ```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="请选择一项" selectionMode="single" value={selectedKey} variant="secondary" onChange={setSelectedKey} > <Label>州</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索州名" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索州名…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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> ); } ``` ### 带描述 ```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="请选择一项" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>州</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索州名" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索州名…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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>请选择你的居住州</Description> </Autocomplete> ); } ``` ### 必填 ```tsx "use client"; import { Autocomplete, Button, EmptyState, FieldError, Form, Label, ListBox, SearchField, useFilter, } from "@heroui/react"; export function Required() { const onSubmit = (e: React.SyntheticEvent<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("表单提交成功！"); }; 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="请选择一项" selectionMode="single" > <Label>州</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索州名" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索州名…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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="选择一个国家" selectionMode="single" > <Label>国家</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索国家" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索国家…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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">提交</Button> </Form> ); } ``` ### 禁用 ```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="请选择一项" selectionMode="single" > <Label>州</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索州名" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索州名…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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="选择国家" selectionMode="multiple" > <Label>计划前往的国家</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索国家" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索国家…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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> ); } ``` ### 含禁用选项 ```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="选择一种动物" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>动物</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索动物" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索动物…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="bird" textValue="鸟"> 鸟 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="elephant" textValue="象"> 象 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="tiger" textValue="老虎"> 老虎 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### 允许空选项 `allowsEmptyCollection` 属性允许集合为空时仍可使用自动完成，适用于列表初始为空或全部被过滤掉的场景。 ```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="请选择一项" selectionMode="single" > <Label>州</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索州名" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索州名…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>} /> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### 分组选项 ```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="选择一个国家" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>国家</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索国家" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索国家…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}> <ListBox.Section> <Header>北美洲</Header> <ListBox.Item id="usa" textValue="美国"> 美国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="canada" textValue="加拿大"> 加拿大 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="mexico" textValue="墨西哥"> 墨西哥 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>欧洲</Header> <ListBox.Item id="uk" textValue="英国"> 英国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="法国"> 法国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="germany" textValue="德国"> 德国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="spain" textValue="西班牙"> 西班牙 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="italy" textValue="意大利"> 意大利 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>亚洲</Header> <ListBox.Item id="japan" textValue="日本"> 日本 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="china" textValue="中国"> 中国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="india" textValue="印度"> 印度 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="south-korea" textValue="韩国"> 韩国 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### 多选 ```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="选择州/省" selectionMode="multiple" value={selectedKeys} onChange={(keys) => setSelectedKeys(keys as Key[])} > <Label>州</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 aria-label="搜索选项" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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> ); } ``` <Callout type="warning"> 在多选模式下，直接使用 `<Autocomplete.Value />` 会将每个选中项在 `ListBox.Item` 中的 children 复制到触发器中，并以符合当前语言环境的分隔符连接。仅包含文本的选项会显示为纯文本，但复选框、头像等可见内容会随每个选中项各出现一次；函数形式的 children 也始终以 `isSelected: false` 调用。 </Callout> 如需以纯文本显示选中值，请使用 `selectedText` 渲染属性，它会将每个选中项的 `textValue` 连接为一个字符串： ```tsx <Autocomplete.Value> {({isPlaceholder, defaultChildren, selectedText}) => isPlaceholder ? defaultChildren : selectedText } </Autocomplete.Value> ``` 如需可移除标签等更丰富的布局，请参考上方示例，基于 `state.selectedItems` 自行渲染内容。 ### 受控组件 ```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="选择一个州" selectionMode="single" value={state} onChange={setState} > <Label>州（受控）</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索州名" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索州名…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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">已选：{selectedState?.name || "无"}</p> </div> ); } ``` ### 受控多选 ```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 ControlledMultiple() { const [selected, setSelected] = useState<Key[]>(["california", "texas"]); 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"}, ]; return ( <div className="space-y-2"> <Autocomplete className="w-[256px]" placeholder="选择州" selectionMode="multiple" value={selected} onChange={(keys) => setSelected(keys as Key[])} > <Label>州</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索州名" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索州名…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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> <p className="text-sm text-muted">已选：{selected.length > 0 ? selected.join(", ") : "无"}</p> </div> ); } ``` ### 受控展开状态 ```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="请选择一项" selectionMode="single" onOpenChange={setIsOpen} > <Label>州</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索州名" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索州名…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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 ? "关闭" : "打开"} 自动完成</Button> <p className="text-sm text-muted">自动完成处于{isOpen ? "打开" : "关闭"}状态</p> </div> ); } ``` ### 异步搜索 ```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 allowsEmptyCollection className="w-[256px]" placeholder="搜索…" selectionMode="single" > <Label>搜索《星球大战》角色</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter inputValue={list.filterText} onInputChange={list.setFilterText}> <SearchField autoFocus aria-label="搜索角色" className="sticky top-0 z-10" name="search" variant="secondary" > <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索角色…" /> <Spinner size="sm" className={cn("absolute end-2 top-1/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>未找到结果</EmptyState>} > {(item: Character) => ( <ListBox.Item id={item.name} textValue={item.name}> {item.name} <ListBox.ItemIndicator /> </ListBox.Item> )} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### 自定义指示器 ```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="请选择一项" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>州</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 aria-label="搜索州名" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索州名…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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> ); } ``` ### 自定义展示值 可使用 render props 自定义显示值： ```tsx "use client"; import { Autocomplete, Description, EmptyState, Label, ListBox, SearchField, useFilter, } from "@heroui/react"; export function CustomValue() { const {contains} = useFilter({sensitivity: "base"}); const currencies = [ {code: "USD", id: "usd", name: "美元", symbol: "$"}, {code: "EUR", id: "eur", name: "欧元", symbol: "€"}, {code: "GBP", id: "gbp", name: "英镑", symbol: "£"}, {code: "JPY", id: "jpy", name: "日元", symbol: "¥"}, {code: "CHF", id: "chf", name: "瑞士法郎", symbol: "₣"}, ]; return ( <Autocomplete className="w-[256px]" defaultValue="usd" placeholder="选择货币" selectionMode="single" > <Label>货币</Label> <Autocomplete.Trigger> <Autocomplete.Value> {({defaultChildren, isPlaceholder, state}) => { const selectedCurrency = currencies.find( (currency) => currency.id === state.selectedItems[0]?.key, ); if (isPlaceholder || !selectedCurrency) { return defaultChildren; } return ( <span className="flex min-w-0 items-center gap-1.5"> <span className="font-medium">{selectedCurrency.symbol}</span> <span>{selectedCurrency.code}</span> <span className="truncate text-muted">{selectedCurrency.name}</span> </span> ); }} </Autocomplete.Value> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索货币" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索货币…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</EmptyState>}> {currencies.map((currency) => ( <ListBox.Item key={currency.id} id={currency.id} textValue={`${currency.code} ${currency.name}`} > <div className="flex flex-col"> <Label>{currency.code}</Label> <Description>{currency.name}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 组件内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。 ```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 OnSurface() { 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-[320px] rounded-3xl p-6"> <Autocomplete className="w-full" placeholder="选择一个" selectionMode="single" value={selectedKey} variant="secondary" onChange={setSelectedKey} > <Label>州</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="搜索州名" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索州名…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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> ); } ``` ### 虚拟滚动 Autocomplete 通过 [Virtualizer](https://react-aria.adobe.com/Virtualizer) 支持虚拟化，仅渲染视口内可见行以高效处理大数据集。 ```tsx "use client"; import type {Key} from "@heroui/react"; import { Autocomplete, Description, EmptyState, Label, ListBox, ListLayout, SearchField, Virtualizer, useFilter, } from "@heroui/react"; import {useMemo, useState} from "react"; interface User { email: string; id: number; name: string; } function generateUsers(n: number): User[] { const firstNames = [ "Emma", "Liam", "Olivia", "Noah", "Ava", "James", "Sophia", "Oliver", "Isabella", "Lucas", "Mia", "Ethan", "Charlotte", "Mason", "Amelia", "Logan", "Harper", "Alexander", "Ella", "Benjamin", ]; const lastNames = [ "Smith", "Johnson", "Williams", "Brown", "Jones", "Garcia", "Miller", "Davis", "Rodriguez", "Martinez", "Anderson", "Taylor", "Thomas", "Jackson", "White", "Harris", "Clark", "Lewis", "Robinson", "Walker", ]; const users: User[] = []; for (let i = 0; i < n; i++) { const firstName = firstNames[i % firstNames.length]!; const lastName = lastNames[Math.floor(i / firstNames.length) % lastNames.length]!; const name = `${firstName} ${lastName}`; users.push({ email: `${firstName.toLowerCase()}.${lastName.toLowerCase()}@acme.com`, id: i + 1, name, }); } return users; } export function Virtualization() { const [selectedKey, setSelectedKey] = useState<Key | null>(null); const [searchQuery, setSearchQuery] = useState(""); const {contains} = useFilter({sensitivity: "base"}); const allUsers = useMemo(() => generateUsers(1000), []); const filteredUsers = useMemo(() => { if (!searchQuery) return allUsers; return allUsers.filter( (user) => contains(user.name, searchQuery) || contains(user.email, searchQuery), ); }, [allUsers, contains, searchQuery]); return ( <Autocomplete allowsEmptyCollection className="w-[300px]" placeholder="选择用户" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>用户</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter inputValue={searchQuery} onInputChange={setSearchQuery}> <SearchField autoFocus aria-label="搜索用户" className="sticky top-0 z-10" name="search" variant="secondary" > <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索用户…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <Virtualizer layout={ListLayout} layoutOptions={{rowHeight: 50}}> <ListBox items={filteredUsers} renderEmptyState={() => <EmptyState>未找到结果</EmptyState>} > {(user) => ( <ListBox.Item id={user.id} textValue={user.name}> <div className="flex flex-col"> <Label>{user.name}</Label> <Description>{user.email}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> )} </ListBox> </Virtualizer> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ## 高级示例 ### 用户选择 ```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="选择用户" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>用户</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} 位用户`; } 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 aria-label="搜索用户" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索用户…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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> ); } ``` ### 用户多选 ```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="选择队友" selectionMode="multiple" value={selectedKeys} onChange={(keys) => setSelectedKeys(keys as Key[])} > <Label>用户</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 aria-label="搜索用户" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索用户…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到结果</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> ); } ``` ### 地点搜索 ```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: "美国", name: "纽约"}, {country: "美国", name: "洛杉矶"}, {country: "美国", name: "芝加哥"}, {country: "英国", name: "伦敦"}, {country: "法国", name: "巴黎"}, {country: "日本", name: "东京"}, {country: "澳大利亚", name: "悉尼"}, {country: "加拿大", name: "多伦多"}, {country: "德国", name: "柏林"}, {country: "西班牙", name: "马德里"}, ]; 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="搜索城市" selectionMode="single" value={selectedKey} onChange={setSelectedKey} > <Label>城市</Label> <Autocomplete.Trigger> <Autocomplete.Value /> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover> <Autocomplete.Filter filter={customFilter}> <SearchField autoFocus aria-label="搜索城市" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索城市…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>{isLoading ? "搜索中…" : "未找到城市"}</EmptyState>} > {allCities.map((city) => ( <ListBox.Item key={city.name} id={city.name} textValue={`${city.name} ${city.country}`} > <div className="flex flex-col"> <Label>{city.name}</Label> <Description>{city.country}</Description> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> ); } ``` ### 标签组选择 ```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="选择标签" selectionMode="multiple" value={selectedKeys} onChange={(keys) => setSelectedKeys(keys as Key[])} > <Label>标签</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 aria-label="搜索标签" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索标签…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到标签</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> ); } ``` ### 邮件收件人 ```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="添加收件人" selectionMode="multiple" value={selectedKeys} onChange={(keys) => setSelectedKeys(keys as Key[])} > <Label>收件人</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 aria-label="搜索邮箱" name="search" variant="secondary"> <SearchField.Group> <SearchField.SearchIcon /> <SearchField.Input placeholder="搜索邮箱…" /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox renderEmptyState={() => <EmptyState>未找到收件人</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> ); } ``` ## 自定义样式 ### Tailwind CSS ```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"; const TEAMMATES = [ {id: "sarah", name: "Sarah Chen", role: "产品设计"}, {id: "marcus", name: "Marcus Lee", role: "工程"}, {id: "priya", name: "Priya Patel", role: "数据科学"}, {id: "jordan", name: "Jordan Kim", role: "客户成功"}, {id: "alex", name: "Alex Rivera", role: "市场营销"}, ] as const; export function CustomStyles() { const {contains} = useFilter({sensitivity: "base"}); const [selectedKeys, setSelectedKeys] = useState<Key[]>([]); const onRemoveTags = (keys: Set<Key>) => { setSelectedKeys((prev) => prev.filter((key) => !keys.has(key))); }; return ( <div className="w-full max-w-sm pt-6"> <Autocomplete className="w-full gap-1.5" placeholder="搜索团队成员..." selectionMode="multiple" value={selectedKeys} onChange={(keys) => setSelectedKeys((keys ?? []) as Key[])} > <Label className="font-medium text-foreground">负责人</Label> <Description>任务更新时将通知以下人员。</Description> <Autocomplete.Trigger className="rounded-xl border border-border/80 bg-surface shadow-sm ring-1 ring-accent/5 transition-[box-shadow,border-color] focus-within:border-accent/25 focus-within:ring-2 focus-within:ring-accent/15 dark:border-border/90 dark:bg-surface dark:ring-accent/10 dark:focus-within:border-accent/35"> <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 teammate = TEAMMATES.find((member) => member.id === selectedItemKey); if (!teammate) return null; return ( <Tag key={teammate.id} className="border border-accent/15 bg-accent/8 text-foreground dark:border-accent/25 dark:bg-accent/12" id={teammate.id} > {teammate.name} </Tag> ); })} </TagGroup.List> </TagGroup> ); }} </Autocomplete.Value> <Autocomplete.ClearButton /> <Autocomplete.Indicator /> </Autocomplete.Trigger> <Autocomplete.Popover className="overflow-hidden rounded-xl border border-border/80 bg-surface shadow-xl ring-1 ring-black/3 dark:border-border/90 dark:bg-surface dark:ring-white/5"> <Autocomplete.Filter filter={contains}> <SearchField autoFocus aria-label="按姓名或角色搜索" name="search" variant="secondary"> <SearchField.Group className="border-b border-separator bg-surface-secondary/50"> <SearchField.SearchIcon className="text-muted" /> <SearchField.Input placeholder="按姓名或角色搜索..." /> <SearchField.ClearButton /> </SearchField.Group> </SearchField> <ListBox className="p-1.5" renderEmptyState={() => <EmptyState>未找到团队成员</EmptyState>} > {TEAMMATES.map((teammate) => ( <ListBox.Item key={teammate.id} className="rounded-lg data-[focused=true]:bg-accent/10 data-[selected=true]:bg-accent/5 dark:data-[focused=true]:bg-accent/15 dark:data-[selected=true]:bg-accent/8" id={teammate.id} textValue={`${teammate.name} ${teammate.role}`} > <div className="flex flex-col gap-0.5"> <span className="text-sm font-medium text-foreground">{teammate.name}</span> <span className="text-xs text-muted">{teammate.role}</span> </div> <ListBox.ItemIndicator /> </ListBox.Item> ))} </ListBox> </Autocomplete.Filter> </Autocomplete.Popover> </Autocomplete> </div> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Autocomplete 组件类。 [了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Autocomplete 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/autocomplete.css)）： #### 基础类 \[!toc] * `.autocomplete` - 自动完成根容器 * `.autocomplete__trigger` - 触发自动完成的按钮 * `.autocomplete__value` - 显示的值或占位符 * `.autocomplete__clear-button` - 清除已选值的按钮 * `.autocomplete__indicator` - 下拉指示图标 * `.autocomplete__popover` - 弹出层容器 * `.autocomplete__filter` - 过滤包装器 #### 变体类 \[!toc] * `.autocomplete--primary` - 带阴影的主变体（默认） * `.autocomplete--secondary` - 无阴影的次变体，适用于 Surface 内 #### 状态类 \[!toc] * `.autocomplete[data-invalid="true"]` - 无效状态 * `.autocomplete__trigger[data-focus-visible="true"]` - 触发器聚焦状态 * `.autocomplete__trigger[data-disabled="true"]` - 触发器禁用状态 * `.autocomplete__value[data-placeholder="true"]` - 占位符状态 * `.autocomplete__clear-button[data-empty="true"]` - 无选择时隐藏清除按钮 * `.autocomplete__indicator[data-open="true"]` - 打开时的指示器状态 ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Hover**：触发器上的 `:hover` 或 `[data-hovered="true"]` * **Focus**：触发器上的 `:focus-visible` 或 `[data-focus-visible="true"]` * **Disabled**：Autocomplete 上的 `:disabled` 或 `[data-disabled="true"]` * **Open**：指示器上的 `[data-open="true"]` ## API 参考 ### Autocomplete | Prop | 类型 | 默认值 | 描述 | | ----------------------- | --------------------------------------- | ------------------ | --------------------------------------------------------- | | `placeholder` | `string` | `'Select an item'` | 为空时显示的占位文本 | | `selectionMode` | `"single" \| "multiple"` | `"single"` | 启用单选或多选 | | `allowsEmptyCollection` | `boolean` | `false` | 是否允许空集合；为 true 时无选项也可使用 | | `isOpen` | `boolean` | - | 弹出层打开状态（受控） | | `defaultOpen` | `boolean` | - | 弹出层默认打开状态（非受控） | | `onOpenChange` | `(isOpen: boolean) => void` | - | 打开状态变化时的回调 | | `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key | | `isDisabled` | `boolean` | - | 是否禁用 | | `value` | `Key \| Key[] \| null` | - | 当前值（受控） | | `defaultValue` | `Key \| Key[] \| null` | - | 默认值（非受控） | | `onChange` | `(value: Key \| Key[] \| null) => void` | - | 值变化时的回调 | | `isRequired` | `boolean` | - | 是否必填 | | `isInvalid` | `boolean` | - | 值是否无效 | | `name` | `string` | - | 提交 HTML 表单时使用的名称 | | `fullWidth` | `boolean` | `false` | 是否占满容器宽度 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode \| RenderFunction` | - | 内容或 render 函数 | ### Autocomplete.Trigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------- | --- | ---------------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode \| RenderFunction` | - | 触发器内容或 render 函数 | ### Autocomplete.Value | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------- | --- | -------------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode \| RenderFunction` | - | 值内容或 render 函数 | ### Autocomplete.Indicator | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | -------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode` | - | 自定义指示器内容 | ### Autocomplete.ClearButton | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------ | --- | ----------- | | `className` | `string` | - | 附加 CSS 类 | | `onClick` | `(e: MouseEvent) => void` | - | 点击按钮时的回调 | | `ref` | `RefObject<HTMLButtonElement>` | - | 清除按钮元素的 ref | ### Autocomplete.Popover | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ----------- | | `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"` | 弹出层相对触发器的位置 | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode` | - | 子内容 | ### Autocomplete.Filter | Prop | 类型 | 默认值 | 描述 | | --------------- | ------------------------------------------ | --- | --------------------------- | | `filter` | `(text: string, input: string) => boolean` | - | 自定义过滤函数 | | `inputValue` | `string` | - | 受控输入值 | | `onInputChange` | `(value: string) => void` | - | 输入值变化时的回调 | | `children` | `ReactNode` | - | 过滤内容（SearchField 与 ListBox） | ### useFilter Hook React Aria 的 `useFilter` hook 提供自动完成过滤函数。 ```tsx import {useFilter} from "@heroui/react"; const {contains} = useFilter({sensitivity: "base"}); <Autocomplete.Filter filter={contains}> <SearchField>...</SearchField> <ListBox>...</ListBox> </Autocomplete.Filter> ``` **Options:** | Option | 类型 | 默认值 | 描述 | | ------------- | ------------------------------------------- | -------- | -------------- | | `sensitivity` | `"base" \| "accent" \| "case" \| "variant"` | `"base"` | 匹配的 locale 敏感度 | **Returns:** | Function | 类型 | 描述 | | ------------ | ------------------------------------------------ | ------------ | | `contains` | `(string: string, substring: string) => boolean` | 判断字符串是否包含子串 | | `startsWith` | `(string: string, substring: string) => boolean` | 判断字符串是否以子串开头 | | `endsWith` | `(string: string, substring: string) => boolean` | 判断字符串是否以子串结尾 | ### Render Props 使用 Autocomplete.Value 的 render 函数时，提供以下值： | Prop | 类型 | 描述 | | ----------------- | --------------- | ----------------------------------------------- | | `defaultChildren` | `ReactNode` | 默认渲染的值。多选模式下为每个选中项 children 的副本，以符合当前语言环境的分隔符连接 | | `isPlaceholder` | `boolean` | 是否为占位符 | | `state` | `SelectState` | 自动完成的状态。如需获取选中的集合节点，请使用 `state.selectedItems` | | `selectedItems` | `(T \| null)[]` | 当前选中项的值 | | `selectedText` | `string` | 选中项的 `textValue`，以符合当前语言环境的分隔符连接 | ## 无障碍 Autocomplete 组件实现带过滤的 ARIA select 模式，提供： * 完整键盘导航支持 * 选择变化的屏幕阅读器播报 * 正确的焦点管理 * 禁用状态支持 * 带过滤的搜索功能 * HTML 表单集成 更多信息请参阅 [React Aria Select 文档](https://react-spectrum.adobe.com/react-aria/Select.html)。 ## 相关组件 ## 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 </page> <page url="/cn/docs/react/components/combo-box"> # ComboBox 组合框 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/combo-box **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(pickers)/combo-box.mdx > 将文本输入与 ListBox 结合，用户可通过输入查询把选项列表过滤为匹配项 ## 用法 ```tsx import { ComboBox } from '@heroui/react'; ``` ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function Default() { return ( <ComboBox className="w-[256px]"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ## 组件结构 ```tsx import { ComboBox, Input, Label, Description, Header, ListBox, Separator } from '@heroui/react'; export default () => ( <ComboBox> <Label /> <ComboBox.InputGroup> <Input /> <ComboBox.Trigger /> </ComboBox.InputGroup> {/* 展示已选中的值，主要用于多选 */} <ComboBox.Value /> <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> ) ``` ## 示例 ### 宽度充满 ```tsx import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <ComboBox fullWidth> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> </div> ); } ``` ### 带描述 ```tsx "use client"; import {ComboBox, Description, Input, Label, ListBox} from "@heroui/react"; export function WithDescription() { return ( <ComboBox className="w-[256px]"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>搜索并选择你最喜欢的动物</Description> </ComboBox> ); } ``` ### 必填 ```tsx "use client"; import {Button, ComboBox, FieldError, Form, Input, Label, ListBox} from "@heroui/react"; export function Required() { const onSubmit = (e: React.SyntheticEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record<string, string> = {}; formData.forEach((value, key) => { data[key] = value.toString(); }); alert("表单提交成功！"); }; return ( <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}> <ComboBox isRequired className="w-full" name="animal"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <FieldError /> </ComboBox> <Button type="submit">提交</Button> </Form> ); } ``` ### 禁用 ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function Disabled() { return ( <ComboBox isDisabled className="w-[256px]" defaultSelectedKey="cat"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### 含禁用选项 ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function WithDisabledOptions() { return ( <ComboBox className="w-[256px]" disabledKeys={["cat", "kangaroo"]}> <Label>动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="bird" textValue="鸟"> 鸟 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="elephant" textValue="象"> 象 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="tiger" textValue="老虎"> 老虎 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### 分组选项 ```tsx "use client"; import {ComboBox, Header, Input, Label, ListBox, Separator} from "@heroui/react"; export function WithSections() { return ( <ComboBox className="w-[256px]"> <Label>国家</Label> <ComboBox.InputGroup> <Input placeholder="搜索国家…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Section> <Header>北美洲</Header> <ListBox.Item id="usa" textValue="美国"> 美国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="canada" textValue="加拿大"> 加拿大 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="mexico" textValue="墨西哥"> 墨西哥 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>欧洲</Header> <ListBox.Item id="uk" textValue="英国"> 英国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="法国"> 法国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="germany" textValue="德国"> 德国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="spain" textValue="西班牙"> 西班牙 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="italy" textValue="意大利"> 意大利 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>亚洲</Header> <ListBox.Item id="japan" textValue="日本"> 日本 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="china" textValue="中国"> 中国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="india" textValue="印度"> 印度 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="south-korea" textValue="韩国"> 韩国 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### 受控组件 ```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: "猫", }, { id: "dog", name: "狗", }, { id: "bird", name: "鸟", }, { id: "fish", name: "鱼", }, { id: "hamster", name: "仓鼠", }, ]; 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>动物（受控）</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <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">已选：{selectedAnimal?.name || "无"}</p> </div> ); } ``` ### 受控输入值 ```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>搜索（受控输入）</Label> <ComboBox.InputGroup> <Input placeholder="输入以搜索…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> <p className="text-sm text-muted">输入值：{inputValue || "（空）"}</p> </div> ); } ``` ### 异步加载 ```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>选择角色</Label> <ComboBox.InputGroup> <Input placeholder="星球大战角色…" /> <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">加载更多…</span> </div> </ListBoxLoadMoreItem> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### 默认选中项 ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function DefaultSelectedKey() { return ( <ComboBox className="w-[256px]" defaultSelectedKey="cat"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### 允许自定义值 ```tsx "use client"; import {ComboBox, Description, Input, Label, ListBox} from "@heroui/react"; export function AllowsCustomValue() { return ( <ComboBox allowsCustomValue className="w-[256px]"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索或输入动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>可输入任意动物名称，即使不在列表中</Description> </ComboBox> ); } ``` ### 自定义指示器 ```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>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger> <ChevronsExpandVertical className="size-3" /> </ComboBox.Trigger> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### 自定义展示值 ```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>用户</Label> <ComboBox.InputGroup> <Input placeholder="搜索用户…" /> <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> ); } ``` ### 自定义过滤 ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function CustomFiltering() { const animals = [ {id: "cat", name: "猫"}, {id: "dog", name: "狗"}, {id: "bird", name: "鸟"}, {id: "fish", name: "鱼"}, {id: "hamster", name: "仓鼠"}, ]; return ( <ComboBox className="w-[256px]" defaultFilter={(text, inputValue) => { if (!inputValue) return true; return text.toLowerCase().includes(inputValue.toLowerCase()); }} > <Label>动物（自定义筛选）</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <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> ); } ``` ### 渲染函数 ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function RenderFunction() { return ( <ComboBox className="w-[256px]" render={(props) => <div {...props} data-custom="foo" />}> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### 菜单触发方式 使用 `menuTrigger` prop 控制 Popover 何时打开： * `focus`（默认）：输入框获得焦点时打开 Popover * `input`：用户编辑输入文本时打开 Popover * `manual`：仅当用户按下触发按钮或使用方向键时打开 Popover ```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">聚焦（默认）</p> <ComboBox className="w-[256px]" menuTrigger="focus"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>输入框获得焦点时打开弹出层</Description> </ComboBox> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">输入</p> <ComboBox className="w-[256px]" menuTrigger="input"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>用户编辑输入文本时打开弹出层</Description> </ComboBox> </div> <div className="flex flex-col gap-2"> <p className="text-sm font-medium text-muted">手动</p> <ComboBox className="w-[256px]" menuTrigger="manual"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <Description>仅在按下触发按钮或使用方向键时打开弹出层</Description> </ComboBox> </div> </div> ); } ``` ### 表单值 使用 `formValue` 控制提交表单时提交选中项的 key 还是文本。默认值为 `key`。当 `allowsCustomValue` 为 true 时，始终提交文本。 ```tsx "use client"; import { Button, ComboBox, Description, FieldError, Form, Input, Label, ListBox, } from "@heroui/react"; import {useState} from "react"; const animals = [ {id: "aardvark", name: "土豚"}, {id: "cat", name: "猫"}, {id: "dog", name: "狗"}, {id: "kangaroo", name: "袋鼠"}, {id: "panda", name: "熊猫"}, {id: "snake", name: "蛇"}, ]; export function FormValue() { const [message, setMessage] = useState<string | null>(null); return ( <Form className="flex w-[256px] flex-col gap-4" onSubmit={(e) => { e.preventDefault(); const formData = new FormData(e.currentTarget); setMessage(`key：${formData.get("animal")}。文本：${formData.get("animal-text")}。`); }} > <ComboBox isRequired className="w-full" formValue="key" name="animal"> <Label>动物</Label> <ComboBox.InputGroup> <Input placeholder="选择动物…" /> <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> <Description>提交选中项的 key</Description> <FieldError /> </ComboBox> <ComboBox isRequired className="w-full" formValue="text" name="animal-text"> <Label>动物（文本）</Label> <ComboBox.InputGroup> <Input placeholder="选择动物…" /> <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> <Description>提交选中项的文本</Description> <FieldError /> </ComboBox> <Button className="w-fit" type="submit"> 提交 </Button> {!!message && <p className="text-sm text-muted">{message}</p>} </Form> ); } ``` ### 校验行为 使用 `validationBehavior` 控制校验信息的展示方式： * `native`（默认）：值为空或无效时阻止表单提交 * `aria`：实时显示错误，不阻止提交 ```tsx "use client"; import { Button, ComboBox, Description, FieldError, Form, Input, Label, ListBox, } from "@heroui/react"; import {useState} from "react"; const animals = [ {id: "aardvark", name: "土豚"}, {id: "cat", name: "猫"}, {id: "dog", name: "狗"}, {id: "kangaroo", name: "袋鼠"}, {id: "panda", name: "熊猫"}, {id: "snake", name: "蛇"}, ]; export function ValidationBehavior() { const [nativeMessage, setNativeMessage] = useState<string | null>(null); const [ariaMessage, setAriaMessage] = useState<string | null>(null); return ( <div className="flex flex-col gap-8"> <Form className="flex w-[256px] flex-col gap-4" onSubmit={(e) => { e.preventDefault(); setNativeMessage("已通过原生校验提交。"); }} > <ComboBox isRequired className="w-full" name="animal" validationBehavior="native"> <Label>动物（原生校验）</Label> <ComboBox.InputGroup> <Input placeholder="选择动物…" /> <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> <Description>值为空时阻止提交</Description> <FieldError /> </ComboBox> <Button className="w-fit" type="submit"> 提交 </Button> {!!nativeMessage && <p className="text-sm text-muted">{nativeMessage}</p>} </Form> <Form className="flex w-[256px] flex-col gap-4" onSubmit={(e) => { e.preventDefault(); setAriaMessage("已通过 ARIA 校验提交。"); }} > <ComboBox isRequired className="w-full" name="animal-aria" validationBehavior="aria"> <Label>动物（ARIA 校验）</Label> <ComboBox.InputGroup> <Input placeholder="选择动物…" /> <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> <Description>实时显示错误，不阻止提交</Description> <FieldError /> </ComboBox> <Button className="w-fit" type="submit"> 提交 </Button> {!!ariaMessage && <p className="text-sm text-muted">{ariaMessage}</p>} </Form> </div> ); } ``` ### 自定义校验 使用 `validate` 在值无效时返回错误信息，有效时返回 `true`。 ```tsx "use client"; import {Button, ComboBox, FieldError, Form, Input, Label, ListBox} from "@heroui/react"; const animals = [ {id: "aardvark", name: "土豚"}, {id: "cat", name: "猫"}, {id: "dog", name: "狗"}, {id: "kangaroo", name: "袋鼠"}, {id: "panda", name: "熊猫"}, {id: "snake", name: "蛇"}, ]; export function CustomValidation() { return ( <Form className="flex w-[256px] flex-col gap-4" onSubmit={(e) => { e.preventDefault(); alert("表单提交成功！"); }} > <ComboBox isRequired className="w-full" name="animal" validate={(value) => { if (value.selectedKey == null) { return "请选择一种动物"; } if (value.selectedKey === "snake") { return "不允许选择蛇"; } return true; }} > <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <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> <FieldError /> </ComboBox> <Button className="w-fit" type="submit"> 提交 </Button> </Form> ); } ``` ### 只读 使用 `isReadOnly` 将 ComboBox 设为只读。选中值可以获得焦点，但不能修改。 ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; const animals = [ {id: "aardvark", name: "土豚"}, {id: "cat", name: "猫"}, {id: "dog", name: "狗"}, {id: "kangaroo", name: "袋鼠"}, {id: "panda", name: "熊猫"}, {id: "snake", name: "蛇"}, ]; export function ReadOnly() { return ( <ComboBox isReadOnly className="w-[256px]" defaultSelectedKey="cat"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <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> ); } ``` ### 多选 设置 `selectionMode="multiple"` 以允许选择多个选项。在多选模式下，使用 `ComboBox.Value` 展示已选项，并同时给内部的 `ListBox` 传入 `selectionMode="multiple"`。选择通过 `value` / `defaultValue`（`Key[]`）以及 `onChange` 回调来控制。 ```tsx "use client"; import {ComboBox, Input, Label, ListBox} from "@heroui/react"; export function MultipleSelection() { return ( <ComboBox className="w-[256px]" selectionMode="multiple"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Value placeholder="未选择任何动物" /> <ComboBox.Popover> <ListBox selectionMode="multiple"> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请使用 `variant="secondary"` 以应用适合 Surface 背景的低强调变体。 ```tsx "use client"; import {Button, ComboBox, FieldError, Form, Input, Label, ListBox, Surface} from "@heroui/react"; export function OnSurface() { const onSubmit = (e: React.SyntheticEvent<HTMLFormElement>) => { e.preventDefault(); const formData = new FormData(e.currentTarget); const data: Record<string, string> = {}; formData.forEach((value, key) => { data[key] = value.toString(); }); alert("表单提交成功！"); }; 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" variant="secondary"> <Label>最喜欢的动物</Label> <ComboBox.InputGroup> <Input placeholder="搜索动物…" /> <ComboBox.Trigger /> </ComboBox.InputGroup> <ComboBox.Popover> <ListBox> <ListBox.Item id="aardvark" textValue="土豚"> 土豚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="panda" textValue="熊猫"> 熊猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="snake" textValue="蛇"> 蛇 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> <FieldError /> </ComboBox> <Button type="submit">提交</Button> </Form> </Surface> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {ComboBox, Input, Label, ListBox} from "@heroui/react"; const itemClass = "rounded-lg data-[focused=true]:bg-muted/70 data-[selected=true]:font-medium data-[selected=true]:text-foreground"; export function CustomStyles() { return ( <ComboBox className="w-64 gap-1.5"> <Label className="font-medium text-neutral-800 dark:text-neutral-100">框架</Label> <ComboBox.InputGroup className="rounded-xl border border-border/80 bg-surface shadow-sm ring-1 ring-black/5 transition-[box-shadow,border-color] focus-within:ring-2 focus-within:ring-neutral-400/25 dark:ring-white/10 dark:focus-within:ring-neutral-500/30"> <Input placeholder="搜索…" /> <ComboBox.Trigger className="text-muted" /> </ComboBox.InputGroup> <ComboBox.Popover className="rounded-xl border border-border/80 bg-surface p-1 shadow-lg ring-1 ring-black/5 dark:ring-white/10"> <ListBox> <ListBox.Item className={itemClass} id="react" textValue="React"> React <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item className={itemClass} id="vue" textValue="Vue"> Vue <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item className={itemClass} id="svelte" textValue="Svelte"> Svelte <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </ComboBox.Popover> </ComboBox> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 ComboBox 组件类。 [了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ComboBox 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/combo-box.css)）： #### 基础类 \[!toc] * `.combo-box` - ComboBox 根容器 * `.combo-box__input-group` - 输入框与触发按钮的容器 * `.combo-box__value` - 已选值的展示区域（用于多选） * `.combo-box__trigger` - 打开 Popover 的按钮 * `.combo-box__popover` - Popover 容器 #### 状态类 \[!toc] * `.combo-box[data-invalid="true"]` - 无效状态 * `.combo-box[data-disabled="true"]` - 禁用状态 * `.combo-box__trigger[data-focus-visible="true"]` - 触发器聚焦 * `.combo-box__trigger[data-disabled="true"]` - 触发器禁用 * `.combo-box__trigger[data-open="true"]` - 展开状态 ### 交互状态 组件同时支持 CSS 伪类与 data 属性： * **Hover**：触发器上 `:hover` 或 `[data-hovered="true"]` * **Focus**：触发器上 `:focus-visible` 或 `[data-focus-visible="true"]` * **Disabled**：ComboBox 上 `:disabled` 或 `[data-disabled="true"]` * **Open**：触发器上 `[data-open="true"]` ## API 参考 ### ComboBox | Prop | 类型 | 默认值 | 描述 | | ----------------------- | ---------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------ | | `inputValue` | `string` | - | 当前输入值（受控） | | `defaultInputValue` | `string` | - | 默认输入值（非受控） | | `onInputChange` | `(value: string) => void` | - | 输入值变化时的回调 | | `selectionMode` | `"single" \| "multiple"` | `"single"` | 启用单选还是多选 | | `selectedKey` | `Key \| null` | - | 当前选中的 key（受控，单选） | | `defaultSelectedKey` | `Key \| null` | - | 默认选中的 key（非受控，单选） | | `onSelectionChange` | `(key: Key \| null) => void` | - | 选中变化时的回调（单选） | | `value` | `Key \| null \| Key[]` | - | 当前选中的 key（受控）。当 `selectionMode="multiple"` 时为 `Key[]` | | `defaultValue` | `Key \| null \| Key[]` | - | 初始选中的 key（非受控）。当 `selectionMode="multiple"` 时为 `Key[]` | | `onChange` | `(value: Key \| null \| Key[]) => void` | - | 选中变化时的回调 | | `items` | `Iterable<T>` | - | 在 ListBox 中展示的 items | | `disabledKeys` | `Iterable<Key>` | - | 禁用项的 key | | `defaultFilter` | `(text: string, inputValue: string) => boolean` | - | 用于过滤 items 的自定义过滤函数 | | `isDisabled` | `boolean` | - | 是否禁用 ComboBox | | `isReadOnly` | `boolean` | - | 输入是否可选中但不可由用户更改 | | `isRequired` | `boolean` | - | 是否必填 | | `isInvalid` | `boolean` | - | ComboBox 的值是否无效 | | `validate` | `(value: ComboBoxValidationValue) => ValidationError \| true \| null \| undefined` | - | 若给定值无效则返回错误信息的函数。当 `validationBehavior="native"` 时，提交表单会向用户展示校验错误；实时校验请改用 `isInvalid` prop | | `validationBehavior` | `"native" \| "aria"` | `"native"` | 使用原生 HTML 表单校验在值缺失或无效时阻止提交，还是通过 ARIA 将字段标记为必填或无效 | | `name` | `string` | - | 提交 HTML 表单时 input 的 name | | `form` | `string` | - | 要关联的 `<form>` 元素 id | | `formValue` | `"text" \| "key"` | `"key"` | 在 HTML 表单提交时提交选中项的文本还是 key。当 `allowsCustomValue` 为 `true` 时该选项不适用，始终提交文本 | | `autoComplete` | `string` | - | 自动完成行为类型 | | `autoFocus` | `boolean` | - | 是否在挂载时自动聚焦 | | `allowsCustomValue` | `boolean` | - | 是否允许不在列表中的自定义值 | | `allowsEmptyCollection` | `boolean` | - | 是否允许空集合 | | `menuTrigger` | `"focus" \| "input" \| "manual"` | `"focus"` | 展示 ComboBox 菜单所需的交互 | | `shouldFocusWrap` | `boolean` | - | 键盘导航是否循环 | | `fullWidth` | `boolean` | `false` | ComboBox 是否占满容器宽度 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式；`secondary` 为低强调无阴影，适用于 Surface 内 | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode \| RenderFunction` | - | ComboBox 内容或 render 函数 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, ComboBoxRenderProps>` | - | 使用自定义 render 函数覆盖默认 DOM 元素 | ### ComboBox.InputGroup | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ------------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode` | - | InputGroup 内容 | ### ComboBox.Value 渲染 ComboBox 已选中的值，若未选中任何值则渲染占位符。默认情况下，已选项以逗号分隔的列表形式渲染。可使用 render 函数自定义（例如以标签形式展示）。 | Prop | 类型 | 默认值 | 描述 | | ------------- | -------------------------------------------------------------- | --- | ----------------- | | `placeholder` | `ReactNode` | - | 未选中任何项时展示的值 | | `className` | `string \| (values: ComboBoxValueRenderProps) => string` | - | 附加 CSS 类 | | `children` | `ReactNode \| (values: ComboBoxValueRenderProps) => ReactNode` | - | 自定义已选值的 render 函数 | ### ComboBox.Trigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | -------- | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode` | - | 自定义触发器内容 | ### ComboBox.Popover | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------------ | | `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"` | 相对于触发器的 Popover 位置 | | `className` | `string` | - | 附加 CSS 类 | | `children` | `ReactNode` | - | 子内容 | ### Render Props 对 ComboBox 使用 render 函数时，会传入以下值： | Prop | 类型 | 描述 | | -------------- | --------------- | ----------- | | `state` | `ComboBoxState` | ComboBox 状态 | | `inputValue` | `string` | 当前输入值 | | `selectedKey` | `Key \| null` | 当前选中的 key | | `selectedItem` | `Node \| null` | 当前选中的 item | ## 无障碍 ComboBox 实现 ARIA ComboBox 模式，并提供： * 完整键盘导航 * 选择与输入变化时的屏幕阅读器播报 * 合理的焦点管理 * 禁用状态支持 * 输入过滤（typeahead）式搜索 * 与 HTML 表单的集成 * 自定义值支持 更多信息见 [React Aria ComboBox 文档](https://react-spectrum.adobe.com/react-aria/ComboBox.html)。 ## 相关组件 ## 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 </page> <page url="/cn/docs/react/components/select"> # Select 选择器 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/select **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(pickers)/select.mdx > Select 展示可折叠的选项列表，并允许用户从中选择一项。 ## 用法 ```tsx import { Select } from "@heroui/react"; ``` ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function Default() { return ( <Select className="w-[256px]" placeholder="请选择"> <Label>州</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="佛罗里达"> 佛罗里达 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="特拉华"> 特拉华 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="加利福尼亚"> 加利福尼亚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="德克萨斯"> 德克萨斯 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="纽约"> 纽约 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="华盛顿"> 华盛顿 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ## 组件结构 ```tsx import {Select, Label, Description, Header, ListBox, Separator} from "@heroui/react"; export default () => ( <Select> <Label /> <Select.Trigger> <Select.Value /> <Select.ClearButton /> <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> ); ``` ## 示例 ### 变体 Select 组件支持两种视觉变体： * **`primary`**（默认）— 带阴影的标准样式，适用于大多数场景 * **`secondary`** — 低强调、无阴影，适合在 Surface 等表面背景上使用 ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function Variants() { return ( <div className="flex flex-col gap-4"> <Select className="w-[256px]" placeholder="请选择" variant="primary"> <Label>主要变体</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="option1" textValue="选项 1"> Option 1 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="option2" textValue="选项 2"> Option 2 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> <Select className="w-[256px]" placeholder="请选择" variant="secondary"> <Label>次要变体</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="option1" textValue="选项 1"> Option 1 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="option2" textValue="选项 2"> Option 2 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> </div> ); } ``` ### 宽度充满 ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function FullWidth() { return ( <div className="w-[400px] space-y-4"> <Select fullWidth placeholder="请选择"> <Label>喜爱的动物</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="bird" textValue="鸟"> 鸟 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> </div> ); } ``` ### 带描述 ```tsx import {Description, Label, ListBox, Select} from "@heroui/react"; export function WithDescription() { return ( <Select className="w-[256px]" placeholder="请选择"> <Label>州</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="佛罗里达"> 佛罗里达 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="特拉华"> 特拉华 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="加利福尼亚"> 加利福尼亚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="德克萨斯"> 德克萨斯 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="纽约"> 纽约 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="华盛顿"> 华盛顿 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> <Description>请选择居住州</Description> </Select> ); } ``` ### 必填 ```tsx "use client"; import {Button, FieldError, Form, Label, ListBox, Select} from "@heroui/react"; export function Required() { const onSubmit = (e: React.SyntheticEvent<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("表单提交成功！"); }; return ( <Form className="flex w-[256px] flex-col gap-4" onSubmit={onSubmit}> <Select isRequired className="w-full" name="state" placeholder="请选择"> <Label>州</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="佛罗里达"> 佛罗里达 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="特拉华"> 特拉华 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="加利福尼亚"> 加利福尼亚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="德克萨斯"> 德克萨斯 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="纽约"> 纽约 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="华盛顿"> 华盛顿 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> <FieldError /> </Select> <Select isRequired className="w-full" name="country" placeholder="请选择国家"> <Label>国家</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="usa" textValue="美国"> 美国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="canada" textValue="加拿大"> 加拿大 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="mexico" textValue="墨西哥"> 墨西哥 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="uk" textValue="英国"> 英国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="法国"> 法国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="germany" textValue="德国"> 德国 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> <FieldError /> </Select> <Button type="submit">提交</Button> </Form> ); } ``` ### 禁用 ```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="请选择"> <Label>州</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="佛罗里达"> 佛罗里达 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="特拉华"> 特拉华 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="加利福尼亚"> 加利福尼亚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="德克萨斯"> 德克萨斯 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="纽约"> 纽约 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="华盛顿"> 华盛顿 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> <Select isDisabled className="w-[256px]" defaultValue={["argentina", "japan", "france"]} placeholder="请选择国家" selectionMode="multiple" > <Label>拟访问国家</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="argentina" textValue="阿根廷"> 阿根廷 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="venezuela" textValue="委内瑞拉"> 委内瑞拉 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="japan" textValue="日本"> 日本 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="法国"> 法国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="italy" textValue="意大利"> 意大利 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="spain" textValue="西班牙"> 西班牙 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> </div> ); } ``` ### 含禁用选项 ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function WithDisabledOptions() { return ( <Select className="w-[256px]" disabledKeys={["cat", "kangaroo"]} placeholder="请选择动物"> <Label>动物</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="dog" textValue="狗"> 狗 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="cat" textValue="猫"> 猫 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="bird" textValue="鸟"> 鸟 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="kangaroo" textValue="袋鼠"> 袋鼠 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="elephant" textValue="大象"> 大象 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="tiger" textValue="老虎"> 老虎 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ### 多选 ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function MultipleSelect() { return ( <Select className="w-[256px]" placeholder="请选择国家" selectionMode="multiple"> <Label>拟访问国家</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox selectionMode="multiple"> <ListBox.Item id="argentina" textValue="阿根廷"> 阿根廷 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="venezuela" textValue="委内瑞拉"> 委内瑞拉 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="japan" textValue="日本"> 日本 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="法国"> 法国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="italy" textValue="意大利"> 意大利 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="spain" textValue="西班牙"> 西班牙 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="thailand" textValue="泰国"> 泰国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-zealand" textValue="新西兰"> 新西兰 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="iceland" textValue="冰岛"> 冰岛 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ### 分组选项 ```tsx import {Header, Label, ListBox, Select, Separator} from "@heroui/react"; export function WithSections() { return ( <Select className="w-[256px]" placeholder="请选择国家"> <Label>国家</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Section> <Header>北美洲</Header> <ListBox.Item id="usa" textValue="美国"> 美国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="canada" textValue="加拿大"> 加拿大 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="mexico" textValue="墨西哥"> 墨西哥 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>欧洲</Header> <ListBox.Item id="uk" textValue="英国"> 英国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="法国"> 法国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="germany" textValue="德国"> 德国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="spain" textValue="西班牙"> 西班牙 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="italy" textValue="意大利"> 意大利 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> <Separator /> <ListBox.Section> <Header>亚洲</Header> <ListBox.Item id="japan" textValue="日本"> 日本 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="china" textValue="中国"> 中国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="india" textValue="印度"> 印度 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="south-korea" textValue="韩国"> 韩国 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox.Section> </ListBox> </Select.Popover> </Select> ); } ``` ### 受控组件 ```tsx "use client"; import type {Key} from "@heroui/react"; import {Label, ListBox, Select} from "@heroui/react"; import {useState} from "react"; export function Controlled() { const states = [ { id: "california", name: "加利福尼亚", }, { id: "texas", name: "德克萨斯", }, { id: "florida", name: "佛罗里达", }, { id: "new-york", name: "纽约", }, { id: "illinois", name: "伊利诺伊", }, { id: "pennsylvania", name: "宾夕法尼亚", }, ]; 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="请选择州" value={state} onChange={(value) => setState(value)} > <Label>州（受控）</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">已选：{selectedState?.name || "无"}</p> </div> ); } ``` ### 受控多选 ```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="请选择州" selectionMode="multiple" value={selected} onChange={(keys) => setSelected(keys as Key[])} > <Label>州（受控多选）</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox selectionMode="multiple"> <ListBox.Item id="california" textValue="加利福尼亚"> 加利福尼亚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="德克萨斯"> 德克萨斯 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="florida" textValue="佛罗里达"> 佛罗里达 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="纽约"> 纽约 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="illinois" textValue="伊利诺伊"> 伊利诺伊 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="pennsylvania" textValue="宾夕法尼亚"> 宾夕法尼亚 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> <p className="text-sm text-muted">已选：{selected.length > 0 ? selected.join(", ") : "无"}</p> </div> ); } ``` ### 受控展开状态 ```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="请选择" onOpenChange={setIsOpen}> <Label>州</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="佛罗里达"> 佛罗里达 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="特拉华"> 特拉华 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="加利福尼亚"> 加利福尼亚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="德克萨斯"> 德克萨斯 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="纽约"> 纽约 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="华盛顿"> 华盛顿 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> <Button onPress={() => setIsOpen(!isOpen)}>{isOpen ? "关闭" : "打开"}选择框</Button> <p className="text-sm text-muted">选择框{isOpen ? "已打开" : "已关闭"}</p> </div> ); } ``` ### 异步加载 ```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="请选择宝可梦"> <Label>选择宝可梦</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">加载更多…</span> </div> </ListBoxLoadMoreItem> </ListBox> </Select.Popover> </Select> ); } ``` ### 自定义指示器 ```tsx import {ChevronsExpandVertical} from "@gravity-ui/icons"; import {Label, ListBox, Select} from "@heroui/react"; export function CustomIndicator() { return ( <Select className="w-[256px]" placeholder="请选择"> <Label>州</Label> <Select.Trigger> <Select.Value /> <Select.Indicator className="size-3"> <ChevronsExpandVertical /> </Select.Indicator> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="佛罗里达"> 佛罗里达 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="特拉华"> 特拉华 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="加利福尼亚"> 加利福尼亚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="德克萨斯"> 德克萨斯 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="纽约"> 纽约 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="华盛顿"> 华盛顿 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ### 带清除按钮 `Select.Trigger` 本身是 button，因此不能再嵌套 `<button>` 来实现清除。请在触发器内组合 `Select.ClearButton` — 它渲染为非 button 控件，且不会打开菜单。 ```tsx import {Label, ListBox, Select} from "@heroui/react"; export function WithClearButton() { return ( <Select className="w-[256px]" defaultValue="california" placeholder="Select one"> <Label>State</Label> <Select.Trigger> <Select.Value /> <Select.ClearButton /> <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> ); } ``` 由于 ARIA 将 button 的子节点视为纯展示内容，清除控件无法获得焦点，因此它带有 `aria-hidden`，仅作为指针操作的可视入口。当组合了 `Select.ClearButton` 时，触发器同时支持按 `Backspace` 或 `Delete` 清除，这是键盘与屏幕阅读器用户的清除方式。两种方式都会调用 `onClear`。 ### 自定义展示值 ```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="请选择用户"> <Label>用户</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} 位用户已选`; } 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> ); } ``` ### 渲染函数 ```tsx "use client"; import {Label, ListBox, Select} from "@heroui/react"; export function RenderFunction() { return ( <Select className="w-[256px]" placeholder="请选择" render={(props) => <div {...props} data-custom="foo" />} > <Label>州</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="佛罗里达"> 佛罗里达 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="特拉华"> 特拉华 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="加利福尼亚"> 加利福尼亚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="德克萨斯"> 德克萨斯 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="纽约"> 纽约 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="华盛顿"> 华盛顿 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ### 表面样式 在 [Surface](/docs/react/components/surface) 内使用时，请使用 `variant="secondary"`，以应用适合表面背景的低强调变体。 ```tsx "use client"; import {Button, FieldError, Form, Label, ListBox, Select, Surface} from "@heroui/react"; export function OnSurface() { const onSubmit = (e: React.SyntheticEvent<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("表单提交成功！"); }; 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="请选择" variant="secondary"> <Label>州</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="florida" textValue="佛罗里达"> 佛罗里达 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="delaware" textValue="特拉华"> 特拉华 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="california" textValue="加利福尼亚"> 加利福尼亚 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="texas" textValue="德克萨斯"> 德克萨斯 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="new-york" textValue="纽约"> 纽约 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="washington" textValue="华盛顿"> 华盛顿 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> <FieldError /> </Select> <Select isRequired className="w-full" name="country" placeholder="请选择国家" variant="secondary" > <Label>国家</Label> <Select.Trigger> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover> <ListBox> <ListBox.Item id="usa" textValue="美国"> 美国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="canada" textValue="加拿大"> 加拿大 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="mexico" textValue="墨西哥"> 墨西哥 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="uk" textValue="英国"> 英国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="france" textValue="法国"> 法国 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item id="germany" textValue="德国"> 德国 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> <FieldError /> </Select> <Button type="submit">提交</Button> </Form> </Surface> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Label, ListBox, Select} from "@heroui/react"; const itemClass = "rounded-lg data-[focused=true]:bg-accent/10 data-[selected=true]:text-foreground"; export function CustomStyles() { return ( <Select className="w-56" placeholder="选择套餐" variant="secondary"> <Label className="font-medium text-foreground">套餐</Label> <Select.Trigger className="rounded-xl bg-default"> <Select.Value /> <Select.Indicator /> </Select.Trigger> <Select.Popover className="rounded-xl border border-border bg-surface p-1 shadow-lg"> <ListBox> <ListBox.Item className={itemClass} id="free" textValue="免费"> 免费 <ListBox.ItemIndicator /> </ListBox.Item> <ListBox.Item className={itemClass} id="pro" textValue="专业版"> 专业版 <ListBox.ItemIndicator /> </ListBox.Item> </ListBox> </Select.Popover> </Select> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Select 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/select.css)）： #### 基础类 \[!toc] * `.select` - Select 根容器 * `.select__trigger` - 打开下拉的触发按钮 * `.select__value` - 当前显示的值或占位符 * `.select__clear-button` - 触发器内的可选清除控件 * `.select__indicator` - 下拉指示图标 * `.select__popover` - 弹出层容器 #### 变体类 \[!toc] * `.select--primary` - Primary 变体，带阴影（默认） * `.select--secondary` - Secondary 变体，无阴影，适合在 Surface 上使用 #### 状态类 \[!toc] * `.select[data-invalid="true"]` - 无效状态 * `.select__trigger[data-focus-visible="true"]` - 触发器聚焦状态 * `.select__trigger[data-disabled="true"]` - 触发器禁用状态 * `.select__value[data-placeholder="true"]` - 占位符状态 * `.select__clear-button[data-empty="true"]` - 无选中项时隐藏清除控件 * `.select__indicator[data-open="true"]` - 展开时的指示器状态 ### 交互状态 该组件同时支持 CSS 伪类与 data 属性，以提供更灵活的状态控制： * **悬停**：触发器上的 `:hover` 或 `[data-hovered="true"]` * **聚焦**：触发器上的 `:focus-visible` 或 `[data-focus-visible="true"]` * **禁用**：Select 上的 `:disabled` 或 `[data-disabled="true"]` * **展开**：指示器上的 `[data-open="true"]` ## API 参考 ### Select | Prop | 类型 | 默认值 | 描述 | | --------------- | ------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------- | | `placeholder` | `string` | `'Select an item'` | Select 为空时显示的占位符文本。 | | `selectionMode` | `"single" \| "multiple"` | `"single"` | 启用单选或多选。 | | `isOpen` | `boolean` | - | 设置菜单是否打开（受控）。 | | `defaultOpen` | `boolean` | - | 设置菜单默认是否打开（非受控）。 | | `onOpenChange` | `(isOpen: boolean) => void` | - | 展开状态变化时的事件处理函数。 | | `disabledKeys` | `Iterable<Key>` | - | 禁用条目的 key。 | | `isDisabled` | `boolean` | - | Select 是否禁用。 | | `value` | `Key \| Key[] \| null` | - | 当前值（受控）。 | | `defaultValue` | `Key \| Key[] \| null` | - | 默认值（非受控）。 | | `onChange` | `(value: Key \| Key[] \| null) => void` | - | 值变化时的事件处理函数。 | | `onClear` | `() => void` | - | 清除选择时的事件处理函数。 | | `isRequired` | `boolean` | - | 用户输入是否必填。 | | `isInvalid` | `boolean` | - | Select 的值是否无效。 | | `name` | `string` | - | 输入框名称，用于提交 HTML 表单。 | | `autoComplete` | `string` | - | 描述自动完成行为类型。 | | `fullWidth` | `boolean` | `false` | Select 是否占满容器宽度。 | | `variant` | `"primary" \| "secondary"` | `"primary"` | 视觉变体。`primary` 为默认带阴影样式。`secondary` 为低强调、无阴影变体，适合在 Surface 上使用。 | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | Select 内容或渲染函数。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SelectRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Select.Trigger | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------------------- | --- | ----------- | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 触发器内容或渲染函数。 | ### Select.Value | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------ | --- | --------------------- | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `ReactNode \| RenderFunction` | - | 值区域内容或渲染函数。 | | `render` | `DOMRenderFunction<keyof React.JSX.IntrinsicElements, SelectValueRenderProps>` | - | 使用自定义渲染函数覆盖默认 DOM 元素。 | ### Select.Indicator | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------- | --- | ---------- | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `ReactNode` | - | 自定义指示器内容。 | ### Select.ClearButton | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------- | --- | --------------- | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `ReactNode` | - | 自定义内容，替代默认图标。 | | `onClick` | `(e: MouseEvent) => void` | - | 点击清除控件时的事件处理函数。 | `Select.ClearButton` 渲染为 `span`，因此可以放在 `Select.Trigger`（button）内部而不会形成嵌套 button。选择为空时会自动隐藏。 ### Select.Popover | Prop | 类型 | 默认值 | 描述 | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------- | ------------ | | `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"` | 弹出层相对触发器的位置。 | | `className` | `string` | - | 额外的 CSS 类。 | | `children` | `ReactNode` | - | 子内容。 | ### RenderProps 对 `Select.Value` 使用渲染函数时，会提供以下值： | Prop | 类型 | 描述 | | ----------------- | ------------- | ----------- | | `defaultChildren` | `ReactNode` | 默认渲染的值。 | | `isPlaceholder` | `boolean` | 是否为占位符状态。 | | `state` | `SelectState` | Select 的状态。 | | `selectedItems` | `Node[]` | 当前已选中的条目。 | ## 无障碍 Select 组件实现 ARIA 列表框模式，并提供： * 完整的键盘导航支持 * 选择变化时的屏幕阅读器播报 * 合理的焦点管理 * 禁用状态支持 * 输入首字母快速定位（typeahead） * 与 HTML 表单的集成 更多信息见 [React Aria Select 文档](https://react-spectrum.adobe.com/react-aria/Select.html)。 ## 相关组件 ## Related Components * **Listbox**: Scrollable list of selectable items * **Popover**: Displays content in context with a trigger * **Label**: Accessible label for form controls </page> <page url="/cn/docs/react/components/kbd"> # Kbd 键盘按键 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/kbd **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(typography)/kbd.mdx > 展示键盘快捷键与按键组合 ## 用法 ```tsx import { Kbd } from "@heroui/react"; ``` ```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> ); } ``` ## 组件结构 ```tsx import { Kbd } from "@heroui/react"; export default () => ( <Kbd> <Kbd.Abbr title="Command">⌘</Kbd.Abbr> <Kbd.Content>K</Kbd.Content> </Kbd> ); ``` ## 示例 ### 变体 ```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>复制：</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>粘贴：</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>剪切：</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>撤销：</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>重做：</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> ); } ``` ### 导航按键 ```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">方向键：</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">页面导航：</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> ); } ``` ### 行内用法 ```tsx import {Kbd} from "@heroui/react"; export function InlineUsage() { return ( <div className="space-y-4"> <p className="text-sm"> 按{" "} <Kbd> <Kbd.Content>Esc</Kbd.Content> </Kbd>{" "} 关闭对话框。 </p> <p className="text-sm"> 使用{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>K</Kbd.Content> </Kbd>{" "} 打开命令面板。 </p> <p className="text-sm"> 使用{" "} <Kbd> <Kbd.Abbr keyValue="up" /> </Kbd>{" "} 和{" "} <Kbd> <Kbd.Abbr keyValue="down" /> </Kbd>{" "} 方向键进行导航。 </p> <p className="text-sm"> 使用{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>S</Kbd.Content> </Kbd>{" "} 定期保存你的工作。 </p> </div> ); } ``` ### 说明文字 ```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">快捷操作</h4> <ul className="space-y-2 text-sm"> <li> • 打开搜索：{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>K</Kbd.Content> </Kbd> </li> <li> • 切换侧边栏：{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>B</Kbd.Content> </Kbd> </li> <li> • 新建文件：{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>N</Kbd.Content> </Kbd> </li> <li> • 快速保存：{" "} <Kbd> <Kbd.Abbr keyValue="command" /> <Kbd.Content>S</Kbd.Content> </Kbd> </li> </ul> </div> </div> ); } ``` ### 特殊按键 ```tsx import {Kbd} from "@heroui/react"; export function SpecialKeys() { return ( <div className="space-y-3"> <p className="text-sm"> 按{" "} <Kbd> <Kbd.Abbr keyValue="enter" /> </Kbd>{" "} 确认，或按{" "} <Kbd> <Kbd.Abbr keyValue="escape" /> </Kbd>{" "} 取消。 </p> <p className="text-sm"> 使用{" "} <Kbd> <Kbd.Abbr keyValue="tab" /> </Kbd>{" "} 在表单字段间切换，使用{" "} <Kbd> <Kbd.Abbr keyValue="shift" /> <Kbd.Abbr keyValue="tab" /> </Kbd>{" "} 返回上一项。 </p> <p className="text-sm"> 按住{" "} <Kbd> <Kbd.Abbr keyValue="space" /> </Kbd>{" "} 可临时启用平移模式。 </p> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {Kbd} from "@heroui/react"; export function CustomStyles() { return ( <div className="flex items-center gap-3"> <Kbd className="rounded-lg bg-accent-soft px-2.5 text-accent-soft-foreground"> <Kbd.Abbr keyValue="command" /> <Kbd.Content>K</Kbd.Content> </Kbd> <Kbd className="rounded-lg bg-default px-2.5 text-muted"> <Kbd.Abbr keyValue="shift" /> <Kbd.Content>P</Kbd.Content> </Kbd> </div> ); } ``` ### 全局 CSS 可使用 `@layer components` 指令自定义 Kbd 组件类。 [了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Kbd 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/kbd.css)）： #### 基础类 \[!toc] * `.kbd` - 基础按键样式，含背景、边框与间距 * `.kbd__abbr` - 修饰键的缩写元素 * `.kbd__content` - 按键文本的内容包裹层 ## API 参考 ### Kbd | Prop | 类型 | 默认值 | 描述 | | | ----------- | ----------------- | --------- | --------- | ------ | | `children` | `React.ReactNode` | - | 按键内容 | | | `variant` | \`"default" | "light"\` | `default` | 按键视觉变体 | | `className` | `string` | - | 自定义 CSS 类 | | ### Kbd.Abbr | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | ------------------------------ | | `title` | `string` | - | 无障碍 title 属性（如 ⌘ 对应 "Command"） | | `children` | `React.ReactNode` | - | 要显示的符号或文本（如 ⌘、⌥、⇧） | | `className` | `string` | - | 自定义 CSS 类 | ### Kbd.Key | Prop | 类型 | 默认值 | 描述 | | ----------- | ----------------- | --- | --------- | | `children` | `React.ReactNode` | - | 按键文本内容 | | `className` | `string` | - | 自定义 CSS 类 | ### Kbd.Content Type `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="/cn/docs/react/components/typography"> # Typography 排版 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/typography **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(typography)/typography.mdx > 面向标题、正文与行内代码的语义化排版原语，基于 React Aria Components 的 Text 构建。 ## 用法 ```tsx import {Typography} from "@heroui/react"; ``` ```tsx import {Typography} from "@heroui/react"; export const Default = () => { return ( <div className="flex max-w-xl flex-col gap-4"> <Typography type="h1">打造更出色的界面</Typography> <Typography type="h2">保持语义化的排版</Typography> <Typography type="h3">默认可组合</Typography> <Typography type="h4">小标题</Typography> <Typography> HeroUI Typography 以 React Aria Components Text 为原语，提供语义化排版类型与 render prop 多态。 </Typography> <Typography color="muted" type="body-sm"> 用于次要说明的较小弱化正文。 </Typography> <Typography type="code">pnpm add @heroui/react</Typography> </div> ); }; ``` ## 组件结构 默认情况下，`Typography` 会将视觉上的 `type` 映射到对应的语义化元素。 ```tsx import {Typography} from "@heroui/react"; export default () => ( <Typography type="h1">Heading</Typography> ); ``` ## 示例 ### 层级 ```tsx import {Typography} from "@heroui/react"; const scale = [ { label: "h1", meta: "36px / 600 / 1.11 / tight", sample: "打造更出色的界面", type: "h1" as const, }, { label: "h2", meta: "30px / 600 / 1.17 / tight", sample: "为智能时代而生", type: "h2" as const, }, { label: "h3", meta: "24px / 600 / 1.25 / tight", sample: "按您的条件定价", type: "h3" as const, }, { label: "h4", meta: "20px / 600 / 1.33 / tight", sample: "申请创业计划", type: "h4" as const, }, { label: "h5", meta: "18px / 600 / 1.39 / tight", sample: "卡片标题", type: "h5" as const, }, { label: "h6", meta: "16px / 600 / 1.50 / tight", sample: "较小的功能标题", type: "h6" as const, }, { label: "body", meta: "16px / 400 / 1.75", sample: "用于文档、营销文案与描述的主要正文。", type: "body" as const, }, { label: "body-sm", meta: "14px / 400 / 1.50", sample: "次要正文、表格单元格、导航与侧边栏项。", type: "body-sm" as const, }, { label: "body-xs", meta: "12px / 400 / 1.25", sample: "说明文字、徽章、辅助文本与细则。", type: "body-xs" as const, }, { label: "code", meta: "14px / mono", sample: "pnpm add @heroui/react", type: "code" as const, }, ] as const; export const TypographyScale = () => { return ( <div className="flex w-full flex-col divide-y divide-border"> {scale.map((row) => ( <div key={row.label} className="grid grid-cols-[160px_1fr] items-center gap-8 py-5"> <div className="flex shrink-0 flex-col gap-0.5"> <span className="text-sm font-semibold text-foreground">{row.label}</span> <span className="text-xs whitespace-nowrap text-muted">{row.meta}</span> </div> <Typography type={row.type}>{row.sample}</Typography> </div> ))} </div> ); }; ``` ### 原语 ```tsx import {Typography} from "@heroui/react"; export const Primitives = () => { return ( <div className="flex max-w-xl flex-col gap-4"> <Typography.Heading level={1}>仪表盘</Typography.Heading> <Typography.Paragraph> 便捷原语是 Typography 的薄封装，可在不学习第二套样式系统的情况下选择显式组合。 </Typography.Paragraph> <Typography.Paragraph color="muted" size="sm"> Paragraph 支持 base、sm 和 xs 尺寸。 </Typography.Paragraph> <Typography.Code>Typography.Code</Typography.Code> </div> ); }; ``` * `Typography.Heading` 将 `level={1..6}` 映射为 `type="h1"` 至 `type="h6"`。 * `Typography.Paragraph` 将 `size="base" | "sm" | "xs"` 映射为正文样式。 * `Typography.Code` 映射为行内代码样式。 * `Typography.Prose` 为以常规 HTML 子节点传入的富文本内容提供排版样式。 ### 富文本排版 ```tsx import {Typography} from "@heroui/react"; export const Prose = () => { return ( <Typography.Prose className="flex max-w-xl flex-col gap-3"> <h1>正文标题</h1> <p>Prose 适用于标记已是语义化、由 HeroUI 应用默认排版节奏的写作型内容。</p> <h2>章节标题</h2> <p> 行内代码如 <code>render</code> 与 Typography 原语获得相同的代码样式处理。 </p> </Typography.Prose> ); }; ``` ### 渲染属性 ```tsx "use client"; import {Typography} from "@heroui/react"; export const RenderProps = () => { return ( <div className="flex max-w-xl flex-col gap-4"> <Typography render={({children, ...domProps}) => <h2 {...domProps}>{children}</h2>} type="h1"> H1 视觉样式，h2 语义元素 </Typography> <Typography render={({children, ...domProps}) => <span {...domProps}>{children}</span>}> render prop 可更换底层元素，同时保留 HeroUI 的 props 与样式。 </Typography> </div> ); }; ``` 需要自定义实际渲染的元素时，可使用 React Aria Components 风格的 `render` prop。 ## 自定义样式 ### Tailwind CSS ```tsx import {Typography} from "@heroui/react"; export function CustomStyles() { return ( <div className="flex max-w-md flex-col gap-2 rounded-xl border border-border/80 bg-surface-secondary p-4"> <Typography className="text-xs font-medium tracking-wide text-accent uppercase" type="body-xs" > 更新日志 </Typography> <Typography className="font-semibold tracking-tight text-foreground" type="h4"> 更快的搜索结果 </Typography> <Typography className="text-sm leading-relaxed text-muted" type="body-sm"> 得益于改进的索引，查询现在在 200 毫秒内返回。 </Typography> </div> ); } ``` ### 全局 CSS 若要自定义 Typography 组件类，可使用 `@layer components` 指令。[了解更多](https://tailwindcss.com/docs/adding-custom-styles#adding-component-classes)。 ```css @layer components { .typography--h1 { @apply font-extrabold tracking-tight; } .typography--code { @apply rounded-md bg-default-100 font-mono dark:bg-default-50/20; } } ``` ## 样式参考 HeroUI 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 Typography 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/typography.css)）： #### 基础类 \[!toc] * `.typography` - 排版基础原语 * `.typography-prose` - 富文本文章体容器 #### 类型类 \[!toc] * `.typography--h1` 至 `.typography--h6` * `.typography--body`、`.typography--body-sm`、`.typography--body-xs` * `.typography--code` #### 修饰类 \[!toc] * `.typography--align-start`、`.typography--align-center`、`.typography--align-end`、`.typography--align-justify` * `.typography--color-default`、`.typography--color-muted` * `.typography--truncate` * `.typography--weight-normal`、`.typography--weight-medium`、`.typography--weight-semibold`、`.typography--weight-bold` ## API 参考 ### Typography | 属性 | 类型 | 默认值 | 说明 | | ---------- | -------------------------------------------------------------------------------------------- | ----------- | ----------------------- | | `type` | `'h1' \| 'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6' \| 'body' \| 'body-sm' \| 'body-xs' \| 'code'` | `'body'` | 语义化排版样式。 | | `align` | `'start' \| 'center' \| 'end' \| 'justify'` | `'start'` | 文本对齐。 | | `color` | `'default' \| 'muted'` | `'default'` | 文本颜色。 | | `weight` | `'normal' \| 'medium' \| 'semibold' \| 'bold'` | - | 字重覆盖。 | | `truncate` | `boolean` | - | 将文本截断为单行并显示省略号。 | | `render` | `DOMRenderFunction` | - | 来自 React Aria 的自定义渲染函数。 | | `children` | `ReactNode` | - | 文本内容。 | ## 相关组件 </page> <page url="/cn/docs/react/components/scroll-shadow"> # ScrollShadow 滚动阴影 **Category**: react **URL**: https://heroui.com/cn/docs/react/components/scroll-shadow **Source**: https://raw.githubusercontent.com/heroui-inc/heroui/refs/heads/v3/apps/docs/content/docs/cn/react/components/(utilities)/scroll-shadow.mdx > 通过阴影提示可滚动溢出内容，并根据滚动位置自动检测显示或隐藏。 ## 用法 ```tsx import { ScrollShadow } from "@heroui/react"; ``` ```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}`}> 段落 {idx + 1}：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> ); } ``` ## 示例 ### 方向 ```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">垂直</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}`}> 段落 {idx + 1}：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">水平</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="示例卡片" 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">连接未来</Card.Title> <Card.Description className="text-xs">今天 18:30</Card.Description> </div> </Card> ))} </div> </ScrollShadow> </Card> </div> </div> ); } ``` ### 阴影尺寸 ```tsx import {ScrollShadow} from "@heroui/react"; export default function Size() { 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}`}> 段落 {idx + 1}：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> ); } ``` ### 与 Card 组合 ```tsx import {Button, Card, ScrollShadow} from "@heroui/react"; export default function WithCard() { return ( <Card className="max-w-[400px]"> <Card.Header> <Card.Title>条款与条件</Card.Title> <Card.Description>继续前请先阅读</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}`}> 段落 {idx + 1}：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">接受</Button> </Card.Footer> </Card> ); } ``` ### 隐藏滚动条 ```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}`}> 段落 {idx + 1}：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> ); } ``` ### 可见性变化 ```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", ]; const VISIBILITY_LABELS: Record<ScrollShadowVisibility, string> = { auto: "自动", both: "两侧", bottom: "底部", left: "左侧", none: "无", right: "右侧", top: "顶部", }; 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">垂直阴影状态：{VISIBILITY_LABELS[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}`}> 段落 {idx + 1}：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"> 水平阴影状态：{VISIBILITY_LABELS[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="示例卡片" 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">连接未来</Card.Title> <Card.Description className="text-xs">今天 18:30</Card.Description> </div> </Card> ))} </div> </ScrollShadow> </div> </div> </div> ); } ``` ## 自定义样式 ### Tailwind CSS ```tsx import {ScrollShadow} from "@heroui/react"; const entries = [ "与设计团队一起回顾季度目标。", "将深色模式设计令牌发布到生产环境。", "合并表单字段的无障碍修复。", "发布更新后的组件文档。", "安排下一冲刺的性能审计。", "在文档站点中添加滚动阴影示例。", ]; export function CustomStyles() { return ( <div className="w-full sm:max-w-sm"> <ScrollShadow hideScrollBar className="max-h-48 rounded-xl border border-border/80 bg-linear-to-b from-neutral-50/90 to-white p-4 ring-1 ring-black/5 dark:from-neutral-900/80 dark:to-neutral-900 dark:ring-white/10" size={48} variant="fade" > <div className="space-y-3"> {entries.map((entry) => ( <p key={entry} className="text-sm leading-relaxed text-neutral-600 dark:text-neutral-400" > {entry} </p> ))} </div> </ScrollShadow> </div> ); } ``` ### 全局 CSS 若要自定义组件类，可使用 `@layer components` 指令。[了解更多](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 遵循 [BEM](https://getbem.com/) 方法论，确保组件变体与状态可复用且易于自定义。 ### CSS 类 ScrollShadow 组件使用以下 CSS 类（[查看源码样式](https://github.com/heroui-inc/heroui/blob/v3/packages/styles/components/scroll-shadow.css)）： #### 基础类 \[!toc] * `.scroll-shadow` - 根容器元素 #### 方向变体 \[!toc] * `.scroll-shadow--vertical` - 纵向滚动（默认） * `.scroll-shadow--horizontal` - 横向滚动 #### 状态修饰符 \[!toc] * `.scroll-shadow--hide-scrollbar` - 隐藏原生滚动条 ### CSS 变量 ScrollShadow 组件使用 CSS 变量设置渐变遮罩尺寸，并为可见的原生滚动条保留空间： | 变量 | 默认值 | 描述 | | -------------------------------- | -------------------------------- | ---------------------------------------------- | | `--scroll-shadow-size` | `40px` | 控制渐变阴影尺寸。该值由 `size` prop 设置。 | | `--scroll-shadow-offset` | `0px` | 开始显示渐变之前需要滚动的距离。该值由 `offset` prop 设置。 | | `--scroll-shadow-scrollbar-size` | `10px`（`hideScrollBar` 时为 `0px`） | 为原生滚动条保留一段实色遮罩区域，避免渐变覆盖滚动条。使用更宽的自定义滚动条时可以覆盖该值。 | ### Data 属性 组件使用 data 属性控制阴影可见性： * **滚动状态**：`[data-top-scroll]`、`[data-bottom-scroll]`、`[data-left-scroll]`、`[data-right-scroll]` — 当内容可向对应方向滚动时应用 * **组合状态**：`[data-top-bottom-scroll]`、`[data-left-right-scroll]` — 当内容可向两个方向滚动时应用 * **方向**：`[data-orientation="vertical"]` 或 `[data-orientation="horizontal"]` — 表示滚动方向 * **尺寸**：`[data-scroll-shadow-size]` — 阴影渐变尺寸数值 * **阴影模式**：`[data-scroll-shadow-mode]` — 渐变由滚动位置推导时为 `"auto"`；`visibility` 受控或 `isEnabled` 为 `false` 时为 `"manual"` ### 滚动驱动的渐变 在 `auto` 模式下，支持[滚动驱动动画](https://developer.mozilla.org/zh-CN/docs/Web/CSS/animation-timeline)的浏览器会直接在 CSS 中根据滚动位置推导渐变。因此遮罩在首次绘制时就是正确的，无需测量，也不会在 hydration 期间出现未渐变内容的闪烁。 不支持的浏览器会回退到上面的 `[data-*-scroll]` 属性，这些属性在 hydration 之后才写入。自定义样式时需要注意两点： * 在 `auto` 模式下，即使没有可滚动内容，根元素也始终会解析出 `mask-image`。这会使其成为层叠上下文， 并成为 `position: fixed` 后代元素的包含块。如需退出该行为，请显式设置 `visibility`。 * 滚动驱动的渐变依赖根元素上的 `animation` 属性。在同一元素上使用 `animate-*` 工具类会覆盖它，导致渐变消失。 请改为对外层容器应用动画。 ## API 参考 ### ScrollShadow | Prop | 类型 | 默认值 | 描述 | | -------------------- | ---------------------------------------------------------------------------------- | ------------ | ----------------- | | `orientation` | `"vertical"` \| `"horizontal"` | `"vertical"` | 滚动方向 | | `variant` | `"fade"` | `"fade"` | 阴影视觉效果样式 | | `size` | `number` | `40` | 阴影渐变尺寸（像素） | | `offset` | `number` | `0` | 开始显示阴影前的滚动偏移量（像素） | | `hideScrollBar` | `boolean` | `false` | 是否隐藏原生滚动条 | | `isEnabled` | `boolean` | `true` | 是否启用滚动阴影检测 | | `visibility` | `"auto"` \| `"both"` \| `"top"` \| `"bottom"` \| `"left"` \| `"right"` \| `"none"` | `"auto"` | 受控的阴影可见性 | | `onVisibilityChange` | `(visibility: ScrollShadowVisibility) => void` | - | 阴影可见性变化时调用的回调 | | `className` | `string` | - | 应用到根元素上的额外 CSS 类 | | `children` | `ReactNode` | - | 可滚动的子内容 | ## 相关组件 </page>