StaggeredMenu

staggered-menu

侧滑分层导航菜单 · 触发按钮（菜单↔关闭文字滚动 + 加号旋转 225°）唤起面板 · 多层色层错峰滑入做叠纸质感 + 主条目自下而上带旋转依次入场 + 序号/社交链接尾随淡入（motion 去 gsap·token·reduced-motion）

用法

基础用法

放进 relative + 固定高度 + overflow-hidden 的容器，点右上角按钮唤起右侧滑入面板。

瑚琏

tsx

<div className="relative h-96 overflow-hidden rounded-xl border border-border">
  <StaggeredMenu
    items={[
      { label: "首页", link: "#home" },
      { label: "产品", link: "#product" },
      { label: "方案", link: "#solution" },
      { label: "关于", link: "#about" },
    ]}
    socialItems={[
      { label: "GitHub", link: "https://github.com" },
      { label: "知乎", link: "https://zhihu.com" },
    ]}
  />
</div>

左侧滑入 + 自定义品牌

position="left" 让面板与色层从左侧滑入，brand 槽自定义左上角品牌文字。

HULIAN

tsx

<StaggeredMenu
  position="left"
  brand="HULIAN"
  items={items}
  socialItems={socialItems}
/>

自定义色层与强调色

colors 控制背后错峰色层，accentColor 影响序号 / 社交标题 / 条目 hover 色。

瑚琏

tsx

<StaggeredMenu
  items={items}
  socialItems={socialItems}
  colors={["var(--color-chart-3)", "var(--color-chart-1)"]}
  accentColor="oklch(0.72 0.22 30)"
/>

精简：无序号无社交区

displayItemNumbering 与 displaySocials 置 false，只保留主条目。

瑚琏

tsx

<StaggeredMenu
  items={items}
  displayItemNumbering={false}
  displaySocials={false}
/>

何时用

需要一个有强叠纸/错峰仪式感的侧滑全屏（或全容器）抽屉式导航时用，常见于品牌站 / 作品集的汉堡菜单。要水平常驻导航条用 PillNav 或 GooeyNav；要功能性下拉/多级菜单用 NavigationMenu 或 Menu。本组件内部 absolute 定位，需放进 relative + 固定高度 + overflow-hidden 的承托容器；整页罩层场景设 isFixed。

导入

import { StaggeredMenu } from "@hulianui/ui"

Props

名称	类型	默认	说明
items	`StaggeredMenuItem[]`	—	主条目列表，空数组渲染占位「No items」
socialItems	`StaggeredMenuSocial[]`	—	社交链接列表，配合 `displaySocials` 在面板底部展示
position	`"left" \| "right"`	`"right"`	面板与色层滑出方向
colors	`string[]`	chart-4 / chart-1 两层	面板背后多层色层颜色（错峰滑入），最多取前 4 个；建议喂 `var(--color-chart-*)` token
displaySocials	`boolean`	`true`	是否展示底部社交区（仅 `socialItems` 非空才实际渲染）
displayItemNumbering	`boolean`	`true`	是否给主条目展示前缀序号（01 / 02 …）
accentColor	`string`	`var(--color-primary)`	强调色（序号 / 社交标题 / 条目 hover）
isFixed	`boolean`	`false`	是否 `fixed` 铺满视口（整页罩层）；否则相对父容器铺满
closeOnClickAway	`boolean`	`true`	点击面板外区域是否关闭
className	`string`	—	透传根容器类名
style	`CSSProperties`	—	透传根容器内联样式

StaggeredMenuItem：{ label; link?; ariaLabel? }（link 缺省渲染为不可跳转 span）。StaggeredMenuSocial：{ label; link }。

Events

事件	类型	说明
onMenuOpen	`() => void`	菜单打开回调
onMenuClose	`() => void`	菜单关闭回调

Slots

插槽	类型	说明
brand	`ReactNode`	触发按钮旁的品牌槽（通常放 logo 文字或图标），缺省渲染默认文字「瑚琏」

禁忌 / 坑

非 isFixed 时必须放进 relative + 固定高度 + overflow-hidden 容器：组件内部 absolute 定位，缺承托会塌缩或溢出（showcase 用 relative h-96 overflow-hidden）。
displaySocials 为 true 但 socialItems 为空时底部社交区不渲染，二者需同时给。
色层 colors 喂主题色请用 var(--color-chart-*) 这类带 --color- 前缀的 token；裸 var(--primary) 在 SVG/canvas 取色处可能不解析。
reduced-motion 下错峰入场退化为直接显示，属预期。

Playground

面板方向条目序号社交区

瑚琏

<div className="relative h-96 overflow-hidden rounded-xl border border-border">
  <StaggeredMenu
    position="right"
    displayItemNumbering={true}
    displaySocials={true}
    items={[{ label: "首页", link: "#home" }, { label: "产品", link: "#product" }]}
    socialItems={[{ label: "GitHub", link: "https://github.com" }]}
  />
</div>

用法

基础用法

放进 relative + 固定高度 + overflow-hidden 的容器，点右上角按钮唤起右侧滑入面板。

瑚琏

tsx

<div className="relative h-96 overflow-hidden rounded-xl border border-border">
  <StaggeredMenu
    items={[
      { label: "首页", link: "#home" },
      { label: "产品", link: "#product" },
      { label: "方案", link: "#solution" },
      { label: "关于", link: "#about" },
    ]}
    socialItems={[
      { label: "GitHub", link: "https://github.com" },
      { label: "知乎", link: "https://zhihu.com" },
    ]}
  />
</div>

左侧滑入 + 自定义品牌

position="left" 让面板与色层从左侧滑入，brand 槽自定义左上角品牌文字。

HULIAN

tsx

<StaggeredMenu
  position="left"
  brand="HULIAN"
  items={items}
  socialItems={socialItems}
/>

自定义色层与强调色

colors 控制背后错峰色层，accentColor 影响序号 / 社交标题 / 条目 hover 色。

瑚琏

tsx

<StaggeredMenu
  items={items}
  socialItems={socialItems}
  colors={["var(--color-chart-3)", "var(--color-chart-1)"]}
  accentColor="oklch(0.72 0.22 30)"
/>

精简：无序号无社交区

displayItemNumbering 与 displaySocials 置 false，只保留主条目。

瑚琏

tsx

<StaggeredMenu
  items={items}
  displayItemNumbering={false}
  displaySocials={false}
/>

何时用

Props

名称	类型	默认	说明
items	`StaggeredMenuItem[]`	—	主条目列表，空数组渲染占位「No items」
socialItems	`StaggeredMenuSocial[]`	—	社交链接列表，配合 `displaySocials` 在面板底部展示
position	`"left" \| "right"`	`"right"`	面板与色层滑出方向
colors	`string[]`	chart-4 / chart-1 两层	面板背后多层色层颜色（错峰滑入），最多取前 4 个；建议喂 `var(--color-chart-*)` token
displaySocials	`boolean`	`true`	是否展示底部社交区（仅 `socialItems` 非空才实际渲染）
displayItemNumbering	`boolean`	`true`	是否给主条目展示前缀序号（01 / 02 …）
accentColor	`string`	`var(--color-primary)`	强调色（序号 / 社交标题 / 条目 hover）
isFixed	`boolean`	`false`	是否 `fixed` 铺满视口（整页罩层）；否则相对父容器铺满
closeOnClickAway	`boolean`	`true`	点击面板外区域是否关闭
className	`string`	—	透传根容器类名
style	`CSSProperties`	—	透传根容器内联样式

StaggeredMenuItem：{ label; link?; ariaLabel? }（link 缺省渲染为不可跳转 span）。StaggeredMenuSocial：{ label; link }。

事件

类型

说明

onMenuOpen

() => void

菜单打开回调

onMenuClose

() => void

菜单关闭回调

插槽

类型

说明

brand

ReactNode

触发按钮旁的品牌槽（通常放 logo 文字或图标），缺省渲染默认文字「瑚琏」

禁忌 / 坑

非 isFixed 时必须放进 relative + 固定高度 + overflow-hidden 容器：组件内部 absolute 定位，缺承托会塌缩或溢出（showcase 用 relative h-96 overflow-hidden）。

displaySocials 为 true 但 socialItems 为空时底部社交区不渲染，二者需同时给。

色层 colors 喂主题色请用 var(--color-chart-*) 这类带 --color- 前缀的 token；裸 var(--primary) 在 SVG/canvas 取色处可能不解析。

reduced-motion 下错峰入场退化为直接显示，属预期。

Playground

面板方向条目序号社交区

瑚琏

<div className="relative h-96 overflow-hidden rounded-xl border border-border">
  <StaggeredMenu
    position="right"
    displayItemNumbering={true}
    displaySocials={true}
    items={[{ label: "首页", link: "#home" }, { label: "产品", link: "#product" }]}
    socialItems={[{ label: "GitHub", link: "https://github.com" }]}
  />
</div>

StaggeredMenu

用法

基础用法

左侧滑入 + 自定义品牌

自定义色层与强调色

精简：无序号无社交区

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground

StaggeredMenu

用法

基础用法

左侧滑入 + 自定义品牌

自定义色层与强调色

精简：无序号无社交区

何时用

导入

Props

Events

Slots

禁忌 / 坑

相关

Playground