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, imperative API. It is recommended that you initialize ToastManager in your app via app.config.globalProperties to allow you to access it on any component instance inside your application.

// main.ts

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

const app = createApp()

// Available inside any component template in the application, and also on 'this' of any component instance
app.config.globalProperties.$toaster = new ToastManager({
  // you can also override the default value of following properties while initializing ToastManager
  id: 'custom-id', // default: 'toaster-container'
  timeout: 500, // default: 5000
  appearance: 'success', // default: 'info'
  zIndex: 92929, // default: 10000
})

For TypeScript, you should also augment the global property in your vue declaration file

import { ToastManager } from '@kong/kongponents'

declare module 'vue' {
  interface ComponentCustomProperties {
    $toaster: typeof ToastManager
  }
}

Once ToastManager is added as a global property, you can access it's methods via this.$toaster if using the Vue Options API.

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

or within the setup() function in your component

<script setup lang="ts">
import { getCurrentInstance } from 'vue'

const $toaster = getCurrentInstance()?.appContext.config.globalProperties.$toaster

const showToast = (name: string) => {
  $toaster.open(`Wow, ${name} is looking toasty!`)
}

NOTE

Using getCurrentInstance is a replacement of Vue 2's Vue.prototype which is no longer present in Vue 3. As with anything global, this should be used sparingly.

If a global property conflicts with a component’s own property, the component's own property will have higher priority.

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 toasters by calling this.$toaster.toasters. Click the buttons below to watch the state change

  []

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

  {{ toasters }}
</template>

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

const toasters = ref<Toast>([])

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