Toast API Reference

useToast Composable

The useToast composable provides all methods and state management for the toast notification system.

Import

import { useToast } from '@/composables/useToastComposable'

Methods

Notification Methods

Method	Parameters	Returns	Description
success(message, options?)	message: string, options?: object	notification	Show success notification
error(message, options?)	message: string, options?: object	notification	Show error notification (persistent by default)
warning(message, options?)	message: string, options?: object	notification	Show warning notification
info(message, options?)	message: string, options?: object	notification	Show info notification
showToast(options)	options: object	notification	Show custom notification with full options

Management Methods

Method	Parameters	Description
removeNotification(notification)	notification: object	Remove specific notification
clearAll()	-	Remove all notifications

Configuration Methods

Method	Parameters	Description
setPosition(position)	position: string	Set toast container position
setOffset(x, y)	x: number, y: number	Set container offset in rem units
setDefaultTimeout(timeout)	timeout: number	Set default auto-dismiss timeout
setMaxNotifications(max)	max: number | null	Set maximum number of notifications

Options Object

showToast Options

Property	Type	Default	Description
type	string	'info'	Notification type: 'success', 'error', 'warning', 'info'
primaryMessage	string	required	Main message text
secondaryMessage	string	null	Optional secondary message
timeout	number	config.defaultTimeout	Auto-dismiss timeout in milliseconds
isPersistent	boolean	false	Whether notification persists until manually closed
showCloseButton	boolean	true	Whether to show close button
icon	string	null	Custom icon HTML string (SVG recommended)
position	string	config.position	Override position for this notification (uses global config if not provided)
offset	object	config.offset	Override offset for this notification { x: number, y: number } in rem units

Convenience Method Options

All convenience methods (success, error, warning, info) accept an optional options object with the following properties:

Property	Type	Default	Description
secondaryMessage	string	null	Optional secondary message
timeout	number	config.defaultTimeout	Auto-dismiss timeout (error defaults to persistent)
isPersistent	boolean	false	Override persistence (error is persistent by default)
showCloseButton	boolean	true	Whether to show close button
icon	string	auto	Custom icon (defaults to type-specific icon)
position	string	config.position	Override position for this notification
offset	object	config.offset	Override offset for this notification { x: number, y: number }

State Properties

Computed Properties

Property	Type	Description
notifications	ComputedRef<Array>	Reactive array of current notifications
config	ComputedRef<Object>	Current configuration object
hasNotifications	ComputedRef<boolean>	Whether there are active notifications
notificationCount	ComputedRef<number>	Number of active notifications

Position Options

Position	Description
'top-left'	Top left corner
'top'	Top center
'top-right'	Top right corner
'bottom-left'	Bottom left corner
'bottom'	Bottom center
'bottom-right'	Bottom right corner (default)

Default Configuration

{
  position: 'bottom-right',
  offset: { x: 1, y: 1 }, // rem units
  defaultTimeout: 5000,   // milliseconds
  maxNotifications: null  // defaults to 5 per position if not set
}

Note: When maxNotifications is null, the system defaults to 5 notifications per position. Setting it to a number limits notifications per position to that value.

Usage Examples

Basic Usage

import { useToast } from '@/composables/useToastComposable'

const { success, error, warning, info } = useToast()

// Simple notifications
success('Data saved successfully!')
error('Failed to save data')
warning('Changes not saved')
info('New version available')

With Options

const { success, error } = useToast()

// With secondary message
success('Profile updated', {
  secondaryMessage: 'Changes will be visible immediately'
})

// Custom timeout
error('Connection failed', {
  secondaryMessage: 'Please check your internet connection',
  timeout: 10000
})

// Per-notification position override
success('Saved!', {
  position: 'top-right',
  offset: { x: 2, y: 2 }
})

Custom Notifications

const { showToast } = useToast()

showToast({
  type: 'success',
  primaryMessage: 'Custom notification',
  secondaryMessage: 'With custom icon',
  timeout: 8000,
  isPersistent: false,
  icon: `<svg>...</svg>`
})

Configuration

const { setPosition, setOffset, setMaxNotifications } = useToast()

// Configure toast system
setPosition('top-right')
setOffset(2, 1.5)
setMaxNotifications(5)

State Access

import { watch } from 'vue'
import { useToast } from '@/composables/useToastComposable'

const { notifications, hasNotifications, notificationCount } = useToast()

// Watch for notifications
watch(hasNotifications, (hasToasts) => {
  if (hasToasts) {
    console.log(`${notificationCount.value} notifications active`)
  }
})

// Access all notifications
console.log(notifications.value) // Array of notification objects

Component Usage

OToast Component

The OToast component should be placed once in your application:

<template>
  <div id="app">
    <!-- Your app content -->
    
    <!-- Toast notifications -->
    <OToast />
  </div>
</template>

Props

The OToast component accepts no props - all configuration is done through the useToast composable.

Events

The component doesn't emit events - all interaction is handled through the composable.

Default Icons

The composable includes built-in SVG icons for each type:

• Success: Green checkmark
• Error: Red X in circle
• Warning: Orange warning triangle
• Info: Blue info circle

Custom icons can be provided as HTML strings (SVG recommended) through the icon option.

TypeScript Support

interface ToastOptions {
  type?: 'success' | 'error' | 'warning' | 'info'
  primaryMessage: string
  secondaryMessage?: string
  timeout?: number
  isPersistent?: boolean
  showCloseButton?: boolean
  icon?: string
}

interface ToastConfig {
  position: string
  offset: { x: number; y: number }
  defaultTimeout: number
  maxNotifications: number | null
}

Notification Object Structure

Each notification object contains:

Property	Type	Description
id	string	Unique identifier (UUID v4)
type	string	Notification type
primaryMessage	string	Main message text
secondaryMessage	string | null	Optional secondary message
iconRef	string	Icon HTML string
showCloseButton	boolean	Whether close button is shown
timeout	number	Auto-dismiss timeout
isPersistent	boolean	Whether notification persists
notificationClass	Array	CSS classes applied to notification
position	string	Position for this notification
offset	object	Offset for this notification { x: number, y: number }
createdAt	number	Timestamp when notification was created
shouldRemove	boolean	Internal flag for animation-based removal

Notes

• Error notifications are persistent by default and require manual dismissal
• The composable uses global state - all instances share the same notifications
• UUID v4 (from uuid package) is used for notification IDs to ensure uniqueness
• Notifications are automatically removed when timeout expires (unless persistent)
• The component handles rem to pixel conversion for positioning
• Notifications are grouped by position and displayed in separate containers
• Bottom positions (bottom, bottom-left, bottom-right) use reverse order for proper stacking
• When maxNotifications limit is exceeded per position, oldest notifications are removed first
• Per-notification position and offset override global configuration

Dependencies

The Toast component depends on:

• useToastComposable composable for state management
• uuid package (v4) for generating unique notification IDs
• convertRemToPixels inject for responsive positioning (optional, falls back to computed rem conversion)
• Vue 3 with Composition API