useToasts

A set of methods to manipulate an array of dismissible toasts.

Import

import useToasts from '@leaflink/stash/useToasts';

Usage

Call the composable in your component and push a toast to the toasts array.

<script setup>
  import useToasts from '@leaflink/stash/useToasts';

  const toasts = useToasts({ timeout: 3000 });

  // displays an "info" toast
  const toastId = toasts.info('I am a toast!');

  // logs the currently active/visible toasts
  console.log(toasts.active);

  // removes an active/visible toast
  toasts.remove(toastId);

  // removes all toasts
  toasts.removeAll();
</script>

Preventing duplicate toasts

It is possible to set a group for the toast. A group name ensures only one toast with the same group and status is visible at any given time. This is useful for preventing the same toast from being spammed accidentally.

<script setup>
  import useToasts from '@leaflink/stash/useToasts';

  const toasts = useToasts();

  toasts.info("I'm a toast", { group: 'test' });
  toasts.info("I'm a toast", { group: 'test' });
</script>

The following option will only show one toast at a time, even if triggered multiple times:

<vp-example class="tw-flex tw-gap-4 tw-items-center">
  <Button color="blue" @click="toasts.info('I\'m a toast', { group: 'test' })">
    Show toast
  </Button>
</vp-example>

Toasts with different statuses can use the same group and still display concurrently: ```vue
<script setup>
  import useToasts from '@leaflink/stash/useToasts';

  const toasts = useToasts();

  toasts.info("I'm a toast", { group: 'test' });
  toasts.success("I'm a toast", { group: 'test' });
</script>

Variants

The toasts object returned by useToasts() contains methods to display specific variants of the Toast component:

<Button @click="toasts.success('Success toast')">Success</Button>
<Button @click="toasts.info('Info toast')">Info</Button>
<Button @click="toasts.error('Error toast')">Error</Button>
<Button @click="toasts.warning('Warning toast')">Warning</Button>

HTML Content

Toasts can also receive a render function instead of a string.

<Button @click="toasts.info(() => h('strong', 'New notification'))">
  Show toast
</Button>

You can also render a Vue component by passing it to the render function.

<template>
  <strong>New Notification</strong><br />
  <strong>[Seller]</strong> has <strong>accepted</strong> the <a>order 1234</a>
</template>

<Button @click="toasts.success(() => h(MyToastContent))">
  Show toast
</Button>

If you need to pass down a template string, the component can safely parse it and inject it to the dom.

<Button
  @click="
    toasts.success(
      '<strong>New Notification</strong><br /><strong>[Seller]</strong> has <strong>accepted</strong> the <a>order 1234</a>',
    )
  "
>
    Show toast
  </Button>

The toast component uses a v-html directive to render the string passed as content. Before rendering it, the

component sanitizes the string to avoid a potential XSS attacks. :::

Duration

By default, a toast will be displayed for 5000 milliseconds before being dismissed. To specify another duration, you can pass the timeout option:

Globally

<script setup>
  const toasts = useToasts({ timeout: 3000 });
</script>

<template>
  <Button @click="toasts.info('I will dismiss in 3 seconds')"> Show toast </Button>
</template>

Locally

<script setup>
  const toasts = useToasts();
</script>

<template>
  <Button @click="toasts.info('I will dismiss in 3 seconds', { timeout: 3000 })"> Show toast </Button>
</template>

Options informed locally will take precedence over global options. :::

Permanent

Toasts can also be displayed indefinitely by setting the timeout property to false:

<Button @click="toasts.success('Click me to dismiss', { timeout: false })">
  Show toast
</Button>

Config

interface ToastOptions {
  /**
   * The timeout in milliseconds before the toast is automatically dismissed. If set to `false`, the toast will persist until the user clicks on it.
   * @default DEFAULT_TIMEOUT
   */
  timeout?: number | boolean;
  /**
   * A group name ensures only one toast from the same group is visible at any given time.
   */
  group?: string;
}