Radix Vue

Appearance

Toast ​

A succinct message that is displayed temporarily.
  • Automatically closes.
  • Pauses closing on hover, focus and window blur.
  • Supports hotkey to jump to toast viewport.
  • Supports closing via swipe gesture.
  • Exposes CSS variables for swipe gesture animations.
  • Can be controlled or uncontrolled.

Installation ​

Install the component from your command line.

bash
npm install radix-vue

Anatomy ​

Import the component.

vue
<script setup lang="ts">
import { ToastAction, ToastClose, ToastDescription, ToastProvider, ToastRoot, ToastTitle, ToastViewport } from 'radix-vue'
</script>

<template>
  <ToastProvider>
    <ToastRoot>
      <ToastTitle />
      <ToastDescription />
      <ToastAction />
      <ToastClose />
    </ToastRoot>

    <ToastViewport />
  </ToastProvider>
</template>

API Reference ​

Provider ​

The provider that wraps your toasts and toast viewport. It usually wraps the application.

PropTypeDefault
duration
number
5000
label*
string
"Notification"
swipeDirection
"right" | "left" | "up" | "down"
"right"
swipeThreshold
number
50

Viewport ​

The fixed area where toasts appear. Users can jump to the viewport by pressing a hotkey. It is up to you to ensure the discoverability of the hotkey for keyboard users.

PropTypeDefault
as
string | Component
ol
asChild
boolean
false
hotkey
string[]
["F8"]
label
string
"Notifications ({hotkey})"

Root ​

The toast that automatically closes. It should not be held open to acquire a user response.

PropTypeDefault
as
string | Component
li
asChild
boolean
false
type
"foreground" | "background"
"foreground"
duration
number
defaultOpen
boolean
true
open
boolean
forceMount
boolean
EmitType
@update:open
(value: boolean) => void
@escapeKeyDown
(event: KeyboardEvent) => void
@pause
() => void
@resume
() => void
@swipeStart
(event: SwipeEvent) => void
@swipeMove
(event: SwipeEvent) => void
@swipeEnd
(event: SwipeEvent) => void
Data AttributeValue
[data-state]"open" | "closed"
[data-swipe]"start" | "move" | "cancel" | "end"
[data-swipe-direction]"up" | "down" | "left" | "right"
CSS VariableDescription
--radix-toast-swipe-move-x
The offset position of the toast when horizontally swiping
--radix-toast-swipe-move-y
The offset position of the toast when vertically swiping
--radix-toast-swipe-end-x
The offset end position of the toast after horizontally swiping
--radix-toast-swipe-end-y
The offset end position of the toast after vertically swiping

Title ​

An optional title for the toast

PropTypeDefault
as
string | Component
div
asChild
boolean
false

Description ​

The toast message.

PropTypeDefault
as
string | Component
div
asChild
boolean
false

Action ​

An action that is safe to ignore to ensure users are not expected to complete tasks with unexpected side effects as a result of a time limit.

When obtaining a user response is necessary, portal an "AlertDialog" styled as a toast into the viewport instead.

PropTypeDefault
as
string | Component
button
asChild
boolean
false
altText*
string

Close ​

A button that allows users to dismiss the toast before its duration has elapsed.

PropTypeDefault
as
string | Component
button
asChild
boolean
false

Examples ​

Custom hotkey ​

Override the default hotkey using the event.code value for each key from keycode.info.

html
<ToastProvider>
  ...
  <ToastViewport :hotkey="['altKey', 'KeyT']" />
</ToastProvider>

Custom duration ​

Customise the duration of a toast to override the provider value.

vue
<ToastRoot :duration="3000">
  <ToastDescription>Saved!</ToastDescription>
</ToastRoot>

Duplicate toasts ​

When a toast must appear every time a user clicks a button, use state to render multiple instances of the same toast (see below). Alternatively, you can abstract the parts to create your own imperative API.

html
<div>
  <form  @submit="count++">
    ...
    <button>save</button>
  </form>

  <ToastRoot v-for="(_, index) in count" :key="index">
    <ToastDescription>Saved!</ToastDescription>
  </ToastRoot>
</div>

Animating swipe gesture ​

Combine --radix-toast-swipe-move-[x|y] and --radix-toast-swipe-end-[x|y] CSS variables with data-swipe="[start|move|cancel|end]" attributes to animate a swipe to close gesture. Here's an example:

html
<ToastProvider swipeDirection="right">
  <ToastRoot class="ToastRoot">...</ToastRoot>
  <ToastViewport />
</ToastProvider>
css
/* styles.css */
.ToastRoot[data-swipe='move'] {
  transform: translateX(var(--radix-toast-swipe-move-x));
}
.ToastRoot[data-swipe='cancel'] {
  transform: translateX(0);
  transition: transform 200ms ease-out;
}
.ToastRoot[data-swipe='end'] {
  animation: slideRight 100ms ease-out;
}

@keyframes slideRight {
  from {
    transform: translateX(var(--radix-toast-swipe-end-x));
  }
  to {
    transform: translateX(100%);
  }
}

Accessibility ​

Adheres to the aria-live requirements.

Sensitivity ​

Control the sensitivity of the toast for screen readers using the type prop.

For toasts that are the result of a user action, choose foreground. Toasts generated from background tasks should use background.

Foreground ​

Foreground toasts are announced immediately. Assistive technologies may choose to clear previously queued messages when a foreground toast appears. Try to avoid stacking distinct foreground toasts at the same time.

Background ​

Background toasts are announced at the next graceful opportunity, for example, when the screen reader has finished reading its current sentence. They do not clear queued messages so overusing them can be perceived as a laggy user experience for screen reader users when used in response to a user interaction.

html
<ToastRoot type="foreground">
  <ToastDescription>File removed successfully.</ToastDescription>
  <ToastClose>Dismiss</ToastClose>
</ToastRoot>

<ToastRoot type="background">
  <ToastDescription>We've just released Radix 1.0.</ToastDescription>
  <ToastClose>Dismiss</ToastClose>
</ToastRoot>

Alternative action ​

Use the altText prop on the Action to instruct an alternative way of actioning the toast to screen reader users.

You can direct the user to a permanent place in your application where they can action it or implement your own custom hotkey logic. If implementing the latter, use foreground type to announce immediately and increase the duration to give the user ample time.

html
<ToastRoot type="background">
  <ToastTitle>Upgrade Available!</ToastTitle>
  <ToastDescription>We've just released Radix 1.0.</ToastDescription>
  <ToastAction altText="Goto account settings to upgrade">
    Upgrade
  </ToastAction>
  <ToastClose>Dismiss</ToastClose>
</ToastRoot>

<ToastRoot type="foreground" :duration="10000">
  <ToastDescription>File removed successfully.</ToastDescription>
  <ToastAction altText="Undo (Alt+U)">
    Undo <kbd>Alt</kbd>+<kbd>U</kbd>
  </ToastAction>
  <ToastClose>Dismiss</ToastClose>
</ToastRoot>

Close icon button ​

When providing an icon (or font icon), remember to label it correctly for screen reader users.

html
<ToastRoot type="foreground">
  <ToastDescription>Saved!</ToastDescription>
  <ToastClose aria-label="Close">
    <span aria-hidden>×</span>
  </ToastClose>
</ToastRoot>

Keyboard Interactions ​

KeyDescription
F8
Focuses toasts viewport.
Tab
Moves focus to the next focusable element.
Shift + Tab
Moves focus to the previous focusable element.
Space
When focus is on a ToastAction or ToastClose, closes the toast
Enter
When focus is on a ToastAction or ToastClose, closes the toast
Esc
When focus is on a Toast, closes the toast

Custom APIs ​

Abstract parts ​

Create your own API by abstracting the primitive parts into your own component.

Usage ​

vue
<script setup lang="ts">
import Toast from './your-toast.vue'
</script>

<template>
  <Toast title="Upgrade available" content="We've just released Radix 3.0!">
    <button @click="handleUpgrade">
      Upgrade
    </button>
  </Toast>
</template>

Implementation ​

vue
// your-toast.vue
<script setup lang="ts">
import { ToastAction, ToastClose, ToastDescription, ToastRoot, ToastTitle } from 'radix-vue'

defineProps<{
  title: string
  content: string
}>()
</script>

<template>
  <ToastRoot>
    <ToastTitle v-if="title">
      {{ title }}
    </ToastTitle>
    <ToastDescription>{{ content }}</ToastDescription>
    <ToastAction as-child>
      <slot />
    </ToastAction>
    <ToastClose aria-label="Close">
      <span aria-hidden>×</span>
    </ToastClose>
  </ToastRoot>
</template>

Imperative API ​

Create your own imperative API to allow toast duplication if preferred.

Usage ​

vue
<script setup lang="ts">
import Toast from './your-toast.vue'
import type { InstanceType } from 'vue'

const savedRef = ref<InstanceType<typeof Toast>>()
</script>

<template>
  <div>
    <form @submit="savedRef.publish()">
      ...
    </form>
    <Toast ref="savedRef">
      Saved successfully!
    </Toast>
  </div>
</template>

Implementation ​

vue
// your-toast.vue
<script setup lang="ts">
import { ToastClose, ToastDescription, ToastRoot, ToastTitle } from 'radix-vue'
import { ref } from 'vue'

const count = ref(0)

function publish() {
  count.value++
}

defineExpose({
  publish
})
</script>

<template>
  <ToastRoot v-for="index in count" :key="index">
    <ToastDescription>
      <slot />
    </ToastDescription>
    <ToastClose>Dismiss</ToastClose>
  </ToastRoot>
</template>