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 lang="ts">
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 lang="ts">
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.

<template>
  <UNotification title="Notification" :id="1" :timeout="0" />
</template>

Description

You can add a description in addition of the title.

<template>
  <UNotification
    description="This is a notification."
    :id="2"
    :timeout="0"
    title="Notification"
  />
</template>

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.

<template>
  <UNotification
    icon="i-heroicons-check-circle"
    description="This is a notification."
    :id="3"
    :timeout="0"
    title="Notification"
  />
</template>

Avatar

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

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

Timeout

Use the timeout prop to configure how long the Notification will remain. The default value is 5000, 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.

<template>
  <UNotification
    :timeout="60000"
    :id="5"
    title="Notification"
    description="This is a notification."
  />
</template>

Style

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

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

Click

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

<script setup lang="ts">
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 lang="ts">
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.

<template>
  <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"
  />
</template>

Actions

Use the actions prop to add actions to the Notification.

<script setup lang="ts">
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.

<template>
  <UNotification
    :actions="[{ label: 'Action 1' }, { variant: 'solid', color: 'gray', label: 'Action 2' }]"
    :id="8"
    title="Notification"
    :timeout="0"
  />
</template>

Actions will render differently whether you have a description set.

<template>
  <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"
  />
</template>

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 lang="ts">
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',
  inner: 'w-0 flex-1',
  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',
    },
  },
}