Pro组件、模板与 AI 工具
HeroUI
27.7k
快速开始
组件
发布说明
迁移

Dropdown 下拉菜单

展示用户可选择的操作或选项列表

StorybookReact Aria源代码样式源代码

用法

import { Dropdown } from '@heroui/react';

组件结构

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

示例

带图标

带描述

含禁用项

分组选项

多选

受控组件

受控展开状态

单选

单选自定义指示器

分组级选择

带快捷键

含子菜单

自定义子菜单指示器

自定义触发器

长按触发

自定义样式

Tailwind CSS

全局 CSS

可使用 @layer components 指令自定义 Dropdown 组件类。 了解更多。

@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 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

Dropdown 组件使用以下 CSS 类（查看源码样式）：

基础类

  • .dropdown - Dropdown 根容器
  • .dropdown__trigger - 触发 Dropdown 的按钮或元素
  • .dropdown__popover - Popover 容器
  • .dropdown__menu - Popover 内的菜单容器

状态类

  • .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 作为底层组件。以下类名也可用于自定义：

菜单类

  • .menu - 菜单容器（menu.css）
    • [data-slot="separator"] - 菜单内的分隔线元素

菜单项类

  • .menu-item - 菜单项容器（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 - 危险样式变体

菜单项状态类

  • .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）

菜单分区类

交互状态

组件同时支持 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 参考

Prop类型默认值描述
isOpenboolean-设置菜单展开状态（受控）。
defaultOpenboolean-设置菜单默认展开状态（非受控）。
onOpenChange(isOpen: boolean) => void-展开状态变化时调用的事件处理函数。
trigger"press" | "longPress""press"触发菜单的交互类型。
classNamestring-额外的 Tailwind CSS 类。
childrenReactNode-Dropdown 内容。
Prop类型默认值描述
classNamestring-额外的 Tailwind CSS 类。
childrenReactNode | RenderFunction-触发器内容或渲染函数。

使用 Button 作为触发器时，同样支持所有 Button props。

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 位置。
classNamestring-额外的 Tailwind CSS 类。
childrenReactNode-子内容。

同样支持所有 Popover props。

Prop类型默认值描述
selectionMode"single" | "multiple" | "none""none"是否启用单选、多选或不启用选择。
selectedKeysIterable<Key>-当前选中的 key（受控）。
defaultSelectedKeysIterable<Key>-初始选中的 key（非受控）。
onSelectionChange(keys: Selection) => void-选中变化时调用的事件处理函数。
disabledKeysIterable<Key>-禁用项的 key。
onAction(key: Key) => void-激活菜单项时调用的事件处理函数。
classNamestring-额外的 Tailwind CSS 类。
childrenReactNode-菜单内容。

同样支持所有 Menu props。

Prop类型默认值描述
selectionMode"single" | "multiple"-该分组内菜单项的选择模式。
selectedKeysIterable<Key>-当前选中的 key（受控）。
defaultSelectedKeysIterable<Key>-初始选中的 key（非受控）。
onSelectionChange(keys: Selection) => void-选中变化时调用的事件处理函数。
disabledKeysIterable<Key>-禁用项的 key。
classNamestring-额外的 Tailwind CSS 类。
childrenReactNode-分组内容。

同样支持所有 MenuSection props。

Prop类型默认值描述
idKey-菜单项唯一标识。
textValuestring-用于首字母导航的文本内容。
variant"default" | "danger""default"菜单项视觉变体。
classNamestring-额外的 Tailwind CSS 类。
childrenReactNode | RenderFunction-菜单项内容或渲染函数。

同样支持所有 MenuItem props。

Prop类型默认值描述
type"checkmark" | "dot""checkmark"指示器类型。
classNamestring-额外的 Tailwind CSS 类。
childrenReactNode | RenderFunction-自定义指示器内容或渲染函数。

使用渲染函数时，会传入以下值：

Prop类型描述
isSelectedboolean该项是否选中。
isIndeterminateboolean该项是否处于不确定状态。
Prop类型默认值描述
classNamestring-额外的 Tailwind CSS 类。
childrenReactNode-自定义指示器内容。
Prop类型默认值描述
classNamestring-额外的 Tailwind CSS 类。
childrenReactNode-子菜单触发器内容。

同样支持所有 SubmenuTrigger props。

Render Props

在 Dropdown.Item 中使用渲染函数时，会传入以下值：

Prop类型描述
isSelectedboolean该项是否选中。
isFocusedboolean该项是否聚焦。
isDisabledboolean该项是否禁用。
isPressedboolean该项是否处于按下状态。

无障碍

Dropdown 组件实现 ARIA 菜单模式，并提供：

  • 完整键盘导航（方向键、Home/End、首字母导航）
  • 屏幕阅读器对操作与选中变化的播报
  • 合理的焦点管理
  • 禁用态支持
  • 长按交互支持
  • 子菜单导航

更多信息见 React Aria Menu 文档。

相关组件

Drawer 抽屉

用于补充内容与操作的滑出面板

ErrorMessage 错误消息

用于展示错误的底层错误消息组件

本页目录

用法组件结构示例带图标带描述含禁用项分组选项多选受控组件受控展开状态单选单选自定义指示器分组级选择带快捷键含子菜单自定义子菜单指示器自定义触发器长按触发自定义样式Tailwind CSS全局 CSS样式参考CSS 类菜单组件类交互状态API 参考DropdownDropdown.TriggerDropdown.PopoverDropdown.MenuDropdown.SectionDropdown.ItemDropdown.ItemIndicatorDropdown.SubmenuIndicatorDropdown.SubmenuTriggerRender Props无障碍相关组件