AisToast

AisToast displays a brief, non-critical message in a way that attracts the user’s attention without interrupting the current task. Toasts are displayed around a container's periphery and are dismissed with a click or after a specified duration. By default, AisToast uses AisAlert to display the message and the useAisToast composable to build message objects. Developers may customize the look-and-feel of the toast by using the display slot.

AisToast and useAisToast are designed such that the component is decoupled from how its messages are stored and manipulated. Many applications will want an app-wide messaging system where AisToast is configured on the layout and backed by a global Pinia store. In this case, components can import the store, initialize the composable, and write messages the layout will automatically render. In other cases, like the examples on this page, the toast component, message array, and composable will be located together.

Introduction

Explore the example below to get a feel for AisToast. By default, the component will display messages as secondary alerts in the bottom-right corner of the browser window. AisToast can display multiple messages, which will stack. All messages will share the same placement. Details like variant, icon, and duration are specified on a per-message basis.

<template>
  <div class="relative">
    <Teleport to="body">
      <AisToast
        :messages="messages"
        :placement="selectedPlacement"
        @dismiss="toast.remove" />
    </Teleport>

    <div class="grid grid-cols-1 md:grid-cols-3 gap-6">
      <AisField label="Title" description="Optional" class="col-span-full">
        <AisInput v-model="title"/>
      </AisField>

      <AisField label="Message" required class="col-span-full">
        <AisTextarea :rows="2" v-model="message"/>
      </AisField>

      <AisField label="Placement">
        <AisSelect
          :options=placements
          v-model="selectedPlacement">
        </AisSelect>
      </AisField>

      <AisField label="Variant">
        <AisSelect
          :options=variants
          v-model="selectedVariant">
        </AisSelect>
      </AisField>

      <AisField label="Duration" description="In milliseconds">
        <AisInput v-model="duration" placeholder="5000" />
      </AisField>

      <AisButtonBar class="col-span-full">
        <AisButton variant="primary" icon="new" fast hover click @click="addMessage">
          Add Message
        </AisButton>

        <AisCheckbox v-model="dismissible">
          Dismissible
        </AisCheckbox>
      </AisButtonBar>
    </div>
  </div>
</template>

<script setup>
  import {ref, computed} from 'vue'
  import {AisButtonBar} from '@ais-public/ais-components'
  import {AisButton} from '@ais-public/ais-components'
  import {useAisToast} from '@ais-public/ais-components'
  import {AisToast} from '@ais-public/ais-components'
  import {AisSelect} from '@ais-public/ais-components'
  import {AisField} from '@ais-public/ais-components'
  import {AisCheckbox} from '@ais-public/ais-components'
  import {AisInput} from '@ais-public/ais-components'
  import {AisTextarea} from '@ais-public/ais-components'
  import {placements} from "@/components/toast/toast-utils"
  import {variants} from "@ais-public/ais-components/util/variants-util"

  const messages = ref([])
  const toast = useAisToast(messages)

  const title = ref('')
  const message = ref('The quick brown fox jumps over the lazy dog.')
  const dismissible = ref(true)
  const selectedPlacement = ref('top-center')
  const selectedVariant = ref('secondary')
  const duration = ref(undefined)
  const sequence = ref(0)

  const options = computed(() => {
    return {
      title: title.value,
      message: message.value,
      variant: selectedVariant.value,
      dismissible: dismissible.value,
      duration: duration.value
    }
  })

  const addMessage = () => {
    sequence.value++
    let msg = `#${sequence.value}. ${message.value}`
    toast.message(msg, options.value)
  }
</script>

Props

messages

messages is a required prop that takes an array of AisUserMessage objects to be displayed by AisToast. useAisToast exposes the message(msg, options) function (and related variants) to create the objects. The remove(uuid) function can be used to remove a message when it is dismissed or its duration expires. See the AisUserMessage definition below for details.

import {AisVariant} from "@/types/AisVariant";

export interface AisUserMessage {
    uuid?: string,
    title?: string,
    message?: string,
    details?: string[],
    variant?: AisVariant,
    icon?: any,
    dismissible?: boolean,
    duration?: number,
    dismissLabel?: string,
}

placement

This prop dictates the placement of the toast messages. By default, toasts are positioned relative to the browser window, but that can be changed with the position prop. The valid placements are top-right, top-center, top-left, bottom-right, bottom-center, and bottom-left.

position

postion dictates the type of CSS positioning used for AisToast. fixed is the default value, which positions the toasts relative to the browser window. Note the first example uses Vue's <Teleport> component to attach the toast group directly to the document <body>. This is a best-practice when using fixed positioning.

Use absolute to position the toast messages relative to an ancestor. This allows toasts to be used in a smaller more targeted part of your interface as illustrated in the example below. See absolute positioning in the TailwindCSS docs for details. Absolute positioning will position the element relative to its first ancestor with relative positioning.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin ac ultricies sapien, id bibendum ex. Integer vitae mi varius, tincidunt lacus sit amet, elementum enim. Sed interdum mauris in ultricies consectetur. Praesent mollis ex ut placerat lacinia. Integer nec ligula pharetra, semper lorem id, ultricies purus. Nunc sollicitudin mollis erat, vel suscipit erat sodales eu. Nulla vitae laoreet ligula, at blandit purus. Curabitur ut erat eu tellus ultrices molestie at vel neque. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris porta nibh egestas diam tempus placerat. Proin accumsan auctor risus, non congue lacus mollis non. Proin sed magna ut dui vulputate malesuada in in enim. Donec ultricies nibh ac pretium cursus. Integer at sapien tempus, rutrum tellus non, rutrum sem. Curabitur id metus lacus.

Placement

Top-LeftTop-CenterTop-RightBottom-LeftBottom-CenterBottom-Right

<script setup lang="ts">
  import {ref} from 'vue'
  import {useAisToast} from '@ais-public/ais-components'
  import {placements} from "@/components/toast/toast-utils"
  import {AisToast} from '@ais-public/ais-components'
  import {AisButtonBar} from '@ais-public/ais-components'
  import {AisButton} from '@ais-public/ais-components'
  import {AisSelect} from '@ais-public/ais-components'
  import {AisField} from '@ais-public/ais-components'

  const messages = ref([])
  const toast = useAisToast(messages, { variant: "info" })
  const selectedPlacement = ref('top-right')

</script>

<template>
  <div class="relative">
    <AisToast
      :messages="messages"
      position="absolute"
      :placement="selectedPlacement"
      margin="m-0"
      z-index="z-20"
      @dismiss="toast.remove"
    />
    <div class="grid gap-4">
      <div>
        <p class="leading-normal">
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Proin ac ultricies sapien, id bibendum ex. Integer
          vitae mi varius, tincidunt lacus sit amet, elementum enim. Sed interdum mauris in ultricies consectetur. Praesent
          mollis ex ut placerat lacinia. Integer nec ligula pharetra, semper lorem id, ultricies purus. Nunc sollicitudin mollis erat,
          vel suscipit erat sodales eu. Nulla vitae laoreet ligula, at blandit purus. Curabitur ut erat eu tellus ultrices molestie at vel neque.
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris porta nibh egestas diam tempus placerat. Proin
          accumsan auctor risus, non congue lacus mollis non. Proin sed magna ut dui vulputate malesuada in in enim. Donec
          ultricies nibh ac pretium cursus. Integer at sapien tempus, rutrum tellus non, rutrum sem. Curabitur id metus lacus.
        </p>
      </div>
      <AisButtonBar>
        <AisField label="Placement" label-mode="sr-only">
          <AisSelect
            :options=placements
            v-model="selectedPlacement">
          </AisSelect>
        </AisField>

        <AisButton variant="primary" icon="new" fast hover click
                   @click="toast.message('The quick brown fox jumped over the lazy dog.')">
          Add Message
        </AisButton>
      </AisButtonBar>
    </div>
  </div>
</template>

Additional props

See the Component Reference for additional props to customize AisToast details.

Events

@dismiss

The @dismiss event is triggered when a user closes a specific toast message. The event payload is the uuid of the message, which can be passed to the remove() function exposed by useAisToast.

Slots

display

Use the display slot to customize the markup for the toast message. The current message object is passed to the slot along with the triggerDismissEvent method.

<template>
  <div>
    <AisToast
      :messages="messages"
      placement="top-right"
      @dismiss="toast.remove"
    >
      <template #display="{message, triggerDismissEvent}">
        <AisBox
          variant="default" rounded="xl"
          class="flex justify-between items-center gap-3 shadow-md"
        >
          <div>{{ message.message }}</div>
          <AisButton
            variant='secondary' size="xs" rounded="lg"
            @click="triggerDismissEvent(message.uuid)"
          >
            Dismiss
          </AisButton>
        </AisBox>
      </template>
    </AisToast>

    <AisButtonBar>
      <AisButton variant="primary" icon="new" fast hover click @click="addMessage">
        Custom Toast
      </AisButton>
    </AisButtonBar>
  </div>
</template>

<script setup>
import { ref } from 'vue'
import { AisButton } from '@ais-public/ais-components'
import { AisButtonBar } from '@ais-public/ais-components'
import { useAisToast } from '@ais-public/ais-components'
import { AisToast } from '@ais-public/ais-components'
import { AisBox } from '@ais-public/ais-components'

const messages = ref([])
const toast = useAisToast(messages)

const addMessage = () => {
  toast.message('The quick brown fox jumped over the lazy dog.')
}
</script>

Component Reference

Props

Property	Type(s)	Required	Default	Description	Deprecated
margin	String		'm-0 sm:m-4'	Margin around the toast group - use Tailwind classes	false
messages	Array			Array of active toast messages	false
placement	ToastPlacement		'top-center'	Placement of the toast group relative to its container	false
position	ToastPosition		'fixed'	TailwindCSS position class	false
width	String		'w-screen sm:w-auto max-w-full md:max-w-fit lg:max-w-lg xl:max-w-lg'	TailwindCSS classes dictating the width of the toast group	false
zIndex	String		'z-toast'	TailwindCSS z-index class. Defaults to z-toast, the top layer of the library scale	false

Slots

Name	Scoped	Description
display		Scoped slot for custom rendering the toast message

Events

Event	Arguments	Description
dismiss	UUID string - of the toast to remove	Emitted when a toast is clicked to dismiss