Toast

A message that appears on the screen to provide feedback on an action.

Anatomy

To set up the toast correctly, you'll need to understand its anatomy and how we name its parts.

Each part includes a data-part attribute to help identify them in the DOM.

Setup

To use the Toast component, create the toast engine using the createToaster function.

This function manages the placement and grouping of toasts, and provides a toast object needed to create toast notification.

const toaster = createToaster({
  placement: 'bottom-end',
  overlap: true,
  gap: 24,
})

Examples

Here's an example of creating a toast using the toast.create method.

import { Toast, Toaster, createToaster } from '@ark-ui/react/toast'
import { XIcon } from 'lucide-react'

const toaster = createToaster({
  placement: 'bottom-end',
  overlap: true,
  gap: 24,
})

export const Basic = () => {
  return (
    <div>
      <button
        type="button"
        onClick={() =>
          toaster.create({
            title: 'Toast Title',
            description: 'Toast Description',
            type: 'info',
          })
        }
      >
        Add Toast
      </button>
      <Toaster toaster={toaster}>
        {(toast) => (
          <Toast.Root key={toast.id}>
            <Toast.Title>{toast.title}</Toast.Title>
            <Toast.Description>{toast.description}</Toast.Description>
            <Toast.CloseTrigger>
              <XIcon />
            </Toast.CloseTrigger>
          </Toast.Root>
        )}
      </Toaster>
    </div>
  )
}

import { Toast, Toaster, createToaster } from '@ark-ui/solid/toast'
import { XIcon } from 'lucide-solid'

export const Basic = () => {
  const toaster = createToaster({
    placement: 'bottom-end',
    gap: 24,
  })

  return (
    <div>
      <button
        type="button"
        onClick={() =>
          toaster.create({
            title: 'Loading!',
            description: 'We are loading something for you. Please wait.',
            type: 'info',
          })
        }
      >
        Add Toast
      </button>
      <Toaster toaster={toaster}>
        {(toast) => (
          <Toast.Root>
            <Toast.Title>{toast().title}</Toast.Title>
            <Toast.Description>{toast().description}</Toast.Description>
            <Toast.CloseTrigger>
              <XIcon />
            </Toast.CloseTrigger>
          </Toast.Root>
        )}
      </Toaster>
    </div>
  )
}

<script setup lang="ts">
import { Toast, Toaster, createToaster } from '@ark-ui/vue/toast'

const toaster = createToaster({ placement: 'bottom-end', overlap: true, gap: 24 })

const createToast = () => {
  toaster.create({
    title: 'Title',
    description: 'Description',
    type: 'info',
  })
}
</script>

<template>
  <button @click="createToast">Create Toast</button>
  <Toaster :toaster="toaster" v-slot="toast">
    <Toast.Root>
      <Toast.Title>{{ toast.title }}</Toast.Title>
      <Toast.Description>{{ toast.description }}</Toast.Description>
      <Toast.ActionTrigger>Action</Toast.ActionTrigger>
      <Toast.CloseTrigger>Close</Toast.CloseTrigger>
    </Toast.Root>
  </Toaster>
</template>

<script lang="ts">
  import { Toast, Toaster, createToaster } from '@ark-ui/svelte/toast'
  import { X } from 'lucide-svelte'

  const toaster = createToaster({
    placement: 'bottom-end',
    overlap: true,
    gap: 24,
  })

  function addToast() {
    toaster.create({
      title: 'Toast Title',
      description: 'Toast Description',
      type: 'info',
    })
  }
</script>

<div>
  <button type="button" onclick={addToast}>Add Toast</button>
  <Toaster {toaster}>
    {#snippet children(toast)}
      <Toast.Root>
        <Toast.Title>{toast().title}</Toast.Title>
        <Toast.Description>{toast().description}</Toast.Description>
        <Toast.CloseTrigger>
          <X />
        </Toast.CloseTrigger>
      </Toast.Root>
    {/snippet}
  </Toaster>
</div>

Update Toast

To update a toast, use the toast.update method.

import { Toast, Toaster, createToaster } from '@ark-ui/react/toast'
import { useRef } from 'react'

const toaster = createToaster({
  placement: 'bottom-end',
  overlap: true,
  gap: 24,
})

export const Update = () => {
  const id = useRef<string>(undefined)

  const createToast = () => {
    id.current = toaster.create({
      title: 'Loading',
      description: 'Loading ...',
      type: 'info',
    })
  }

  const updateToast = () => {
    if (!id.current) {
      return
    }
    toaster.update(id.current, {
      title: 'Success',
      description: 'Success!',
    })
  }

  return (
    <div>
      <button type="button" onClick={createToast}>
        Create Toast
      </button>
      <button type="button" onClick={updateToast}>
        Update Toast
      </button>
      <Toaster toaster={toaster}>
        {(toast) => (
          <Toast.Root key={toast.id}>
            <Toast.Title>{toast.title}</Toast.Title>
            <Toast.Description>{toast.description}</Toast.Description>
          </Toast.Root>
        )}
      </Toaster>
    </div>
  )
}

import { Toast, Toaster, createToaster } from '@ark-ui/solid/toast'
import { createSignal } from 'solid-js'

const toaster = createToaster({
  placement: 'bottom-end',
  overlap: true,
  gap: 24,
})

export const Update = () => {
  const [id, setId] = createSignal<string | undefined>(undefined)

  const createToast = () => {
    const newId = toaster.create({
      title: 'Loading',
      description: 'Loading ...',
      type: 'info',
    })
    setId(newId)
  }

  const updateToast = () => {
    const currentId = id()
    if (!currentId) {
      return
    }
    toaster.update(currentId, {
      title: 'Success',
      description: 'Success!',
    })
  }

  return (
    <div>
      <button type="button" onClick={createToast}>
        Create Toast
      </button>
      <button type="button" onClick={updateToast}>
        Update Toast
      </button>
      <Toaster toaster={toaster}>
        {(toast) => (
          <Toast.Root>
            <Toast.Title>{toast().title}</Toast.Title>
            <Toast.Description>{toast().description}</Toast.Description>
          </Toast.Root>
        )}
      </Toaster>
    </div>
  )
}

<script setup lang="ts">
import { Toast, Toaster, createToaster } from '@ark-ui/vue/toast'
import { ref } from 'vue'

const toaster = createToaster({
  placement: 'bottom-end',
  overlap: true,
  gap: 24,
})

const id = ref<string | undefined>(undefined)

const createToast = () => {
  id.value = toaster.create({
    title: 'Loading',
    description: 'Loading ...',
    type: 'info',
  })
}

const updateToast = () => {
  if (!id.value) {
    return
  }
  toaster.update(id.value, {
    title: 'Success',
    description: 'Success!',
  })
}
</script>

<template>
  <div>
    <button type="button" @click="createToast">Create Toast</button>
    <button type="button" @click="updateToast">Update Toast</button>
    <Toaster :toaster="toaster" v-slot="toast">
      <Toast.Root>
        <Toast.Title>{{ toast.title }}</Toast.Title>
        <Toast.Description>{{ toast.description }}</Toast.Description>
      </Toast.Root>
    </Toaster>
  </div>
</template>

<script lang="ts">
  import { Toast, Toaster, createToaster } from '@ark-ui/svelte/toast'

  const toaster = createToaster({
    placement: 'bottom-end',
    overlap: true,
    gap: 24,
  })

  let toastId: string | undefined = $state()

  function createToast() {
    toastId = toaster.create({
      title: 'Loading',
      description: 'Loading ...',
      type: 'info',
    })
  }

  function updateToast() {
    if (!toastId) {
      return
    }
    toaster.update(toastId, {
      title: 'Success',
      description: 'Success!',
    })
  }
</script>

<div>
  <button type="button" onclick={createToast}>Create Toast</button>
  <button type="button" onclick={updateToast}>Update Toast</button>
  <Toaster {toaster}>
    {#snippet children(toast)}
      <Toast.Root>
        <Toast.Title>{toast().title}</Toast.Title>
        <Toast.Description>{toast().description}</Toast.Description>
      </Toast.Root>
    {/snippet}
  </Toaster>
</div>

Action

To add an action to a toast, use the toast.action property.

import { Toast, Toaster, createToaster } from '@ark-ui/react/toast'

const toaster = createToaster({
  placement: 'bottom-end',
  gap: 24,
})

export const Action = () => {
  return (
    <div>
      <button
        type="button"
        onClick={() =>
          toaster.create({
            title: 'Toast Title',
            description: 'Toast Description',
            type: 'info',
            action: {
              label: 'Subscribe',
              onClick: () => {
                console.log('Subscribe')
              },
            },
          })
        }
      >
        Add Toast
      </button>
      <Toaster toaster={toaster}>
        {(toast) => (
          <Toast.Root key={toast.id}>
            <Toast.Title>{toast.title}</Toast.Title>
            <Toast.Description>{toast.description}</Toast.Description>
            {toast.action && <Toast.ActionTrigger>{toast.action?.label}</Toast.ActionTrigger>}
          </Toast.Root>
        )}
      </Toaster>
    </div>
  )
}

import { Toast, Toaster, createToaster } from '@ark-ui/solid/toast'

const toaster = createToaster({
  placement: 'bottom-end',
  gap: 24,
})

export const Action = () => {
  return (
    <div>
      <button
        type="button"
        onClick={() =>
          toaster.create({
            title: 'Toast Title',
            description: 'Toast Description',
            type: 'info',
            action: {
              label: 'Subscribe',
              onClick: () => {
                console.log('Subscribe')
              },
            },
          })
        }
      >
        Add Toast
      </button>
      <Toaster toaster={toaster}>
        {(toast) => (
          <Toast.Root>
            <Toast.Title>{toast().title}</Toast.Title>
            <Toast.Description>{toast().description}</Toast.Description>
            {toast().action && <Toast.ActionTrigger>{toast().action?.label}</Toast.ActionTrigger>}
          </Toast.Root>
        )}
      </Toaster>
    </div>
  )
}

<script setup lang="ts">
import { Toast, Toaster, createToaster } from '@ark-ui/vue/toast'

const toaster = createToaster({
  placement: 'bottom-end',
  gap: 24,
})

const addToast = () => {
  toaster.create({
    title: 'Toast Title',
    description: 'Toast Description',
    type: 'info',
    action: {
      label: 'Subscribe',
      onClick: () => {
        console.log('Subscribe')
      },
    },
  })
}
</script>

<template>
  <div>
    <button type="button" @click="addToast">Add Toast</button>
    <Toaster :toaster="toaster" v-slot="toast">
      <Toast.Root>
        <Toast.Title>{{ toast.title }}</Toast.Title>
        <Toast.Description>{{ toast.description }}</Toast.Description>
        <Toast.ActionTrigger v-if="toast.action">{{ toast.action?.label }}</Toast.ActionTrigger>
      </Toast.Root>
    </Toaster>
  </div>
</template>

<script lang="ts">
  import { Toast, Toaster, createToaster } from '@ark-ui/svelte/toast'

  const toaster = createToaster({
    placement: 'bottom-end',
    gap: 24,
  })

  function addToast() {
    toaster.create({
      title: 'Toast Title',
      description: 'Toast Description',
      type: 'info',
      action: {
        label: 'Subscribe',
        onClick: () => {
          console.log('Subscribe')
        },
      },
    })
  }
</script>

<div>
  <button type="button" onclick={addToast}>Add Toast</button>
  <Toaster {toaster}>
    {#snippet children(toast)}
      <Toast.Root>
        <Toast.Title>{toast().title}</Toast.Title>
        <Toast.Description>{toast().description}</Toast.Description>
        {#if toast().action}
          <Toast.ActionTrigger>{toast().action?.label}</Toast.ActionTrigger>
        {/if}
      </Toast.Root>
    {/snippet}
  </Toaster>
</div>

Styling guide

There's a minimal styling required for the toast to work correctly.

Toast root

The toast root will be assigned these css properties at runtime:

--x - The x position
--y - The y position
--scale - The scale
--z-index - The z-index
--height - The height
--opacity - The opacity
--gap - The gap between toasts

[data-scope='toast'][data-part='root'] {
  translate: var(--x) var(--y);
  scale: var(--scale);
  z-index: var(--z-index);
  height: var(--height);
  opacity: var(--opacity);
  will-change: translate, opacity, scale;
  transition:
    translate 400ms,
    scale 400ms,
    opacity 400ms,
    height 400ms,
    box-shadow 200ms;
  transition-timing-function: cubic-bezier(0.21, 1.02, 0.73, 1);

  &[data-state='closed'] {
    transition:
      translate 400ms,
      scale 400ms,
      opacity 200ms;
    transition-timing-function: cubic-bezier(0.06, 0.71, 0.55, 1);
  }
}

Styling based on type

You can also style based on the data-type attribute.

[data-scope='toast'][data-part='root'] {
  &[data-type='error'] {
    background: red;
    color: white;
  }

  &[data-type='info'] {
    background: blue;
    color: white;
  }

  &[data-type='warning'] {
    background: orange;
  }

  &[data-type='success'] {
    background: green;
    color: white;
  }
}

Mobile considerations

A very common use case is to adjust the toast width on mobile so it spans the full width of the screen.

@media (max-width: 640px) {
  [data-scope='toast'][data-part='group'] {
    width: 100%;
  }

  [data-scope='toast'][data-part='root'] {
    inset-inline: 0;
    width: calc(100% - var(--gap) * 2);
  }
}

API Reference

Root

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Data Attribute	Value
`[data-scope]`	toast
`[data-part]`	root
`[data-state]`	"open" \| "closed"
`[data-type]`	The type of the item
`[data-placement]`	The placement of the toast
`[data-align]`
`[data-side]`
`[data-mounted]`	Present when mounted
`[data-paused]`	Present when paused
`[data-first]`
`[data-sibling]`
`[data-stack]`
`[data-overlap]`	Present when overlapping

ActionTrigger

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

CloseTrigger

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Description

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Title

Prop	Default	Type
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.

Toaster

Prop	Default	Type
`toaster`		`CreateToasterReturn`
`asChild`		`boolean` Use the provided child element as the default rendered element, combining their props and behavior. For more details, read our Composition guide.
`dir`	`'ltr'`	`'ltr' \| 'rtl'` The document's text/writing direction.
`getRootNode`		`() => Node \| ShadowRoot \| Document` A root node to correctly resolve document in custom environments. E.x.: Iframes, Electron.