Overlays
Notification
Display a toast notification in your app.
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.
Notification
<UNotification title="Notification" :id="1" :timeout="0" />
Description
You can add a description
in addition of the title
.
Notification
This is a notification.
<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
.
Notification
This is a notification.
<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.
Notification
This is a notification.
<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.
Notification
This is a notification.
<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.
Notification
This is a 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
.
Notification
<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
.
Notification
<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.
Notification
This is a notification.
<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>
<UNotifications />
component are automatically passed down to the Notification
children.Props
undefined
config.default.color
config.default.icon
null
config.default.closeButton as Button
null
[]
5000
null
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,
"closeButton": {
"icon": "i-heroicons-x-mark-20-solid",
"color": "gray",
"variant": "link",
"padded": false
},
"actionButton": {
"size": "xs",
"color": "white"
}
}
}