HammerHammer

主题切换

在亮色、暗色与跟随系统之间切换主题的组件。

Open in v0

最后更新:2026/10/07 13:52:32

pnpm dlx shadcn add @chaos-design/theme-switch
npx shadcn@latest add @chaos-design/theme-switch
yarn dlx shadcn add @chaos-design/theme-switch
bunx shadcn add @chaos-design/theme-switch
Open preview in new tab

全部配置

下面把 ThemeSwitch 的每个属性都摆出来:左键点击任意开关的下拉菜单,或直接点受控卡片上的按钮。

Open preview in new tab

需要注意的三点:

  • 多个开关默认联动。 非受控开关之间通过模块级广播实时同步,所以在这个页面里切换一次主题,八个开关会一起变。
  • 受控开关不写存储。 传入 value 后组件仍然会把主题应用到文档,但不再写入 localStorage、也不再同步其他开关。
  • attribute 会作用于整个文档。 设为 data-theme 时组件会写入 data-theme 属性并移除 .dark 类,因此你的 CSS 需要按 [data-theme="dark"] 来匹配:
<ThemeSwitch attribute="data-theme" />
[data-theme="dark"] {
  /* 你的暗色变量 */
}

安装

npm install @chaos-design/theme-switch

使用方式

import { ThemeSwitch } from '@chaos-design/theme-switch';

export default function Demo() {
  return <ThemeSwitch />;
}

配合无闪烁脚本(放在服务端渲染的页面 <head> 中),在首次绘制之前完成主题应用:

import { ThemeScript } from '@chaos-design/theme-switch';

export default function Root() {
  return (
    <html lang="zh" suppressHydrationWarning>
      <head>
        <ThemeScript />
      </head>
      <body>{/* ... */}</body>
    </html>
  );
}

Props

属性类型默认值说明
valueTheme-受控主题值('light' | 'dark' | 'system')。
defaultThemeTheme'system'未存储时的初始主题。
onValueChange(theme: Theme) => void-用户切换主题时的回调。
storageKeystring'theme'持久化主题的 localStorage 键名。
enableSystembooleantrue是否提供“跟随系统”选项。
attribute'class' | 'data-theme''class'主题写入文档根节点的方式。
disableTransitionOnChangebooleantrue切换主题时禁用 CSS 过渡,避免页面闪现。
labelsPartial<Record<Theme, string>>-自定义各项的文本(国际化)。
iconsPartial<Record<Theme, ComponentType>>-自定义各项的图标。
triggerLabelstring-触发按钮的 aria-label。
classNamestring-自定义触发按钮类名。
classNamesThemeSwitchClassNames-内部元素自定义类名。

ThemeSwitchClassNames

属性说明
trigger触发按钮。
content弹出菜单。
item菜单项。
icon图标。

On this page