Vue Sonner

https://github.com/xiaoluoboding/vue-sonner
Admin
An opinionated and customizable toast component for Vue.js, offering a smooth swipe-to-dismiss...
Tokens:38,839
Snippets:295
Trust Score:9.9
License:MIT
Update:1 week ago
Show doc for...
Tokens:
Raw
### Install project dependencies with npm install

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/test/README.md

Installs all project dependencies listed in package.json. Run this once at the start of the project setup.

```sh
npm install
```

--------------------------------

### Examples

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toaster.md

Usage examples for the Toaster component, including configuration with props and multiple scoped toasters.

```APIDOC
## Examples

```vue
<template>
  <Toaster
    position="top-right"
    theme="dark"
    rich-colors
    :visible-toasts="9"
    :toast-options="{
      unstyled: true,
      classes: {
        toast: 'bg-blue-400',
        title: 'text-red-400'
      }
    }"
  />
</template>

<script lang="ts" setup>
import { Toaster, toast } from 'vue-sonner'
import 'vue-sonner/style.css'
</script>
```

Multiple scoped toasters:

```vue
<template>
  <Toaster id="main" position="top-right" />
  <Toaster id="sidebar" position="bottom-left" />
</template>

<script lang="ts" setup>
toast('Global')
toast('Sidebar-only', { toasterId: 'sidebar' })
</script>
```
```

--------------------------------

### Install vue-sonner with pnpm or yarn

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Install the vue-sonner library in your project either with pnpm or yarn.

```bash
pnpm install vue-sonner
or
yarn add vue-sonner
```

--------------------------------

### toast.promise usage examples

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Three usage examples: basic loading/success/error handling, awaiting settlement with unwrap, and the extended result form with a custom success object.

```typescript
// basic – loading → success/error automatically
const p = toast.promise(
  () => new Promise((resolve) => setTimeout(resolve, 2000)),
  {
    loading: 'Loading',
    success: (data: any) => 'Success',
    error: (data: any) => 'Error'
  }
)
```

```typescript
// awaiting settlement with unwrap
try {
  await toast.promise(fetchData(), {
    loading: 'Fetching…',
    success: 'Done',
    error: 'Failed'
  })?.unwrap()
} catch (err) {
  console.error('request failed', err)
}
```

```typescript
// extended result form
toast.promise(save(), {
  loading: 'Saving…',
  success: (data) => ({
    message: 'Saved',
    description: `id: ${data.id}`,
    duration: 5000
  }),
  error: 'Could not save'
})
```

--------------------------------

### VueSonner UMD plugin install()

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/umd.md

The default export of the UMD build is a Vue 3 plugin whose install() method sets up $toast, registers the Toaster component, provides toast for Composition API, and assigns window.toast. This is the main export from src/plugin.umd.ts.

```ts
const VueSonner = {
  /**
   * Install function used by Vue.use()
   * @param {App} app - The Vue application instance
   */
  install(app) {
    // Make $toast globally available in Options API
    app.config.globalProperties.$toast = toast

    // Register the <Toaster /> component globally
    app.component('Toaster', Toaster)

    // Provide toast for Composition API usage
    app.provide('toast', toast)

    // assign toast to window
    if (typeof window !== 'undefined') {
      window.toast = toast
    }
  }
}

// UMD-friendly single export for Vue.use(VueSonner)
export default VueSonner
```

--------------------------------

### VueSonner.install(app)

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/umd.md

The install function of the VueSonner plugin, called when the plugin is used with Vue.use(). It sets up global properties, registers the Toaster component, provides toast for injection, and assigns toast to window.

```APIDOC
## VueSonner.install(app)

### Description
Installs the VueSonner plugin into a Vue application. It makes the toast object available globally via `$toast`, registers the `<Toaster />` component, provides toast for Composition API injection, and assigns toast to `window.toast` in browsers.

### Method
install

### Parameters
- **app** (App) - Required - The Vue application instance.

### Behavior
- Sets `app.config.globalProperties.$toast` to the toast object.
- Registers the `Toaster` component globally.
- Provides `toast` via `app.provide('toast', toast)`.
- Assigns `window.toast` to the toast object if `window` is defined.

### Example
```ts
const VueSonner = {
  install(app) {
    app.config.globalProperties.$toast = toast
    app.component('Toaster', Toaster)
    app.provide('toast', toast)
    if (typeof window !== 'undefined') {
      window.toast = toast
    }
  }
}
```
```

--------------------------------

### Run end-to-end tests with Playwright

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/test/README.md

Install Playwright browsers on first run, then build the project before testing on CI. Run the end-to-end tests, optionally scoped to Chromium or a specific file.

```sh
# Install browsers for the first run
npx playwright install

# When testing on CI, must build the project first
npm run build

# Runs the end-to-end tests
npm run test:e2e
# Runs the tests only on Chromium
npm run test:e2e -- --project=chromium
# Runs the tests of a specific file
npm run test:e2e -- --project=chromium
```

--------------------------------

### useIsDocumentHidden usage example

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/hooks.md

Shows how to import and use the useIsDocumentHidden hook in a component.

```TypeScript
import { useIsDocumentHidden } from 'vue-sonner/src/packages/hooks'

const { isDocumentHidden } = useIsDocumentHidden()
```

--------------------------------

### cn usage example

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/hooks.md

Demonstrates the cn helper with a call that returns 'a b'.

```TypeScript
cn('a', undefined, 'b', '') // 'a b'
```

--------------------------------

### Compile and hot-reload for development with npm run dev

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/test/README.md

Starts the Vite development server with hot-reload for the Vue 3 project.

```sh
npm run dev
```

--------------------------------

### ExternalToast usage example

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/types.md

Example usage of ExternalToast options in a toast call. Shows how to set id for dedupe/update, description, duration, action, onDismiss, position, and classes.

```ts
toast('Event', {
  id: 42,                    // ExternalToast.id — dedupe/update target
  description: 'Details',    // ExternalToast.description
  duration: Infinity,        // ExternalToast.duration
  action: { label: 'Undo', onClick: (e) => {} },
  onDismiss: (t) => console.log(t.id),
  position: 'top-center',
  classes: { toast: 'my-toast' }
})
```

--------------------------------

### Composition API injection: inject('toast')

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/umd.md

The toast object is provided via `app.provide('toast', toast)` during installation, allowing Composition API components to inject it using `inject('toast')`.

```APIDOC
## Composition API injection: inject('toast')

### Description
In Composition API, the toast object can be injected into any component below the app root using `inject('toast')`. This provides access to toast methods like `error`.

### Usage Example
```ts
import { inject } from 'vue'
const toast = inject('toast')
toast?.error('Something went wrong!')
```
```

--------------------------------

### CDN browser usage with VueSonner

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/umd.md

CDN usage example: load Vue 3 and vue-sonner from unpkg, create an app, use the VueSonner plugin, and call toast.success globally. The toast object is available even outside Vue.

```html
<script src="https://unpkg.com/vue@3"></script>
<script src="https://unpkg.com/vue-sonner"></script>
<script>
  const app = Vue.createApp({})
  app.use(VueSonner)
  app.mount('#app')

  // Toast usage anywhere (even outside Vue)
  toast.success('This works globally!')
</script>
```

--------------------------------

### nuxt.config.ts with vueSonner module

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/nuxt.md

Example Nuxt configuration that enables the module and sets `css` to `false` to disable automatic stylesheet inclusion. The default is `true`.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['vue-sonner/nuxt'],
  vueSonner: {
    css: false // true by default to include css file
  }
})
```

--------------------------------

### Using Toaster and $toast in app.vue

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/nuxt.md

Example usage in an `app.vue` SFC. The `Toaster` component is auto-registered as client-only, and the `$toast` function is accessed via `useNuxtApp()` in the script setup.

```vue
<!-- app.vue -->
<template>
  <div>
    <Toaster position="top-right" />
    <button @click="$toast('My first toast')">Render a toast</button>
  </div>
</template>

<script setup lang="ts">
  const { $toast } = useNuxtApp()
</script>
```

--------------------------------

### Set keyboard focus hotkey with hotkey prop

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Overrides the default keyboard shortcut (⌥/alt + T) for focusing the toast area by providing an array of event.code values. This example uses 'KeyC'.

```html
<Toaster hotkey="['KeyC']" />
```

--------------------------------

### toast.dismiss usage example

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Shows how to dismiss a single toast by its id and dismiss all toasts by calling dismiss() without arguments.

```typescript
const toastId = toast('Event has been created')
toast.dismiss(toastId) // one toast
toast.dismiss()        // all toasts
```

--------------------------------

### Custom toast with progress bar: script setup

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast-item.md

Registers a custom toast component with `toast.custom`, wrapping it with `markRaw` to avoid Vue reactivity overhead. Sets a duration of 5000 ms and a `testId` of 'progress'.

```vue
<script lang="ts" setup>
import { markRaw } from 'vue'
import ProgressToast from './ProgressToast.vue'

toast.custom(markRaw(ProgressToast), { duration: 5000, testId: 'progress' })
</script>
```

--------------------------------

### Show promise toast with loading, success, and error states

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Starts in a loading state and updates automatically after the promise resolves or fails. The success and error callbacks can use the promise result or error.

```ts
toast.promise(() => new Promise((resolve) => setTimeout(resolve, 2000)), {
  loading: 'Loading',
  success: (data: any) => 'Success',
  error: (data: any) => 'Error'
})
```

--------------------------------

### ToastState singleton export

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Exports the module-level singleton ToastState, shared by all toast.* calls and every <Toaster /> or useVueSonner subscription. The id counter starts at 1.

```ts
export const ToastState = new Observer()   // src/packages/state.ts:332
```

--------------------------------

### Configure vue-sonner Nuxt module with css: false

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/configuration.md

Configures the vue-sonner Nuxt module. Setting css to false prevents vue-sonner/style.css from being appended to nuxt.options.css, allowing manual stylesheet import for headless or Tailwind setups.

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['vue-sonner/nuxt'],
  vueSonner: {
    css: false
  }
})
```

--------------------------------

### assignOffset: generate CSS offset custom properties

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/hooks.md

The function accepts desktop and mobile offsets, each either a number, string, or partial object. It returns CSS custom properties: --offset-* for desktop and --mobile-offset-* for mobile, converting numbers to px strings and falling back to VIEWPORT_OFFSET (24px) or MOBILE_VIEWPORT_OFFSET (16px) for missing keys or undefined arguments. The example call shows the resulting flat object for a string desktop offset and a mobile object with only bottom set.

```ts
export function assignOffset(
  defaultOffset: ToasterProps['offset'],
  mobileOffset: ToasterProps['mobileOffset']
) {
  const styles = {} as CSSProperties

  ;[defaultOffset, mobileOffset].forEach((offset, index) => {
    const isMobile = index === 1
    const prefix = isMobile ? '--mobile-offset' : '--offset'
    const defaultValue = isMobile ? MOBILE_VIEWPORT_OFFSET : VIEWPORT_OFFSET

    function assignAll(offset: string | number) {
      ;['top', 'right', 'bottom', 'left'].forEach((key) => {
        styles[`${prefix}-${key}`] =
          typeof offset === 'number' ? `${offset}px` : offset
      })
    }

    if (typeof offset === 'number' || typeof offset === 'string') {
      assignAll(offset)
    } else if (typeof offset === 'object') {
      ;['top', 'right', 'bottom', 'left'].forEach((key) => {
        if (offset[key as keyof typeof offset] === undefined) {
          styles[`${prefix}-${key}`] = defaultValue
        } else {
          styles[`${prefix}-${key}`] =
            typeof offset[key as keyof typeof offset] === 'number'
              ? `${offset[key as keyof typeof offset]}px`
              : offset[key as keyof typeof offset]
        }
      })
    } else {
      assignAll(defaultValue)
    }
  })

  return styles
}
```

```ts
assignOffset('80px', { bottom: 12 })
// { '--offset-top': '80px', '--offset-right': '80px', '--offset-bottom': '80px', '--offset-left': '80px',
//   '--mobile-offset-top': '16px', '--mobile-offset-right': '16px', '--mobile-offset-bottom': '12px',
//   '--mobile-offset-left': '16px' }
```

--------------------------------

### useVueSonner composable and usage example

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/hooks.md

The composable subscribes to the ToastState singleton inside a watchEffect, so the subscription is automatically torn down on unmount (onInvalidate). It is the Composition-API counterpart of rendering <Toaster /> — it does not mount any DOM; it only exposes state. The returned activeToasts is a reactive array of currently active toast objects; dismiss notifications remove items, updates merge by id, and new toasts are prepended.

```ts
export function useVueSonner(): {
  activeToasts: Ref<ToastT[]>
} {
  const activeToasts = ref<ToastT[]>([])

  watchEffect((onInvalidate) => {
    const unsubscribe = ToastState.subscribe((toast) => {
      if ('dismiss' in toast && toast.dismiss) {
        activeToasts.value = activeToasts.value.filter((t) => t.id !== toast.id)
        return
      }

      nextTick(() => {
        const existingToastIndex = activeToasts.value.findIndex(
          (t) => t.id === toast.id
        )
        if (existingToastIndex !== -1) {
          const updatedToasts = [...activeToasts.value]
          updatedToasts[existingToastIndex] = {
            ...updatedToasts[existingToastIndex],
            ...toast
          }
          activeToasts.value = updatedToasts
        } else {
          activeToasts.value = [toast, ...activeToasts.value]
        }
      })
    })

    onInvalidate(() => {
      unsubscribe()
    })
  })

  return {
    activeToasts
  }
}
```

```ts
import { useVueSonner } from 'vue-sonner'

const { activeToasts } = useVueSonner()

watch(activeToasts, (toasts) => {
  console.log(toasts.map((t) => t.id))
})
```

--------------------------------

### Type-check, compile and minify for production with npm run build

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/test/README.md

Builds the project for production. This command type-checks, compiles, and minifies the output.

```sh
npm run build
```

--------------------------------

### toast.message, toast.success, toast.error, toast.info, toast.warning, toast.loading

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Documentation for the six toast creation methods: toast.message, toast.success, toast.error, toast.info, toast.warning, and toast.loading. All share the same signature and return the toast id.

```APIDOC
## toast.message(message, data?)

### Description
Creates a toast with the default type. Accepts a message and optional data.

### Method
Function call

### Signature
`message = (message: titleT, data?: ExternalToast) => number | string`

### Parameters
- **message** (titleT) - Required - The message to display in the toast.
- **data** (ExternalToast) - Optional - Additional toast configuration data.

### Returns
- The toast id (`number | string`) from `Observer.create`.

### Error Handling
This method does not throw.

### Example
```ts
toast.message('Hello')
```

## toast.success(message, data?)

### Description
Creates a success toast. Accepts a message and optional data.

### Method
Function call

### Signature
`success = (message: titleT, data?: ExternalToast) => number | string`

### Parameters
- **message** (titleT) - Required - The message to display in the toast.
- **data** (ExternalToast) - Optional - Additional toast configuration data.

### Returns
- The toast id (`number | string`) from `Observer.create`.

### Error Handling
This method does not throw.

### Example
```ts
toast.success('Event has been created')
```

## toast.error(message, data?)

### Description
Creates an error toast. Accepts a message and optional data.

### Method
Function call

### Signature
`error = (message: titleT, data?: ExternalToast) => number | string`

### Parameters
- **message** (titleT) - Required - The message to display in the toast.
- **data** (ExternalToast) - Optional - Additional toast configuration data.

### Returns
- The toast id (`number | string`) from `Observer.create`.

### Error Handling
This method does not throw.

### Example
```ts
toast.error('Event has not been created')
```

## toast.info(message, data?)

### Description
Creates an info toast. Accepts a message and optional data.

### Method
Function call

### Signature
`info = (message: titleT, data?: ExternalToast) => number | string`

### Parameters
- **message** (titleT) - Required - The message to display in the toast.
- **data** (ExternalToast) - Optional - Additional toast configuration data.

### Returns
- The toast id (`number | string`) from `Observer.create`.

### Error Handling
This method does not throw.

### Example
```ts
toast.info('Information')
```

## toast.warning(message, data?)

### Description
Creates a warning toast. Accepts a message and optional data.

### Method
Function call

### Signature
`warning = (message: titleT, data?: ExternalToast) => number | string`

### Parameters
- **message** (titleT) - Required - The message to display in the toast.
- **data** (ExternalToast) - Optional - Additional toast configuration data.

### Returns
- The toast id (`number | string`) from `Observer.create`.

### Error Handling
This method does not throw.

### Example
```ts
toast.warning('Warning')
```

## toast.loading(message, data?)

### Description
Creates a loading toast. Accepts a message and optional data. Loading toasts never auto-close; they stay on screen until updated, dismissed, or their duration elapses.

### Method
Function call

### Signature
`loading = (message: titleT, data?: ExternalToast) => number | string`

### Parameters
- **message** (titleT) - Required - The message to display in the toast.
- **data** (ExternalToast) - Optional - Additional toast configuration data.

### Returns
- The toast id (`number | string`) from `Observer.create`.

### Error Handling
This method does not throw. Loading toasts do not auto-close; the timer is skipped for `toast.type === 'loading'`.

### Example
```ts
toast.loading('Uploading...')
// later, replace the loading toast in place:
toast.success('Uploaded', { id: sameId })
```
```

--------------------------------

### Run end-to-end tests with pnpm test:e2e --ui

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Navigate to the test directory and run the end-to-end tests with the UI mode.

```bash
cd ./test
```

```bash
cd ./test
pnpm test:e2e --ui
```

--------------------------------

### Toast with description and action

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Creates a toast with a description, an action button, and a custom duration.

```typescript
// with description and action
toast('Event has been created', {
  description: 'Monday, January 3rd at 6:00pm',
  action: {
    label: 'Undo',
    onClick: () => console.log('Undo')
  },
  duration: 10000
})
```

--------------------------------

### toast methods implementation (message, error, success, info, warning, loading)

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Shows the shared implementation of all six toast methods. Each method calls this.create with the same message and data parameters, differing only in the type argument passed to create. Use these methods to trigger toasts with the corresponding type.

```typescript
message = (message: titleT, data?: ExternalToast) => {
  return this.create({ ...data, message, type: 'default' })
}
error = (message: titleT, data?: ExternalToast) => {
  return this.create({ ...data, type: 'error', message })
}
success = (message: titleT, data?: ExternalToast) => {
  return this.create({ ...data, type: 'success', message })
}
info = (message: titleT, data?: ExternalToast) => {
  return this.create({ ...data, type: 'info', message })
}
warning = (message: titleT, data?: ExternalToast) => {
  return this.create({ ...data, type: 'warning', message })
}
loading = (message: titleT, data?: ExternalToast) => {
  return this.create({ ...data, type: 'loading', message })
}
```

--------------------------------

### toast(component, options?)

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Displays a custom Vue component as a toast with default styling.

```APIDOC
## toast(component, options?)

### Description
Displays a custom Vue component as a toast while maintaining default styling. The component should be passed using `markRaw` to avoid reactivity overhead.

### Method
`toast`

### Parameters
- **component** (Component) - Required - A Vue component to render as the toast content.
- **options** (object) - Optional - Configuration options (same as `toast`).

### Request Example
```html
<script lang="ts" setup>
  import { defineComponent, h, markRaw } from 'vue'

  const CustomDiv = defineComponent({
    setup() {
      return () =>
        h('div', {
          innerHTML: 'A custom toast with unstyling'
        })
    }
  })

  toast(markRaw(CustomDiv))
</script>
```

### Response
No return value is documented.
```

--------------------------------

### toast.success(message, options?)

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Displays a success toast with a checkmark icon.

```APIDOC
## toast.success(message, options?)

### Description
Displays a success toast with a checkmark icon in front of the message.

### Method
`toast.success`

### Parameters
- **message** (string) - Required - The message to display.
- **options** (object) - Optional - Configuration options for the toast (same as `toast`).

### Request Example
```ts
toast.success('Event has been created')
```

### Response
No return value is documented.
```

--------------------------------

### toast()

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Documentation for the toast function and its toasterId option for scoping toasts to specific Toaster components.

```APIDOC
## toast(message, data?)

### Description
Creates a toast notification. The `toasterId` option in the data object allows the toast to target a specific `<Toaster>` component with a matching `id` prop.

### Parameters
#### Data Object (ExternalToast)
- **toasterId** (string) - Optional - The ID of the target `<Toaster>` component. If provided, only the `<Toaster>` with this `id` will display the toast. If omitted, the toast will only be shown by `<Toaster>` components without an `id` prop.

### Request Example
```ts
toast('Scoped toast', { toasterId: 'sidebar' })
```

### Related Components
- `<Toaster id="sidebar" />` - The component that renders the toast, with an `id` prop to match the `toasterId`.
```

--------------------------------

### Custom toast with progress bar: ProgressToast.vue component

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast-item.md

Defines the custom toast component used in the example. It accepts `onCloseToast` and `isPaused` props, displays an uploading message with a pause indicator, and includes a close button.

```vue
<!-- ProgressToast.vue -->
<script lang="ts" setup>
defineProps<{ onCloseToast: () => void; isPaused: boolean }>()
</script>
<template>
  <div class="p-4 rounded bg-white shadow">
    Uploading… <span :class="{ 'opacity-50': isPaused }">⏸</span>
    <button @click="onCloseToast">Close</button>
  </div>
</template>
```

--------------------------------

### Show default toast with optional description

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

The basic toast call displays a message. To include a description, pass an options object with a 'description' property as the second argument.

```ts
toast('Event has been created')
```

```ts
toast('Event has been created', {
  description: 'Monday, January 3rd at 6:00pm'
})
```

--------------------------------

### Style all toasts with toastOptions

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Applies global styling to all toasts via the toastOptions prop, setting inline styles, a class, and a description class.

```html
<Toaster
  :toastOptions="{
    style: { background: 'red' },
    class: 'my-toast',
    descriptionClass: 'my-toast-description'
  }"
/>
```

--------------------------------

### Vue plugin default export

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/index.md

The default export is a standard Vue 3 plugin that only performs app.component('Toaster', Toaster) — global registration of the <Toaster /> component. It does not install $toast, provide dependency injection, or touch window. Import with `import VueSonner from 'vue-sonner'` and use with `app.use(VueSonner)`.

```ts
const plugin: Plugin = {
  install(app) {
    app.component('Toaster', Toaster)
  }
}

export default plugin
```

--------------------------------

### toast.promise

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/types.md

Documentation for the `toast.promise` API, including its options object and related types.

```APIDOC
## `toast.promise`

### Description
Creates a toast for a promise, showing loading, success, and error states based on the promise's settlement.

### Parameters
#### PromiseData<ToastData>
- **loading** (`string | Component`) - Optional - Shows a 'loading' toast while pending; omitting it means no toast until settlement and `toast.promise` returns only `{ unwrap }`.
- **success** (`PromiseTResult<ToastData> | PromiseTExtendedResult<ToastData>`) - Optional - Message/component/function for fulfillment. The function receives the resolved value.
- **error** (`PromiseTResult | PromiseTExtendedResult`) - Optional - Message/component/function for rejection (or a resolved-but-failed `Response`/`Error`, see `Observer.promise`).
- **description** (`PromiseTResult`) - Optional - Optional description; when a function, it receives the same argument as `success`/`error`.
- **finally** (`() => void | Promise<void>`) - Optional - Always invoked on settle.
- *(all remaining `ExternalToast` fields)* - Optional - Applied to the loading toast on creation.

### Types
#### `PromiseTExtendedResult<Data>`
```ts
export type PromiseTExtendedResult<Data = any> =
  | PromiseIExtendedResult
  | ((data: Data) => PromiseIExtendedResult | Promise<PromiseIExtendedResult>)
```
The `success`/`error` handler may itself be an extended result or a function returning one (possibly async).

#### `PromiseTResult<Data>`
```ts
export type PromiseTResult<Data = any> =
  | string
  | Component
  | ((data: Data) => Component | string | Promise<Component | string>)
```
The `success`/`error`/`description` promise handlers: a plain string, a component, or a (possibly async) function of the settled value.

#### `PromiseExternalToast`
```ts
export type PromiseExternalToast = Omit<ExternalToast, 'description'>
```
`ExternalToast` minus `description` — the base of `PromiseData`.

#### `PromiseData<ToastData>`
```ts
export type PromiseData<ToastData = any> = PromiseExternalToast & {
  loading?: string | Component
  success?: PromiseTResult<ToastData> | PromiseTExtendedResult<ToastData>
  error?: PromiseTResult | PromiseTExtendedResult
  description?: PromiseTResult
  finally?: () => void | Promise<void>
}
```
The options object of `toast.promise`. See [toast.md](api-reference/toast.md#toastpromisepromise-data).
```

--------------------------------

### Build vue-sonner in dev mode with watch

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Build the vue-sonner library in lib mode with watch enabled, so changes are automatically rebuilt for testing.

```bash
pnpm build:dev
```

--------------------------------

### toast(message, options?)

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Displays a basic toast notification with optional description and action button.

```APIDOC
## toast(message, options?)

### Description
Displays a basic toast notification. Accepts a message string or a Vue component, and an optional options object to customize the toast.

### Method
`toast`

### Parameters
- **message** (string | Component) - Required - The message to display or a Vue component to render.
- **options** (object) - Optional - Configuration options for the toast.
  - **description** (string) - Optional - A description to display below the message.
  - **action** (object) - Optional - An action button configuration.
    - **label** (string) - Required - The label for the action button.
    - **onClick** (function) - Required - Callback function invoked when the action button is clicked.

### Request Example
```ts
toast('Event has been created')
```

With custom description:
```ts
toast('Event has been created', {
  description: 'Monday, January 3rd at 6:00pm'
})
```

With action:
```ts
toast('Event has been created', {
  action: {
    label: 'Undo',
    onClick: () => console.log('Undo')
  }
})
```

### Response
No return value is documented.
```

--------------------------------

### toast.loading(message, data?)

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Creates a loading toast with the given message and optional data. Returns the toast id.

```APIDOC
## toast.loading(message, data?)

### Description
Creates a loading toast with the given message and optional data. Returns the toast id.

### Method
Function call

### Signature
```ts
toast.loading(message: titleT, data?: ExternalToast): number | string
```

### Parameters
- `message` (`(() => string | Component) | string | Component`) - Required - Toast title: a string, a Vue `Component`, or a function returning either.
- `data` (`ExternalToast`) - Optional - Per-toast options.

### Returns
- `number | string` - The toast id.
```

--------------------------------

### toast.info(message, data?)

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Creates an info toast with the given message and optional data. Returns the toast id.

```APIDOC
## toast.info(message, data?)

### Description
Creates an info toast with the given message and optional data. Returns the toast id.

### Method
Function call

### Signature
```ts
toast.info(message: titleT, data?: ExternalToast): number | string
```

### Parameters
- `message` (`(() => string | Component) | string | Component`) - Required - Toast title: a string, a Vue `Component`, or a function returning either.
- `data` (`ExternalToast`) - Optional - Per-toast options.

### Returns
- `number | string` - The toast id.
```

--------------------------------

### toast.promise(promise, options)

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Displays a toast that tracks a promise and updates on resolution or rejection.

```APIDOC
## toast.promise(promise, options)

### Description
Displays a toast that starts in a loading state and automatically updates after the provided promise resolves or fails. The success and error messages can be functions that receive the promise's result or error.

### Method
`toast.promise`

### Parameters
- **promise** (Promise) - Required - The promise to track.
- **options** (object) - Required - Configuration options.
  - **loading** (string) - Required - Message to display while the promise is pending.
  - **success** (string | function) - Required - Message or function returning a message when the promise resolves. The function receives the resolved data.
  - **error** (string | function) - Required - Message or function returning a message when the promise rejects. The function receives the error.

### Request Example
```ts
toast.promise(() => new Promise((resolve) => setTimeout(resolve, 2000)), {
  loading: 'Loading',
  success: (data: any) => 'Success',
  error: (data: any) => 'Error'
})
```

### Response
No return value is documented.
```

--------------------------------

### Show success toast

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Displays a checkmark icon in front of the message.

```ts
toast.success('Event has been created')
```

--------------------------------

### Style individual toast with toast() options

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Styles an individual toast when calling toast(), applying inline style, class, and description class.

```ts
toast('Event has been created', {
  style: {
    background: 'red'
  },
  class: 'my-toast',
  descriptionClass: 'my-toast-description'
})
```

--------------------------------

### Set theme to dark with theme prop

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Sets the toast theme to dark using the theme prop. The default theme is light.

```html
<Toaster theme="dark" />
```

--------------------------------

### Configure Toaster with options and custom classes

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toaster.md

Configures a Toaster with position, theme, rich colors, visible toast limit, and custom classes. Requires importing Toaster and toast from 'vue-sonner' and the style.css.

```vue
<template>
  <Toaster
    position="top-right"
    theme="dark"
    rich-colors
    :visible-toasts="9"
    :toast-options="{
      unstyled: true,
      classes: {
        toast: 'bg-blue-400',
        title: 'text-red-400'
      }
    }"
  />
</template>

<script lang="ts" setup>
import { Toaster, toast } from 'vue-sonner'
import 'vue-sonner/style.css'
</script>
```

--------------------------------

### cn helper implementation

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/hooks.md

A tiny clsx-style helper that filters out falsy class tokens and joins the rest with spaces. Used throughout Toast.vue and Toaster.vue for merging class props.

```TypeScript
export function cn(...classes: (string | undefined)[]) {
  return classes.filter(Boolean).join(' ')
}
```

--------------------------------

### Enable rich colors with richColors prop

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Makes error and success states more colorful by adding the richColors prop.

```html
<Toaster richColors />
```

--------------------------------

### toast.warning(message, data?)

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Creates a warning toast with the given message and optional data. Returns the toast id.

```APIDOC
## toast.warning(message, data?)

### Description
Creates a warning toast with the given message and optional data. Returns the toast id.

### Method
Function call

### Signature
```ts
toast.warning(message: titleT, data?: ExternalToast): number | string
```

### Parameters
- `message` (`(() => string | Component) | string | Component`) - Required - Toast title: a string, a Vue `Component`, or a function returning either.
- `data` (`ExternalToast`) - Optional - Per-toast options.

### Returns
- `number | string` - The toast id.
```

--------------------------------

### toast object assembly with Object.assign

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Shows how the `toast` object is created by combining a base callable function with named methods and getters. It is bound to the `ToastState` observer singleton.

```typescript
const basicToast = toastFunction

const getHistory = () => ToastState.toasts
const getToasts = () => ToastState.getActiveToasts()

// We use `Object.assign` to maintain the correct types as we would lose them otherwise
export const toast = Object.assign(
  basicToast,
  {
    success: ToastState.success,
    info: ToastState.info,
    warning: ToastState.warning,
    error: ToastState.error,
    custom: ToastState.custom,
    message: ToastState.message,
    promise: ToastState.promise,
    dismiss: ToastState.dismiss,
    loading: ToastState.loading
  },
  {
    getHistory,
    getToasts
  }
)
```

--------------------------------

### Runtime plugin providing $toast

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/nuxt.md

The runtime plugin that provides the full `toast` object on the Nuxt app context. It is registered as client-only and makes `$toast` available via `useNuxtApp()`.

```ts
import { toast } from 'vue-sonner'
import { defineNuxtPlugin } from 'nuxt/app'

export default defineNuxtPlugin(() => {
  return {
    provide: {
      toast
    }
  }
})
```

--------------------------------

### useVueSonner

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/hooks.md

Composable hook that exposes the active toasts state. It subscribes to the ToastState singleton and returns a reactive ref of active toast objects.

```APIDOC
## useVueSonner

### Description
Returns a reactive array of currently active toast objects. Subscribes to the ToastState singleton inside a watchEffect, automatically tearing down the subscription on unmount. It does not mount any DOM; it only exposes state.

### Signature
```ts
export function useVueSonner(): {
  activeToasts: Ref<ToastT[]>
}
```

### Returns
- **activeToasts** (`Ref<ToastT[]>`) - Reactive array of currently active toast objects. Dismiss notifications remove items; updates merge by id. New toasts are prepended.

### Example
```ts
import { useVueSonner } from 'vue-sonner'

const { activeToasts } = useVueSonner()

watch(activeToasts, (toasts) => {
  console.log(toasts.map((t) => t.id))
})
```
```

--------------------------------

### toast(message, data?)

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Creates a default toast with the given message and optional data. Returns the toast id, which can be used with toast.dismiss().

```APIDOC
## toast(message, data?)

### Description
Creates a default toast with the given message and optional data. Returns the toast id, which can be used with toast.dismiss().

### Method
Function call

### Signature
```ts
toast(message: titleT, data?: ExternalToast): number | string
```

### Parameters
- `message` (`(() => string | Component) | string | Component`) - Required - Toast title: a string, a Vue `Component`, or a function returning either.
- `data` (`ExternalToast`) - Optional - Per-toast options; most notably `data.id` is honored, otherwise an auto-incrementing id (`toastsCounter`) is assigned. `type` is forced to `'default'` unless `data.id`-dedup update path applies.

### Returns
- `number | string` - The toast id. Pass it to `toast.dismiss(id)` to remove the toast programmatically.

### Behavior Notes
- If `data?.id` is falsy, a fresh `toastsCounter++` id is used.
- If a toast with the same id already exists in `ToastState.toasts`, `create` **updates** it instead of adding a new one.
- If the id was previously dismissed, it is removed from `dismissedToasts` so it can be shown again.

### Example
```ts
// basic
const id = toast('Event has been created')
toast.dismiss(id)

// with description and action
toast('Event has been created', {
  description: 'Monday, January 3rd at 6:00pm',
  action: {
    label: 'Undo',
    onClick: () => console.log('Undo')
  },
  duration: 10000
})

// persistent toast
toast('Event has been created', { duration: Infinity })
```
```

--------------------------------

### Show toast with action button

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/README.md

Adds an action button to the toast. The 'action' object contains a 'label' for the button text and an 'onClick' handler.

```ts
toast('Event has been created', {
  action: {
    label: 'Undo',
    onClick: () => console.log('Undo')
  }
})
```

--------------------------------

### Using $toast from useNuxtApp

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/nuxt.md

Shows how to access the `$toast` function provided by the plugin in any component or composable. The `$toast` function is the full `toast` object from `vue-sonner`.

```ts
const { $toast } = useNuxtApp()
$toast('Hello from Nuxt')
```

--------------------------------

### Slots

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toaster.md

All slots are forwarded into every <Toast /> item. Customize toast icons by providing slot templates.

```APIDOC
## Slots

All slots are forwarded into every `<Toast />` item (defaults come from `src/packages/Toaster.vue:41-136`):

| Slot name | Default content | Used for toast type |
|-----------|-----------------|---------------------|
| `close-icon` | `CloseIcon` (`src/packages/assets/CloseIcon.vue`) | Close button glyph |
| `loading-icon` | `LoaderIcon` with `:visible="toast.type === 'loading'"` (`src/packages/assets/Loader.vue`) | `loading` |
| `success-icon` | `SuccessIcon` | `success` |
| `error-icon` | `ErrorIcon` | `error` |
| `warning-icon` | `WarningIcon` | `warning` |
| `info-icon` | `InfoIcon` | `info` |

```vue
<Toaster>
  <template #success-icon>
    <MySuccessIcon />
  </template>
  <template #error-icon>
    <MyErrorIcon />
  </template>
</Toaster>
```

Custom-component toasts render their own markup and do not use these slots.
```

--------------------------------

### Basic toast usage with dismiss

Source: https://github.com/xiaoluoboding/vue-sonner/blob/main/_autodocs/api-reference/toast.md

Creates a basic toast and dismisses it using the returned id.

```typescript
// basic
const id = toast('Event has been created')
toast.dismiss(id)
```
Tokens:
Raw