Accordion

accordion

手风琴 · Base UI 单/多开 + 高度过渡

用法

基础用法

单开模式：同一时刻最多展开一项，点击标题切换。

tsx

<Accordion className="w-80">
  <AccordionItem value="ship">
    <AccordionTrigger>瑚琏怎么发版？</AccordionTrigger>
    <AccordionPanel>本地 master 直接 commit，trunk-based，三道门全绿即可。</AccordionPanel>
  </AccordionItem>
  <AccordionItem value="token">
    <AccordionTrigger>颜色怎么适配明暗？</AccordionTrigger>
    <AccordionPanel>只消费语义 token，Tailwind v4 dark variant 自动换肤。</AccordionPanel>
  </AccordionItem>
</Accordion>

默认展开

用 defaultValue 指定初始展开的项（非受控）。

本地 master 直接 commit，trunk-based，无 remote。三道门全绿即可。

tsx

<Accordion defaultValue={["ship"]} className="w-80">
  <AccordionItem value="ship">
    <AccordionTrigger>瑚琏怎么发版？</AccordionTrigger>
    <AccordionPanel>本地 master 直接 commit。</AccordionPanel>
  </AccordionItem>
  {/* …更多 item */}
</Accordion>

多开

multiple 允许同时展开多项。

本地 master 直接 commit，trunk-based，无 remote。三道门全绿即可。

只消费语义 token，禁写死裸值；Tailwind v4 dark variant 自动换肤。

tsx

<Accordion multiple defaultValue={["ship", "token"]} className="w-80">
  {/* item 同上 */}
</Accordion>

禁用项

在 AccordionItem 上加 disabled，该项不可展开且置灰。

本地 master 直接 commit，trunk-based，无 remote。三道门全绿即可。

tsx

<Accordion defaultValue={["ship"]} className="w-80">
  <AccordionItem value="ship">
    <AccordionTrigger>瑚琏怎么发版？</AccordionTrigger>
    <AccordionPanel>本地 master 直接 commit。</AccordionPanel>
  </AccordionItem>
  <AccordionItem value="token" disabled>
    <AccordionTrigger>颜色怎么适配明暗？</AccordionTrigger>
    <AccordionPanel>不可展开。</AccordionPanel>
  </AccordionItem>
</Accordion>

何时用

多组「标题 + 可折叠内容」并列（FAQ、设置分组、文档目录）时用，默认单开互斥、可切多开。只有单块内容要折叠用 Collapsible；不需要折叠、只是导航跳转用 Command。

导入

import { Accordion, AccordionItem, AccordionTrigger, AccordionPanel } from "@hulianui/ui"

Props

Accordion / AccordionItem / AccordionTrigger / AccordionPanel 均为 Base UI 对应原语的薄包，透传其全部 props。常用如下：

名称	类型	默认	说明
`Accordion.multiple`	`boolean`	`false`	是否允许同时展开多项；`false` 时为单开互斥
`Accordion.defaultValue`	`string[]`	—	非受控初始展开的 item value 数组
`Accordion.value`	`string[]`	—	受控展开态
`Accordion.className`	`string`	—	容器类名
`AccordionItem.value` *	`string`	—	该项唯一标识，与 `value`/`defaultValue` 对应
`AccordionItem.disabled`	`boolean`	`false`	禁用该项（不可展开/收起）

Events

事件	类型	说明
`Accordion.onValueChange`	`(value: string[]) => void`	展开态变化回调（透传 Base UI Root），受控时配合 `value` 使用

Slots

插槽	类型	说明
`AccordionTrigger.children`	`ReactNode`	标题行内容
`AccordionPanel.children`	`ReactNode`	折叠区内容

禁忌 / 坑

高度展开/收起过渡走 Base UI 暴露的 --accordion-panel-height CSS 变量做纯 CSS transition，不要自己 useLayoutEffect 测 scrollHeight、也别上 framer-motion；padding 要放 Panel 内层 div 否则收起塌不到 0。详见 [[base-ui-accordion-panel-height-css-var-pure-css-transition]]。
受控与非受控二选一：传了 value 就别再传 defaultValue。

Playground

multiple（多开）禁用第二项

本地 master 直接 commit，trunk-based，无 remote。三道门全绿即可。

<Accordion defaultValue={["ship"]}>
  <AccordionItem value="ship">
    <AccordionTrigger>瑚琏怎么发版？</AccordionTrigger>
    <AccordionPanel>本地 master 直接 commit…</AccordionPanel>
  </AccordionItem>
  {/* …更多 item */}
</Accordion>

用法

基础用法

单开模式：同一时刻最多展开一项，点击标题切换。

tsx

<Accordion className="w-80">
  <AccordionItem value="ship">
    <AccordionTrigger>瑚琏怎么发版？</AccordionTrigger>
    <AccordionPanel>本地 master 直接 commit，trunk-based，三道门全绿即可。</AccordionPanel>
  </AccordionItem>
  <AccordionItem value="token">
    <AccordionTrigger>颜色怎么适配明暗？</AccordionTrigger>
    <AccordionPanel>只消费语义 token，Tailwind v4 dark variant 自动换肤。</AccordionPanel>
  </AccordionItem>
</Accordion>

默认展开

用 defaultValue 指定初始展开的项（非受控）。

本地 master 直接 commit，trunk-based，无 remote。三道门全绿即可。

tsx

<Accordion defaultValue={["ship"]} className="w-80">
  <AccordionItem value="ship">
    <AccordionTrigger>瑚琏怎么发版？</AccordionTrigger>
    <AccordionPanel>本地 master 直接 commit。</AccordionPanel>
  </AccordionItem>
  {/* …更多 item */}
</Accordion>

多开

multiple 允许同时展开多项。

本地 master 直接 commit，trunk-based，无 remote。三道门全绿即可。

只消费语义 token，禁写死裸值；Tailwind v4 dark variant 自动换肤。

tsx

<Accordion multiple defaultValue={["ship", "token"]} className="w-80">
  {/* item 同上 */}
</Accordion>

禁用项

在 AccordionItem 上加 disabled，该项不可展开且置灰。

本地 master 直接 commit，trunk-based，无 remote。三道门全绿即可。

tsx

<Accordion defaultValue={["ship"]} className="w-80">
  <AccordionItem value="ship">
    <AccordionTrigger>瑚琏怎么发版？</AccordionTrigger>
    <AccordionPanel>本地 master 直接 commit。</AccordionPanel>
  </AccordionItem>
  <AccordionItem value="token" disabled>
    <AccordionTrigger>颜色怎么适配明暗？</AccordionTrigger>
    <AccordionPanel>不可展开。</AccordionPanel>
  </AccordionItem>
</Accordion>

Props

Accordion / AccordionItem / AccordionTrigger / AccordionPanel 均为 Base UI 对应原语的薄包，透传其全部 props。常用如下：

名称	类型	默认	说明
`Accordion.multiple`	`boolean`	`false`	是否允许同时展开多项；`false` 时为单开互斥
`Accordion.defaultValue`	`string[]`	—	非受控初始展开的 item value 数组
`Accordion.value`	`string[]`	—	受控展开态
`Accordion.className`	`string`	—	容器类名
`AccordionItem.value` *	`string`	—	该项唯一标识，与 `value`/`defaultValue` 对应
`AccordionItem.disabled`	`boolean`	`false`	禁用该项（不可展开/收起）

事件

类型

说明

Accordion.onValueChange

(value: string[]) => void

展开态变化回调（透传 Base UI Root），受控时配合 value 使用

插槽

类型

说明

AccordionTrigger.children

ReactNode

标题行内容

AccordionPanel.children

ReactNode

折叠区内容

禁忌 / 坑

高度展开/收起过渡走 Base UI 暴露的 --accordion-panel-height CSS 变量做纯 CSS transition，不要自己 useLayoutEffect 测 scrollHeight、也别上 framer-motion；padding 要放 Panel 内层 div 否则收起塌不到 0。详见 [[base-ui-accordion-panel-height-css-var-pure-css-transition]]。

受控与非受控二选一：传了 value 就别再传 defaultValue。

Playground

multiple（多开）禁用第二项

本地 master 直接 commit，trunk-based，无 remote。三道门全绿即可。

<Accordion defaultValue={["ship"]}>
  <AccordionItem value="ship">
    <AccordionTrigger>瑚琏怎么发版？</AccordionTrigger>
    <AccordionPanel>本地 master 直接 commit…</AccordionPanel>
  </AccordionItem>
  {/* …更多 item */}
</Accordion>

Accordion

用法

基础用法

默认展开

多开

禁用项

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground

Accordion

用法

基础用法

默认展开

多开

禁用项

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground

用法

基础用法

瑚琏怎么发版？

颜色怎么适配明暗？

无障碍谁兜底？

默认展开

瑚琏怎么发版？

颜色怎么适配明暗？

无障碍谁兜底？

多开

瑚琏怎么发版？

颜色怎么适配明暗？

无障碍谁兜底？

禁用项

瑚琏怎么发版？

颜色怎么适配明暗？

无障碍谁兜底？

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground

瑚琏怎么发版？

颜色怎么适配明暗？

无障碍谁兜底？

用法

基础用法

瑚琏怎么发版？

颜色怎么适配明暗？

无障碍谁兜底？

默认展开

瑚琏怎么发版？

颜色怎么适配明暗？

无障碍谁兜底？

多开

瑚琏怎么发版？

颜色怎么适配明暗？

无障碍谁兜底？

禁用项

瑚琏怎么发版？

颜色怎么适配明暗？

无障碍谁兜底？

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground

瑚琏怎么发版？

颜色怎么适配明暗？

无障碍谁兜底？