Toaster

KToaster a popup notification component. The toaster will close automatically after a set timeout or can be dismissed by clicking on the close icon.

KToaster is used via the ToastManager instance. All rendering is controlled from ToastManager via an intuitive API.

The easiest way to use it is by creating a composable that you can use anywhere in your app. This way you don't have to initialize ToastManager in every component.

// composables/useToaster

import { onBeforeUnmount } from 'vue'
import { ToastManager } from '@kong/kongponents'

export default function useToaster() {
  const toaster = new ToastManager()

  onBeforeUnmount(() => {
    toaster.destroy()
  })

  return { toaster }
}

Once ToastManager instance is initialized, you can use it's methods to show toast messages:

<template>
  <KButton @click="toaster.open({ title: 'Basic Notification', message: 'Detailed message' })">Open Toaster</KButton>
</template>

<script setup lang="ts">
import useToaster from '~/composables/useToaster'

const { toaster } = useToaster()
</script>

or call them from within the setup() function in your component:

<script setup lang="ts">
import useToaster from '~/composables/useToaster'

const { toaster } = useToaster()

const showToast = (name: string) => {
  toaster.open(`Hello ${name}!`)
}
</script>

NOTE

Don't forget to clean up the toaster instance by calling toaster.destroy() in onBeforeUnmount.

Optionally, you can provide options object upon initialization. It takes one parameter:

interface ToasterOptions {
  zIndex?: number // z-index of toast message element
}

const toaster = new ToastManager({ zIndex: 1001 })

NOTE

If you are using Kongponents in SSR mode, it is advised that you only initialize ToastManager on the client side.

Arguments

KToaster is the underlying component rendered by the ToastManager instance, so all component properties are passed down via ToastManager.open() methods' arguments. The accepted argument type is string or object that is instance of Toast.

interface Toast {
  key?: any // optional, unique identifier of a toast
  title?: string
  message?: string
  appearance?: ToasterAppearance
  timeoutMilliseconds?: number
}

title

Notification title.

<KButton @click="toaster.open({ title: 'Notification Title' })">Open Toaster</KButton>

message

The message string that allows for displaying longer strings of text to the user. This prop is good for more detailed messages.

Alternatively, if you provide a string as the only argument to the open() method, it will be treated as message.

<KButton @click="toaster.open({ 
  title: 'Title',
  message: 'Detailed message. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.' })"
>
  Open Toaster
</KButton>
<KButton @click="toaster.open('String will become a message.')" appearance="secondary">Open Toaster</KButton>

appearance

Depending on the nature of notification, you might want to use different appearances. KToaster supports these 5 appearances:

• info (default)
• success
• danger
• warning
• system

toaster.open({ title: 'Warning', appearance: 'warning' })

timeoutMilliseconds

The default timeout, in milliseconds, is 5000 (5 seconds) however you can change this to by passing the timeoutMilliseconds property.

<template>
  <KButton @click="openNotification(toasterOptions)">Open Toaster</KButton>
</template>

<script setup lang="ts">
import type { Toast } from '@kong/kongponents'

const toasterOptions: Toast = {
  appearance: 'success',
  timeoutMilliseconds: 3000,
  title: 'Notification',
  message: 'This toaster has a 3 second timeout'
}

const openNotification = (options: Toast | string) => {
  toaster.open(options)
}
</script>

Toaster State

You can view the current state of active toasts by calling ToastManager.toasts. Click the buttons below to watch the state change

  []

<template>
  <KButton @click="openNotification({ timeoutMilliseconds: 10000, title: 'Info Notification', appearance: 'info' })">
    Open Toaster
  </KButton>

  {{ toasts }}
</template>

<script lang="ts">
import type { Toast } from '@kong/kongponents'

const toasts = ref<Toast>([])

const openNotification = (options: Toast | string): void => {
  toaster.open(options)
  toasts.value = toaster.toasts.value
}
</script>