shadcn-svelte Sonner 组件实战在 Svelte 项目中接入高质量 Toast 通知【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelteSonner 是 shadcn-svelte 提供的一款有主见opinionated的 Toast 通知组件由svelte-sonner驱动是 React 版 Sonner 的 Svelte 移植。本文围绕docs/content/components/sonner.md文档结合仓库源码完整讲解 Sonner 的安装接入、深色模式适配、API 用法toast、toast.success、toast.promise等以及图标定制方案。读完本文你将能在自己的 SvelteKit / Vite 项目中一键接入与 shadcn-svelte 风格统一的 Toast 系统并掌握如何自定义通知图标与主题样式。AboutSonner 组件从何而来Sonner 组件的核心并不在 shadcn-svelte 仓库内部自研而是由第三方库 svelte-sonner 提供——它是 React 生态中由 Emil Kowalski 创作的 Sonner 的 Svelte 移植版。shadcn-svelte 所做的是把该库封装为一个符合自身组件规范、与项目主题变量深度集成的Toaster组件。在仓库中该封装位于 sonner 组件目录sonner.svelteToaster组件本体负责将svelte-sonner的Toaster与项目主题、CSS 变量、图标渲染绑定index.ts统一导出export { default as Toaster } from ./sonner.svelte;这也是所有页面代码中import { Toaster } from $lib/components/ui/sonner/index.js的导入来源。值得强调的是 shadcn-svelte 的经典做法组件源码直接落到你的项目里而不是作为运行时依赖。你复制或通过 CLI 添加进来的sonner.svelte是一份可完全掌控的代码后续任何主题或图标的调整都是对本地文件的修改。安装CLI 命令与手动安装两种方式方式一通过 CLI 安装推荐在项目根目录执行 shadcn-svelte 的 add 命令添加 Sonner 组件npx shadcn-sveltelatest add sonner从 sonner 注册表项 可以看出该命令会同时写入以下devDependenciessvelte-sonner^1.0.7Toast 运行时核心库mode-watcher^1.1.0用于感知系统/手动深色模式见下文主题支持lucide/svelte^0.561.0Toast 默认状态图标成功、错误、警告、信息、加载。随后在根布局中加入Toaster组件建议放在layout.svelte中这样全站所有路由都能触发 Toastscript langts import { Toaster } from $lib/components/ui/sonner/index.js; let { children } $props(); /script Toaster / {render children?.()}第 2 行的导入路径$lib/components/ui/sonner/index.js是 CLI 安装后的默认产物位置第 6 行Toaster /即全局渲染的通知挂载点。注意 Svelte 5 的 runes 语法中子内容需通过children属性 {render children?.()}渲染Toaster /与页面内容并列即可正常工作。方式二手动安装如果你更习惯手动控制依赖可按如下步骤操作安装svelte-sonner为开发依赖pnpm add -D svelte-sonner使用 npm 则为npm install -D svelte-sonner使用 yarn 则为yarn add -D svelte-sonner。将sonner.svelte与index.ts两个文件从 sonner 组件目录 复制进自己项目的$lib/components/ui/sonner/下也可参考 sonner.json 中的files字段内容。在layout.svelte中加入Toaster /代码与上文 CLI 方式完全一致。无论哪种方式接入后都要确保项目已按 shadcn-svelte 规范配置了 Tailwind 与 CSS 变量主题参见 安装指南因为sonner.svelte的样式变量直接引用了主题色变量。主题支持让 Toast 跟随深色模式默认情况下Sonner 会读取用户的系统偏好prefers-color-scheme来决定显示浅色还是深色主题。在 shadcn-svelte 中更推荐的做法是让 Toast 与站点主题保持一致具体有两种方案使用 mode-watchersonner.svelte中通过import { mode } from mode-watcher读取当前主题并把theme{mode.current}传给底层Toaster。mode-watcher 会自动跟随系统偏好同时支持手动切换为强制dark或light。这是 CLI 安装后的默认行为手动传入themeprop如果你不需要深色模式可在使用Toaster themelight /或dark时直接覆盖。关于完整的深色模式接入流程class策略、CSS 变量、mode-watcher 配置等可参考 深色模式文档内含 Svelte 与 Astro 两套方案以及站点入口布局中 mode-watcher 的实际接线方式参见 站点根布局/(layout)/layout.svelte) 相关的模式切换组件。彻底关闭深色模式如果你希望项目完全不支持深色可以卸载mode-watcher并从sonner.svelte中删除themeprop 与相关 import。手动安装时则直接复制组件时不引入 mode-watcher 即可。组件源码解析主题变量与图标渲染CLI 安装后sonner.svelte的关键逻辑如下核心片段script langts import { mode } from mode-watcher; import { Toaster as Sonner, type ToasterProps as SonnerProps } from svelte-sonner; // ...图标导入 let { ...restProps }: SonnerProps $props(); /script Sonner theme{mode.current} classtoaster group style--normal-bg: var(--color-popover); --normal-text: var(--color-popover-foreground); --normal-border: var(--color-border); {...restProps} !-- loading / success / error / info / warning 五个图标 snippet -- /Sonner几个值得注意的实现细节主题变量无缝衔接--normal-bg、--normal-text、--normal-border三个 CSS 变量被映射到 shadcn-svelte 的--color-popover、--color-popover-foreground、--color-border上使 Toast 的外观自动继承 Card/Popover 的皮肤深浅色切换零成本。props 透传let { ...restProps }: SonnerProps $props()配合{...restProps}意味着svelte-sonner的ToasterProps如position、duration、richColors、closeButton等全部可以直接透传到Toaster positiontop-right /无需二次封装。类型安全type ToasterProps as SonnerProps确保 IDE 能给出完整的属性提示与类型检查。图标定制从占位到 lucide 图标在文档站点源码中sonner.svelte使用 IconPlaceholder 组件渲染五种状态图标loading、success、error、info、warning分别对应加载旋转、成功对勾、错误、信息与警告三角。IconPlaceholder 是一个多图标库适配层会根据当前设计系统配置从 lucide、tabler、hugeicons、phosphor、remixicon 等图标库中选取对应图标——这正是文档站演示多图标主题时展示的能力。而对于普通用户2025 年 12 月的 Changelog 更新见下文已把注册表默认实现切换为直接使用lucide/svelte图标五种状态的映射如下状态lucide 图标应用位置loadingLoader2Iconsize-4 animate-spin加载中提示successCircleCheckIcontoast.success()errorOctagonXIcontoast.error()infoInfoIcontoast.info()warningTriangleAlertIcontoast.warning()使用一行代码弹出 Toast在任意组件中引入toast函数即可触发通知script langts import { toast } from svelte-sonner; import { Button } from $lib/components/ui/button/index.js; /scriptButton onclick{() toast(Hello world)}Show toast/Buttontoast是svelte-sonner导出的命令式 API它不依赖组件树层级在事件回调、异步请求、表单提交等任何位置都能调用这也是 Toast 类组件最自然的使用形态。示例五种通知类型与 Promise 场景文档站提供的两个示例组件位于 examples 目录是理解 API 的最佳范本。基础演示带描述与操作按钮sonner-demo.svelte 展示了一条带description描述文本与action操作按钮的 ToastButton variantoutline onclick{() toast(Event has been created, { description: Sunday, December 03, 2023 at 9:00 AM, action: { label: Undo, onClick: () console.info(Undo), }, })} Show Toast /Buttondescription在标题下方显示次要信息适合补充事件详情、错误原因等action渲染一个可点击的按钮如撤销onClick回调中处理业务逻辑。类型演示Default / Success / Info / Warning / Error / Promisesonner-types.svelte 集中展示了全部常用调用方式div classflex flex-wrap gap-2 Button variantoutline onclick{() toast(Event has been created)}Default/Button Button variantoutline onclick{() toast.success(Event has been created)}Success/Button Button variantoutline onclick{() toast.info(Be at the area 10 minutes before the event time)} Info /Button Button variantoutline onclick{() toast.warning(Event start time cannot be earlier than 8am)} Warning /Button Button variantoutline onclick{() toast.error(Event has not been created)}Error/Button Button variantoutline onclick{() { toast.promise{ name: string }( () new Promise((resolve) setTimeout(() resolve({ name: Event }), 2000)), { loading: Loading..., success: (data) ${data.name} has been created, error: Error, } ); }} Promise /Button /div对 Promise 用法的要点说明toast.promise接收一个返回Promise的函数在 pending 阶段显示loading文案resolve 后显示success可基于返回数据拼接文案如示例中根据data.name生成Event has been createdreject 后显示error示例通过泛型toast.promise{ name: string }让success回调中的data获得类型推断该场景非常适合表单提交中 → 提交成功/失败这类异步流程无需手动管理三个状态的切换。Changelog2025-12 图标更新2025-12 Icons最近一次更新2025-12将 Sonner 组件的状态图标切换为lucide图标集。如果你此前安装过旧版本需要按以下方式更新你的sonner.svelte文件文件位于components/ui/sonner.sveltescript langts import CircleCheckIcon from lucide/svelte/icons/circle-check; import InfoIcon from lucide/svelte/icons/info; import Loader2Icon from lucide/svelte/icons/loader-2; import OctagonXIcon from lucide/svelte/icons/octagon-x; import TriangleAlertIcon from lucide/svelte/icons/triangle-alert; import { Toaster as Sonner, type ToasterProps as SonnerProps, } from svelte-sonner; import { mode } from mode-watcher; let { ...restProps }: SonnerProps $props(); /script Sonner theme{mode.current} classtoaster group style--normal-bg: var(--color-popover); --normal-text: var(--color-popover-foreground); --normal-border: var(--color-border); {...restProps} {#snippet loadingIcon()} Loader2Icon classsize-4 animate-spin / {/snippet} {#snippet successIcon()} CircleCheckIcon classsize-4 / {/snippet} {#snippet errorIcon()} OctagonXIcon classsize-4 / {/snippet} {#snippet infoIcon()} InfoIcon classsize-4 / {/snippet} {#snippet warningIcon()} TriangleAlertIcon classsize-4 / {/snippet} /Sonner更新要点新增 5 个图标导入第 2-6 行CircleCheckIcon、InfoIcon、Loader2Icon、OctagonXIcon、TriangleAlertIcon均来自lucide/svelte替换图标 snippet第 22-36 行svelte-sonner通过loadingIcon、successIcon、errorIcon、infoIcon、warningIcon五个命名 snippet 插槽开放图标定制。更新后即由 lucide 图标渲染五种状态其中Loader2Icon保留animate-spin旋转动画该版本对应的完整产物含 devDependencies 声明可在 sonner.json 中查看。如果希望自定义为其他图标库的图标只需替换这五个 snippet 内的组件即可例如换成 Tabler Icons 或 Phosphor 的对应图标。小结Sonner 组件把svelte-sonner的完整能力与 shadcn-svelte 的主题系统缝合在一起通过Toaster /全局挂载、toast命令式 API 触发配合 mode-watcher 自动适配深浅色并允许通过 snippet 插槽自由定制五种状态图标。无论是快速接入npx shadcn-sveltelatest add sonner还是手动安装其源码都直接归属你的项目方便进一步定制。更多细节可查阅 Sonner 组件文档 与 组件源码以及文档站的 Toast 示例 获取可直接复用的代码。【免费下载链接】shadcn-svelteshadcn/ui, but for Svelte. ✨项目地址: https://gitcode.com/GitHub_Trending/sh/shadcn-svelte创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考