跳到正文
目录与搜索
⌘K

原语 / Animate UI

Theme Toggler · Animate UI

使用 View Transitions API 把新主题以擦除方式铺满页面的主题切换器。

安装

自有原语直接来自 @animate-ui/react,不依赖 Radix UI、Base UI 或 React Aria;装上包即可使用。

终端
bun add @animate-ui/react motion

用法

直接从 @animate-ui/react 的对应子路径引入,下面就是完整示例;样式由你的类名决定。

theme-toggler.tsx
import { useTheme } from 'next-themes';
import {
  ThemeToggler,
  type Resolved,
  type ThemeSelection,
} from '@animate-ui/react/primitives/effects/theme-toggler';

export function ThemeButton() {
  const { theme, resolvedTheme, setTheme } = useTheme();

  return (
    <ThemeToggler
      theme={theme as ThemeSelection}
      resolvedTheme={resolvedTheme as Resolved}
      setTheme={setTheme}
    >
      {({ effective, toggleTheme }) => (
        <button
          onClick={() => toggleTheme(effective === 'dark' ? 'light' : 'dark')}
        >
          {effective === 'dark' ? 'Light mode' : 'Dark mode'}
        </button>
      )}
    </ThemeToggler>
  );
}

动效

  • 新主题以 clip-path 擦除在 700ms ease-in-out 内展开,方向由 direction 控制,默认从左到右。
  • 新旧页面都是快照,擦除过程中不会触发重新渲染;减少动效下直接切换。

所有时长都会乘以 AnimateUIProvider 的 tempo,并遵守系统的减少动效设置。

API

动效相关的 transition 与 exitTransition 是 Animate UI 唯一新增的属性;其余 props 见上表。

属性类型默认值
theme'light' | 'dark' | 'system'—
resolvedTheme'light' | 'dark'—
setTheme(theme: 'light' | 'dark' | 'system') => void—
direction'btt' | 'ttb' | 'ltr' | 'rtl''ltr'
onImmediateChange(theme: 'light' | 'dark' | 'system') => void—
childrenReact.ReactNode | ((state: { resolved: 'light' | 'dark'; effective: 'light' | 'dark' | 'system'; toggleTheme: (theme: 'light' | 'dark' | 'system') => void }) => React.ReactNode)—

未列出的属性与上游 API 完全一致,可在 官方文档 查阅。

内容对应官方文档 2026-10-18 版本。