Notification

Usage

First of all, add the Notifications component to your app, preferably inside app.vue.

<template>
  <div>
    <UContainer>
      <NuxtPage />
    </UContainer>
    <UNotifications />
  </div>
</template>

This component will render the notifications at the bottom right of the screen by default. You can configure its behavior in the app.config.ts through ui.notifications:

export default defineAppConfig({
  ui: {
    notifications: {
      // Show toasts at the top right of the screen
      position: 'top-0 right-0'
    }
  }
})

Then, you can use the useToast composable to add notifications to your app:

<script setup>
const toast = useToast()
</script>
<template>
  <UButton label="Show toast" @click="toast.add({ title: 'Hello world!' })" />
</template>

When using toast.add, this will push a new notification to the stack displayed in <UNotifications />. All the props of the Notification component can be passed to toast.add.

<script setup>
const toast = useToast()
onMounted(() => {
  toast.add({
    id: 'update_downloaded',
    title: 'Update downloaded.',
    description: 'It will be installed on restart. Restart now?',
    icon: 'i-octicon-desktop-download-24',
    timeout: 0,
    actions: [{
      label: 'Restart',
      click: () => {
      }
    }]
  })
})
</script>

You can also use the Notification component directly in your app as an alert for example.

Title

Pass a title to your Notification.

<UNotification title="Notification" />

Description

You can add a description in addition of the title.

<UNotification description="This is a notification." />

Icon

Use any icon from Iconify by setting the icon prop by using this pattern: i-{collection_name}-{icon_name} or change it globally in ui.notification.default.icon.

<UNotification icon="i-heroicons-check-circle" description="This is a notification." />

Avatar

Use the avatar prop as an object and configure it with any of its props.

description

Notification

This is a notification.

<UNotification description="This is a notification." :avatar="{ src: 'https://avatars.githubusercontent.com/u/739984?v=4' }" />

Timeout

Use the timeout prop to configure how long the Notification will remain. Set it to 0 to disable the timeout.

You will see a progress bar at the bottom of the Notification which will indicate the remaining time. When hovering the Notification, the progress bar will be paused.

<UNotification :timeout="60000" />

Style

Use the color prop to change the progress and icon color of the Notification.

<UNotification icon="i-heroicons-check-badge" color="primary" />

Click

Use the click prop to execute a function when the Notification is clicked.

<script setup>
const toast = useToast()
function onClick () {
  alert('Clicked!')
}
</script>
<template>
  <UButton label="Show toast" @click="toast.add({ title: 'Click me', click: onClick })" />
</template>

Callback

Use the callback prop to execute a function when the Notification expires.

<script setup>
const toast = useToast()
function onCallback () {
  alert('Notification expired!')
}
</script>
<template>
  <UButton label="Show toast" @click="toast.add({ title: 'Expires soon...', timeout: 1000, callback: onCallback })" />
</template>

Close

Use the close-button prop to hide or customize the close button on the Notification.

You can pass all the props of the Button component to customize it through the close-button prop or globally through ui.notification.default.closeButton.

<UNotification :close-button="{ icon: 'i-heroicons-archive-box-x-mark', color: 'primary', variant: 'outline', padded: true, size: '2xs', ui: { rounded: 'rounded-full' } }" />

Actions

Use the actions prop to add actions to the Notification.

<script setup>
const toast = useToast()
</script>
<template>
  <UButton label="Show toast" @click="toast.add({ title: 'Click me', click: () => alert('Clicked!') })" />
</template>

Like for closeButton, you can pass all the props of the Button component inside the action or globally through ui.notification.default.actionButton.

<UNotification :actions="[{ label: 'Action 1' }, { variant: 'solid', color: 'gray', label: 'Action 2' }]" />

Actions will render differently whether you have a description set.

<UNotification :actions="[{ variant: 'solid', color: 'primary', label: 'Action 1' }, { variant: 'outline', color: 'primary', label: 'Action 2' }]" />

Slots

title / description

Use the #title and #description slots to customize the Notification.

This can be handy when you want to display HTML content. To achieve this, you can define those slots in the top-level <UNotifications /> component in your app.vue and use the v-html directive.

<template>
  <UNotifications>
    <template #title="{ title }">
      <span v-html="title" />
    </template>
    <template #description="{ description }">
      <span v-html="description" />
    </template>
  </UNotifications>
</template>

This way, you can use HTML tags in the title and description props when using useToast.

<script setup>
const toast = useToast()
</script>
<template>
  <UButton label="Show toast" @click="toast.add({ title: 'Notification <i>italic</i>', description: 'This is an <u>underlined</u> and <b>bold</b> notification.' })" />
</template>

Props

Preset

{
  "wrapper": "w-full pointer-events-auto",
  "container": "relative overflow-hidden",
  "title": "text-sm font-medium text-gray-900 dark:text-white",
  "description": "mt-1 text-sm leading-4 text-gray-500 dark:text-gray-400",
  "background": "bg-white dark:bg-gray-900",
  "shadow": "shadow-lg",
  "rounded": "rounded-lg",
  "padding": "p-4",
  "ring": "ring-1 ring-gray-200 dark:ring-gray-800",
  "icon": {
    "base": "flex-shrink-0 w-5 h-5",
    "color": "text-{color}-500 dark:text-{color}-400"
  },
  "avatar": {
    "base": "flex-shrink-0 self-center",
    "size": "md"
  },
  "progress": {
    "base": "absolute bottom-0 end-0 start-0 h-1",
    "background": "bg-{color}-500 dark:bg-{color}-400"
  },
  "transition": {
    "enterActiveClass": "transform ease-out duration-300 transition",
    "enterFromClass": "translate-y-2 opacity-0 sm:translate-y-0 sm:translate-x-2",
    "enterToClass": "translate-y-0 opacity-100 sm:translate-x-0",
    "leaveActiveClass": "transition ease-in duration-100",
    "leaveFromClass": "opacity-100",
    "leaveToClass": "opacity-0"
  },
  "default": {
    "color": "primary",
    "icon": null,
    "closeButton": {
      "icon": "i-heroicons-x-mark-20-solid",
      "color": "gray",
      "variant": "link",
      "padded": false
    },
    "actionButton": {
      "size": "xs",
      "color": "white"
    }
  }
}