NuxtStart Logo

NuxtStart

Composables

useToastMessage

Display toast notifications with pre-configured styles for error, success, and info messages.

The useToastMessage composable provides helper functions to display toast notifications with consistent styling. It wraps Nuxt UI's useToast with pre-configured colors and icons for common notification types.

Basic Usage

<script setup lang="ts">
const { errorToast, successToast, infoToast } = useToastMessage()

async function saveData() {
  try {
    await $fetch('/api/data', { method: 'POST' })
    successToast({ title: 'Saved successfully' })
  } catch (error) {
    errorToast({ title: 'Failed to save', description: error.message })
  }
}
</script>

<template>
  <UButton label="Save" @click="saveData" />
</template>

Return Value

The composable returns an object with three toast functions:

  • errorToast(options) - Display error toast with red color and alert icon
  • successToast(options) - Display success toast with green color and check icon
  • infoToast(options) - Display info toast with blue color and info icon

All functions accept the same options parameter (see below).

Toast Options

Each toast function accepts an options object with the following properties (extends Nuxt UI's ToastProps except color):

PropertyTypeRequiredDescription
titlestringNoThe main toast message
descriptionstringNoSecondary message displayed below the title
iconstringNoCustom icon (defaults: i-lucide-circle-alert for error, i-lucide-check for success, i-lucide-info for info)
timeoutnumberNoAuto-dismiss delay in milliseconds
actionsToastAction[]NoArray of action buttons
callback() => voidNoFunction called when toast is clicked

Examples

Error Notifications

layers/01.base/app/composables/useToastMessage.ts
const { errorToast } = useToastMessage()

// Simple error
errorToast({ title: 'Something went wrong' })

// With description
errorToast({
  title: 'Failed to delete item',
  description: 'You do not have permission to delete this item.',
})

// Custom icon
errorToast({
  title: 'Connection lost',
  icon: 'i-lucide-wifi-off',
})

Success Notifications

const { successToast } = useToastMessage()

// Simple success
successToast({ title: 'Changes saved' })

// With auto-dismiss
successToast({
  title: 'Account created',
  description: 'Welcome to the platform!',
  timeout: 5000,
})

Info Notifications

const { infoToast } = useToastMessage()

infoToast({
  title: 'New update available',
  description: 'Click here to refresh.',
  callback: () => window.location.reload(),
})

With Actions

const { errorToast } = useToastMessage()

errorToast({
  title: 'Failed to load data',
  actions: [{
    label: 'Retry',
    click: async () => {
      await refreshNuxtData()
    },
  }],
})

API Error Handling

const { errorToast, successToast } = useToastMessage()

async function updateProfile(data: ProfileData) {
  try {
    await $fetch('/api/profile', {
      method: 'PATCH',
      body: data,
    })
    successToast({ title: 'Profile updated' })
  } catch (error) {
    errorToast({
      title: 'Update failed',
      description: error.statusMessage || 'An error occurred',
    })
  }
}

Notes

  • The color property is pre-configured for each toast type and cannot be overridden. Use the appropriate function (errorToast, successToast, or infoToast) for the desired color scheme.
  • You can override the default icon by passing a custom icon property. Use Iconify icon names prefixed with i-, such as i-lucide-alert-triangle or i-heroicons-exclamation-circle.

useSearchableRoutes

Generate searchable route items for command palette from your app's route configuration with automatic filtering and permission checks.

useVersionUpdated

Detect when a new version of the application is available and notify users to refresh.

Copyright © 2026