JGuang
EN

动画主题切换

Theme Toggler · Magic UI

交互预览
npx shadcn@latest add https://jiguang132.com/r/magic-ui/animated-theme-toggler.json

部分上游示例使用在线图片、视频或推文；这些内容依赖网络与第三方服务，不代表本地预览加载失败。

动画主题切换

Magic UI 的独立组件，请不要替换为 JGuang UI/Base UI 的同名 API。

安装

npx shadcn@latest add https://jiguang132.com/r/magic-ui/animated-theme-toggler.json

Registry 将复制可编辑源码和依赖到独立命名空间。检查主题变量与 Tailwind CSS v4 配置；不要覆盖已有的项目组件。

使用与验证

在左侧选择组件，在预览中操作它的状态；使用“查看代码”检查真实源码。安装后执行类型检查和构建，再验证键盘焦点、手机布局与深浅色主题。

来源

https://github.com/magicuidesign/magicui/tree/cdb348cb4c72a9b54b554d8617801e479fbc8714 MIT 许可证；不包括付费内容。下方提供上游英文参考内容，中文使用指南已适配；上游详细参考暂保留英文。

适用场景

通过视图过渡形状切换主题。

示例使用的原生参数

从该组件全部本地示例的 JSX 提取，按导入模块及组件区分；包括复合示例中实际使用的其他 Magic UI 组件。不是全部属性清单，也不是宿主通用 variant API。展开对象需结合示例数据声明；完整类型与默认值见下方源码参考。

所属组件参数说明示例来源
AnimatedThemeToggler.variant (animated-theme-toggler)所属组件的样式/形状联合，不能替换为统一 variant API。examples/animated-theme-toggler-square-demo.tsx、examples/animated-theme-toggler-diamond-demo.tsx、examples/animated-theme-toggler-rectangle-demo.tsx、examples/animated-theme-toggler-hexagon-demo.tsx、examples/animated-theme-toggler-triangle-demo.tsx、examples/animated-theme-toggler-star-demo.tsx
AnimatedThemeToggler.theme (animated-theme-toggler)受控 light/dark 值，宿主管理持久化。examples/animated-theme-toggler-next-themes-demo.tsx
AnimatedThemeToggler.onThemeChange (animated-theme-toggler)接收请求切换的主题，与受控 theme 配套。examples/animated-theme-toggler-next-themes-demo.tsx

交互与状态检查

  • 动画主题切换 · 默认示例 — animated-theme-toggler-demo
  • 动画主题切换 · 方形过渡 — animated-theme-toggler-square-demo
  • 动画主题切换 · 菱形过渡 — animated-theme-toggler-diamond-demo
  • 动画主题切换 · 矩形过渡 — animated-theme-toggler-rectangle-demo
  • 动画主题切换 · 六边形过渡 — animated-theme-toggler-hexagon-demo
  • 动画主题切换 · 三角形过渡 — animated-theme-toggler-triangle-demo
  • 动画主题切换 · 星形过渡 — animated-theme-toggler-star-demo
  • 受控 next-themes 主题 — animated-theme-toggler-next-themes-demo

这些名称是实际示例入口，不是新增组件属性或独立组件数量。选择对应示例后，检查指针/键盘行为、深浅色、手机尺寸和加载失败；纯装饰特效不应伪造禁用、错误或提交状态。完整示例安装包含其真实依赖闭包。

业务接入边界

传入 theme/onThemeChange 时由父组件管理持久化；复用 next-themes，隔离预览不能修改平台父页面。

宿主与动画配置

初始化 Tailwind CSS v4、语义 CSS 变量及 dark 变体；按本地 Registry 的独立命名空间导入。复用已有 next-themes Provider，不混入 JGuang UI/Base UI/HeroUI API。进入视口再挂载特效，离开后卸载；为 Canvas/WebGL 不可用、网络媒体失败提供静态替代。遵循 prefers-reduced-motion，并验证计时器、RAF、观察器和事件监听已清理；不能仅凭 CSS 停止就宣称引擎已停止。示例不提供后端、登录、支付或真实 AI 流。这里的实用指南为双语，上游详细参考和演示文本仍保留原文。

可用状态与示例

动画主题切换 · 默认示例、动画主题切换 · 方形过渡、动画主题切换 · 菱形过渡、动画主题切换 · 矩形过渡、动画主题切换 · 六边形过渡、动画主题切换 · 三角形过渡、动画主题切换 · 星形过渡、受控 next-themes 主题

组件中的状态与数据为演示用途，不包含后端接口。接入实际项目时请检查源码中的公开参数，再连接业务数据。

Installation

<Tabs defaultValue="cli"> <TabsList> <TabsTrigger value="cli">CLI</TabsTrigger> <TabsTrigger value="manual">Manual</TabsTrigger> </TabsList> <TabsContent value="cli"> 
npx shadcn@latest add @magicui/animated-theme-toggler
</TabsContent> <TabsContent value="manual"> <Steps>

<Step>Copy and paste the following code into your project.</Step>

<Step>Update the import paths to match your project setup.</Step>

<Step>Add the required CSS into your global CSS file</Step>

The component sets --magicui-theme-toggle-vt-duration and a data-magicui-theme-vt="active" flag on <html> only while a toggle is in flight, so the clip-path animation stays in sync with the view-transition group without affecting any other view transitions in your app (e.g. Next.js navigation transitions).

::view-transition-old(root),
::view-transition-new(root) {
  animation: none;
  mix-blend-mode: normal;
}

/* Scoped to AnimatedThemeToggler — the toggler sets the data-attribute and the variable only during a theme toggle. */
html[data-magicui-theme-vt="active"]::view-transition-group(root) {
  animation-duration: var(--magicui-theme-toggle-vt-duration);
}
</Steps> </TabsContent> </Tabs>

Usage

import { AnimatedThemeToggler } from "@/components/ui/animated-theme-toggler"

<AnimatedThemeToggler />

Use variant to change the clip-path shape of the view transition (circle, square, triangle, diamond, rectangle, hexagon, or star):

<AnimatedThemeToggler variant="star" />

Expand from the viewport center instead of the button with fromCenter:

<AnimatedThemeToggler variant="hexagon" duration={600} fromCenter />

Examples

The preview at the top of this page uses the default circle reveal. Below, each variant has its own isolated preview so you can test one shape at a time.

Square

Diamond

Rectangle

Hexagon

Triangle

Star

Next.js (next-themes)

Pass theme and onThemeChange to keep useTheme() subscribers in sync on toggle. When controlled, the component skips localStorage and lets the parent own persistence.

Props

PropTypeDefaultDescription
classNamestring—Additional classes for the button
durationnumber400Duration of the theme transition animation in milliseconds
variantTransitionVariant"circle"Shape used for the view-transition clip-path reveal
fromCenterbooleanfalseIf true, the clip expands from the viewport center instead of the button
theme"light" | "dark"—Controlled theme value. When set, the parent owns persistence (e.g. next-themes).
onThemeChange(theme: "light" | "dark") => void—Called on toggle. Pair with theme for controlled usage.

Export TransitionVariant from the same module when you need typed props or menus.

Credits

完整示例安装

组件安装命令只安装组件；下列示例命令还包含该示例实际导入的其他组件、原生辅助 UI、工具和固定版本依赖。辅助源码不算独立组件。

动画主题切换 · 默认示例

npx shadcn@latest add https://jiguang132.com/r/magic-ui/examples/animated-theme-toggler/animated-theme-toggler-demo.json

默认导入: @/components/magicui/examples/animated-theme-toggler-demo

依赖: clsx@2.1.1, lucide-react@1.24.0, tailwind-merge@3.6.0

动画主题切换 · 方形过渡

npx shadcn@latest add https://jiguang132.com/r/magic-ui/examples/animated-theme-toggler/animated-theme-toggler-square-demo.json

默认导入: @/components/magicui/examples/animated-theme-toggler-square-demo

依赖: clsx@2.1.1, lucide-react@1.24.0, tailwind-merge@3.6.0

动画主题切换 · 菱形过渡

npx shadcn@latest add https://jiguang132.com/r/magic-ui/examples/animated-theme-toggler/animated-theme-toggler-diamond-demo.json

默认导入: @/components/magicui/examples/animated-theme-toggler-diamond-demo

依赖: clsx@2.1.1, lucide-react@1.24.0, tailwind-merge@3.6.0

动画主题切换 · 矩形过渡

npx shadcn@latest add https://jiguang132.com/r/magic-ui/examples/animated-theme-toggler/animated-theme-toggler-rectangle-demo.json

默认导入: @/components/magicui/examples/animated-theme-toggler-rectangle-demo

依赖: clsx@2.1.1, lucide-react@1.24.0, tailwind-merge@3.6.0

动画主题切换 · 六边形过渡

npx shadcn@latest add https://jiguang132.com/r/magic-ui/examples/animated-theme-toggler/animated-theme-toggler-hexagon-demo.json

默认导入: @/components/magicui/examples/animated-theme-toggler-hexagon-demo

依赖: clsx@2.1.1, lucide-react@1.24.0, tailwind-merge@3.6.0

动画主题切换 · 三角形过渡

npx shadcn@latest add https://jiguang132.com/r/magic-ui/examples/animated-theme-toggler/animated-theme-toggler-triangle-demo.json

默认导入: @/components/magicui/examples/animated-theme-toggler-triangle-demo

依赖: clsx@2.1.1, lucide-react@1.24.0, tailwind-merge@3.6.0

动画主题切换 · 星形过渡

npx shadcn@latest add https://jiguang132.com/r/magic-ui/examples/animated-theme-toggler/animated-theme-toggler-star-demo.json

默认导入: @/components/magicui/examples/animated-theme-toggler-star-demo

依赖: clsx@2.1.1, lucide-react@1.24.0, tailwind-merge@3.6.0

受控 next-themes 主题

npx shadcn@latest add https://jiguang132.com/r/magic-ui/examples/animated-theme-toggler/animated-theme-toggler-next-themes-demo.json

默认导入: @/components/magicui/examples/animated-theme-toggler-next-themes-demo

依赖: clsx@2.1.1, lucide-react@1.24.0, next-themes@0.4.6, tailwind-merge@3.6.0

最小使用与主题

import Demo from '@/components/magicui/examples/animated-theme-toggler-demo';
import { ThemeProvider } from 'next-themes';
export default function Example() {
  return <ThemeProvider attribute="class" defaultTheme="system" enableSystem><Demo /></ThemeProvider>;
}

项目须先配置 Tailwind CSS v4、语义颜色变量和 dark 变体。已有 next-themes Provider 时复用它，不要重复嵌套。Next Link 示例需要 Next.js 环境；静态 Vite 项目可保留原生组件代码，并自行将示例的页面链接改为项目路由。部分演示图片、视频和推文依赖网络；示例不包含登录或后端服务。实用指南与示例标签已提供中文，上游详细英文参考及演示数据未宣称全文翻译。

源码参数参考

以下实现签名和类型从本地固定版本源码生成。保留可选属性、原生继承类型、联合分支和 never 限制；不会将其他设计系统的 API 混入。forwardRef 实现中的 ref 属于 React 引用，不是新增业务属性。此区域是原始类型参考，不是上游说明的全文翻译。

AnimatedThemeToggler({
  className,
  duration = 400,
  variant,
  fromCenter = false,
  theme,
  onThemeChange,
  ...props
}: AnimatedThemeTogglerProps)

export type TransitionVariant =
  | "circle"
  | "square"
  | "triangle"
  | "diamond"
  | "hexagon"
  | "rectangle"
  | "star"

interface AnimatedThemeTogglerProps extends React.ComponentPropsWithoutRef<"button"> {
  duration?: number
  variant?: TransitionVariant
  /** When true, the transition expands from the viewport center instead of the button center. */
  fromCenter?: boolean
  /**
   * Controlled theme value. When provided, the parent owns persistence
   * (e.g. `next-themes`) and this component will not write to localStorage.
   */
  theme?: "light" | "dark"
  /** Called on toggle. Pair with `theme` for controlled usage. */
  onThemeChange?: (theme: "light" | "dark") => void
}

源码中的解构默认值

只列出直接写在参数或 props 解构中的默认表达式。条件表达式、运行时主题和其他计算值请结合源码；这里不是全部行为的默认值清单。

// AnimatedThemeToggler
duration = 400

// AnimatedThemeToggler
fromCenter = false

原生与外部类型

以下外部类型仍由 React 或资源自身依赖定义，没有手工展开为虚构属性。实际可用类型以安装版本的 TypeScript 检查为准。

React.ComponentPropsWithoutRef<"button">