goey-toast

goey-toast

Framer Motion のアニメーション（ピル → ブロブ → ピル）を使用し、Sonner をベースに構築された、形状が変化する React トーストコンポーネントです。このスキルを使ってパッケージをインストールし、任意の React プロジェクトで正しい使用コードを記述できます。

使用する場面

• React アプリ（React >= 18）にトースト／通知 UI を追加する場合。
• ユーザーが「goey-toast」や「gooey toast」と言及した場合、またはアニメーション付き／形状が変化するトーストを求めている場合。
• 標準の sonner トーストを gooey 版に置き換える場合。

インストール

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

ピア依存関係（ホストアプリに存在する必要があります）：

パッケージ	バージョン
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 にラッパーをインストールし、依存関係も自動でインストールします。

トーストを表示するために必要な2つの手順

1. <GooeyToaster /> をアプリのルート付近に一度だけマウントします。
2. エントリーポイントでスタイルシートを一度だけインポートします。 インポートしない場合、トーストはスタイルなしで表示されます。

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	ブロブのスタイル設定
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 /> の主な props

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 トースト

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' を忘れると、トーストはスタイルなしで表示されます。最もよくある不具合です。
• <GooeyToaster /> はルート付近に一度だけマウントする必要があります。
• update() には、作成時の呼び出しで返されたものと同じ id が必要です。
• framer-motion はピア依存関係です。明示的にインストールしてください。
• v0.2.x との後方互換エイリアス（GoeyToaster、goeyToast）もありますが、二重の o を使う名前（GooeyToaster、gooeyToast）を推奨します。

参考資料

• ライブデモとドキュメント：https://goey-toast.vercel.app
• npm：https://www.npmjs.com/package/goey-toast