Toasts

Toast component provides lightweight notifications displayed in the corner of the page. It supports a functional API (toast.success(), toast.error(), etc.) without requiring template declarations.

Note

Before using Toasts, you must place <TToastContainer /> in your app entry (e.g., App.vue). This component uses <Teleport to="body"> and accepts placement and teleportTo props.

Functional API

Import the toast object and call methods directly — no template needed.

Show Code

<script setup lang="ts">
import { toast } from '@gulcc/tabler-vue'

toast.success('Operation completed!')
toast.error('An error occurred.')
toast.warning('Low disk space.')
toast.info('New update available.')
</script>

<template>
  <button class="btn btn-success" @click="toast.success('Success')">Success</button>
  <button class="btn btn-danger" @click="toast.error('Error')">Error</button>
  <button class="btn btn-warning" @click="toast.warning('Warning')">Warning</button>
  <button class="btn btn-info" @click="toast.info('Info')">Info</button>
</template>

Custom Toast

Use toast.show() to customize title, color, icon, and auto-close duration.

Show Code

<script setup lang="ts">
import { toast } from '@gulcc/tabler-vue'

toast.show('This is a custom notification', {
  title: 'Notification Title',
  color: 'primary',
  duration: 3000, // auto-close after 3 seconds
})
</script>

<template>
  <button class="btn btn-primary" @click="toast.show('Message', { title: 'Title', duration: 3000 })">
    Show Custom Toast
  </button>
</template>

Persistent Toast

Set duration: 0 to keep the toast visible until the user manually closes it.

Show Code

<script setup lang="ts">
import { toast } from '@gulcc/tabler-vue'

toast.show('This toast will not auto-dismiss', {
  title: 'Persistent',
  duration: 0, // never auto-close
})
</script>

Toast with Icon

Pass an icon component from @tabler/icons-vue via the icon option.

Show Code

<script setup lang="ts">
import { toast } from '@gulcc/tabler-vue'
import { IconCheck } from '@tabler/icons-vue'

toast.show('Operation completed', {
  title: 'Result',
  color: 'success',
  icon: IconCheck,
})
</script>

Clear All Toasts

Call toast.clear() to immediately remove all active toasts.

Show Code

<script setup lang="ts">
import { toast } from '@gulcc/tabler-vue'

// Show multiple toasts
toast.success('Toast 1')
toast.info('Toast 2')
toast.warning('Toast 3')

// Clear all at once
toast.clear()
</script>

Bare Style

Toasts without a title or avatar automatically render in "bare" style: no toast-header, close button floating in the top-right corner of the body.

<button class="btn btn-outline-dark" @click="toast.show('A simple toast without header bar.')">
  Show Bare Toast
</button>

Important Style

Enable the important option to render toasts with a solid color background and white text, matching the Alert component's "Important" style. Ideal for critical system notifications.

Show Code

<script setup lang="ts">
import {toast} from '@gulcc/tabler-vue'

// Important info
toast.show('Scheduled maintenance tonight at 02:00, expected to last 2 hours.', {
  title: 'Maintenance Notice',
  color: 'info',
  duration: 0,
  important: true,
  icon: IconInfoCircle,
})

// Important error
toast.show('Database connection failed. Some features are unavailable!', {
  title: 'Critical Error',
  color: 'danger',
  duration: 0,
  important: true,
  icon: IconAlertCircle,
})

// Important success (using shortcut method)
toast.success('System upgrade completed. All services are back to normal.', {
  important: true,
  duration: 0,
})
</script>

Hover Pause

When the mouse enters a toast, the auto-close timer pauses; when the mouse leaves, the timer resumes. This gives users enough time to read the content.

<button class="btn btn-primary" @click="toast.success('Hover to pause the timer.', { duration: 3000 })">
  Show Test Toast (3s)
</button>

Placement

Use setToastPlacement() to set the global default position, or pass placement in toast.show() options to override individual toasts.

Show Code

<script setup lang="ts">
import { toast, setToastPlacement } from '@gulcc/tabler-vue'

// Global setting
setToastPlacement('bottom-right')

// Per-toast override
toast.info('This toast appears at top-left', { placement: 'top-left' })
toast.info('This toast appears at bottom-right', { placement: 'bottom-right' })
</script>

Chat-style Toasts

Use avatar, sender, and timestamp options to create chat-message style toasts. When avatar is set, the toast header automatically switches to an avatar + sender + timestamp layout.

Show Code

<script setup lang="ts">
import { toast } from '@gulcc/tabler-vue'

// Simple chat — with avatar, sender, timestamp
toast.show('Hello, world! This is a toast message.', {
  avatar: '/public/avatar.png',
  sender: 'Mallory Hulme',
  timestamp: '11 mins ago',
  duration: 0,
})

// Cookie notice — using bodyHtml to render action buttons
toast.show('', {
  avatar: '/public/avatar.png',
  sender: 'Mallory Hulme',
  timestamp: '11 mins ago',
  duration: 0,
  bodyHtml: 'Our site uses cookies. By continuing to use our site, you agree to our Cookie Policy.<div class="mt-2 pt-2 border-top"><a href="#" class="btn btn-primary btn-sm">I understand</a></div>',
})
</script>

API

toast Object Methods

Method	Parameters	Returns	Description
toast.show()	(message: string, options?: ToastOptions)	string	Show a custom toast, returns the toast ID
toast.success()	(message: string, options?: ToastOptions)	string	Show a success toast (green)
toast.error()	(message: string, options?: ToastOptions)	string	Show an error toast (red)
toast.warning()	(message: string, options?: ToastOptions)	string	Show a warning toast (yellow)
toast.info()	(message: string, options?: ToastOptions)	string	Show an info toast (blue)
toast.remove()	(id: string)	void	Remove a toast by ID
toast.clear()	—	void	Clear all toasts

ToastOptions

Property	Type	Default	Description
title	string	—	Toast title
color	TablerColor	Semantic color	Color variant, e.g. 'success', 'danger'
icon	Component	—	Icon component (from @tabler/icons-vue)
duration	number	5000	Auto-close delay (ms). 0 disables auto-close
placement	ToastPlacement	'top-right'	Toast placement, overrides the global default
closable	boolean	true	Show close button
avatar	string	—	Avatar image URL (switches to chat-style header)
sender	string	—	Sender name (chat-style header)
timestamp	string	—	Timestamp text (chat-style header)
bodyHtml	string	—	Body HTML content (rendered via v-html)
important	boolean	false	Important style (solid background + white text)

TToastContainer Props

Property	Type	Default	Description
placement	ToastPlacement	'top-right'	Container placement
teleportTo	string	'body'	Teleport target selector

ToastPlacement Type

Value	Description
'top-right'	Top-right corner (default)
'top-left'	Top-left corner
'bottom-right'	Bottom-right corner
'bottom-left'	Bottom-left corner
'top-center'	Centered at top
'bottom-center'	Centered at bottom