goey-toast

goey-toast

一个基于 Sonner 构建的黏糊变形 React toast 组件，使用 Framer Motion 动画（药丸 → blob → 药丸）。使用此技能可在任何 React 项目中安装此软件包并编写正确的使用代码。

适用场景

• 在 React 应用（React >= 18）中添加 toast / 通知 UI。
• 用户提到“goey-toast”“gooey toast”，或希望使用动画 / 变形 toast。
• 将原始 sonner toast 替换为黏糊变体。

安装

npm install goey-toast react react-dom framer-motion

Peer 依赖（必须存在于宿主应用中）：

软件包	版本
react	>= 18.0.0
react-dom	>= 18.0.0
framer-motion	>= 10.0.0

shadcn/ui 项目

npx shadcn@latest add https://goey-toast.vercel.app/r/goey-toaster.json

安装位于 components/ui/goey-toaster.tsx 的封装组件，并自动安装依赖。

渲染 toast 的两个必要步骤

1. 在应用根目录附近挂载一次 <GooeyToaster />。
2. **在入口点导入一次样式表。**否则 toast 将不会应用样式。

import { GooeyToaster, gooeyToast } from 'goey-toast'
import 'goey-toast/styles.css' // REQUIRED — import once at app entry

function App() {
  return (
    <>
      <GooeyToaster position="bottom-right" />
      <button onClick={() => gooeyToast.success('Saved!')}>Save</button>
    </>
  )
}

API：gooeyToast

gooeyToast(title, options?)         // default (neutral)
gooeyToast.success(title, options?) // green
gooeyToast.error(title, options?)   // red
gooeyToast.warning(title, options?) // yellow
gooeyToast.info(title, options?)    // blue
gooeyToast.promise(promise, data)   // loading → success/error
gooeyToast.update(id, options)      // update an existing toast in-place
gooeyToast.dismiss(idOrFilter?)     // dismiss one, by type, or all

常用选项（第 2 个参数）

选项	类型	说明
description	ReactNode	字符串或组件主体
action	GooeyToastAction	{ label, onClick, successLabel? }
icon	ReactNode	自定义图标（在 update 中使用 null 可清除）
duration	number	毫秒
id	string | number	稳定 ID（update 所需）
fillColor / borderColor / borderWidth	颜色 / px	Blob 样式
spring / bounce	boolean / number	弹跳范围为 0.05–0.8，默认值为 0.4
preset	'smooth' | 'bouncy' | 'subtle' | 'snappy'	动画预设
showProgress	boolean	倒计时条
showTimestamp	boolean	默认值为 true
onDismiss / onAutoClose	(id) => void	关闭回调

<GooeyToaster /> 主要属性

position（'top-left'|'top-center'|'top-right'|'bottom-left'|'bottom-center'|'bottom-right'，默认值为 'bottom-right'）， theme（'light'|'dark'）、closeButton、showProgress、closeOnEscape、 maxQueue、queueOverflow（'drop-oldest'|'drop-newest'）、dir（'ltr'|'rtl'）、 spring、bounce、preset、swipeToDismiss、showTimestamp、gap、offset。

示例

描述和操作按钮

gooeyToast.info('Share link ready', {
  description: 'Your link has been generated.',
  action: {
    label: 'Copy',
    onClick: () => navigator.clipboard.writeText(url),
    successLabel: 'Copied!', // morphs back to pill after click
  },
})

Promise toast

gooeyToast.promise(saveData(), {
  loading: 'Saving...',
  success: (data) => `Saved ${data.count} items`,
  error: (e) => `Failed: ${String(e)}`,
  description: { success: 'All changes synced.', error: 'Try again later.' },
  action: { error: { label: 'Retry', onClick: () => retry() } },
})

原位更新

const id = gooeyToast('Uploading...', { icon: <Spinner /> })
gooeyToast.update(id, { title: 'Done', type: 'success', icon: null })

按筛选条件关闭

gooeyToast.dismiss(id)                       // one
gooeyToast.dismiss({ type: 'error' })        // all errors
gooeyToast.dismiss({ type: ['error','warning'] })
gooeyToast.dismiss()                         // all

注意事项

• 忘记 import 'goey-toast/styles.css' → toast 不会应用样式。这是最常见的问题。
• <GooeyToaster /> 必须在根目录附近恰好挂载一次。
• update() 需要使用创建调用返回的同一个 id。
• framer-motion 是 peer 依赖，需显式安装。
• v0.2.x 提供向后兼容别名（GoeyToaster、goeyToast）；建议使用名称中有两个 o 的版本（GooeyToaster、gooeyToast）。

参考

• 在线演示和文档：https://goey-toast.vercel.app
• npm：https://www.npmjs.com/package/goey-toast