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 bottom-auto'
    }
  }
})

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" :id="1" :timeout="0" />

Description

You can add a description in addition of the title.

<UNotification
  description="This is a notification."
  :id="2"
  :timeout="0"
  title="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."
  :id="3"
  :timeout="0"
  title="Notification"
/>

Avatar

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

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

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"
  :id="5"
  title="Notification"
  description="This is a notification."
/>

Style

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

<UNotification
  icon="i-heroicons-check-badge"
  color="primary"
  :id="6"
  title="Notification"
  description="This is a notification."
  :timeout="600000"
/>

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' } }"
  :id="7"
  title="Notification"
  :timeout="0"
/>

Actions

Use the actions prop to add actions to the Notification.

<script setup>
const toast = useToast()

const actions = ref([{
  label: 'Action 1',
  click: () => alert('Action 1 clicked!')
}, {
  label: 'Action 2',
  click: () => alert('Action 2 clicked!')
}])
</script>

<template>
  <UButton label="Show toast" @click="toast.add({ title: 'With actions', actions })" />
</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' }]"
  :id="8"
  title="Notification"
  :timeout="0"
/>

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' }]"
  :id="9"
  title="Notification"
  description="This is a notification."
  :timeout="0"
/>

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: 'This is an <u>underlined</u> and <b>bold</b> notification.' })" />
</template>

Props

Config

{
  "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",
  "actions": "flex items-center gap-2 mt-3 flex-shrink-0",
  "background": "bg-white dark:bg-gray-900",
  "shadow": "shadow-lg",
  "rounded": "rounded-lg",
  "padding": "p-4",
  "gap": "gap-3",
  "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,
    "timeout": 5000,
    "closeButton": {
      "icon": "i-heroicons-x-mark-20-solid",
      "color": "gray",
      "variant": "link",
      "padded": false
    },
    "actionButton": {
      "size": "xs",
      "color": "white"
    }
  }
}