@davidramosweb/vue-sonner
v1.1.4
Published
[![NPM][npmBadge]][npmUrl] [![Minzip Package][bundlePhobiaBadge]][bundlePhobiaUrl] [![NPM Download][npmDtBadge]][npmDtUrl]
Downloads
9
Readme
Sonner for Vue
An opinionated toast component for Vue. It's a Vue port of Sonner
Preview
https://user-images.githubusercontent.com/6118824/228208185-be5aefd4-7fa8-4f95-a41c-88a60c0e2800.mp4
Introduction
Vue Sonner
is an opinionated toast component for Vue. It's customizable, but styled by default. Comes with a swipe to dismiss animation.
Table of Contents
- Sonner for Vue
Installation
To start using the library, install it in your project:
pnpm install vue-sonner
or
yarn add vue-sonner
Usage
For Vue 3
<!-- App.vue -->
<template>
<Toaster />
<button @click="() => toast('My first toast')">Render a toast</button>
</template>
<script lang="ts" setup>
import { Toaster, toast } from 'vue-sonner'
</script>
For Nuxt 3
Define a nuxt plugin
// plugins/sonner.client.ts
import { Toaster, toast } from 'vue-sonner'
export default defineNuxtPlugin((nuxtApp) => {
nuxtApp.vueApp.component('Toaster', Toaster)
return {
provide: {
toast
}
}
})
Use Toaster
component and $toast
function anywhere in the Vue SFC
<!-- app.vue -->
<template>
<div>
<NuxtPage />
<Toaster position="top-right" />
<button @click="() => $toast('My first toast')">Render a toast</button>
</div>
</template>
<script setup lang="ts">
// alternatively, you can also use it here
const { $toast } = useNuxtApp()
</script>
Add the build transpile for vue-sonner
// nuxt.config.ts
import { defineNuxtConfig } from 'nuxt/config'
export default defineNuxtConfig({
...
build: {
transpile: ['vue-sonner']
}
})
CDN Link
EMS version
https://cdn.jsdelivr.net/npm/vue-sonner/+esm
UMD version
https://www.unpkg.com/[email protected]/lib/vue-sonner.umd.cjs
Types
Default
Most basic toast. You can customize it (and any other type) by passing an options object as the second argument.
toast('Event has been created')
With custom description:
toast('Event has been created', {
description: 'Monday, January 3rd at 6:00pm'
})
Success
Renders a checkmark icon in front of the message.
toast.success('Event has been created')
Error
Renders an error icon in front of the message.
toast.error('Event has not been created')
Action
Renders a button.
toast('Event has been created', {
action: {
label: 'Undo',
onClick: () => console.log('Undo')
}
})
Promise
Starts in a loading state and will update automatically after the promise resolves or fails.
You can pass a function to the success/error messages to incorporate the result/error of the promise.
toast.promise(() => new Promise((resolve) => setTimeout(resolve, 2000)), {
loading: 'Loading',
success: (data: any) => 'Success',
error: (data: any) => 'Error'
})
Custom Component
You can pass a Vue Component as the first argument instead of a string to render custom Component while maintaining default styling. You can use the headless version below for a custom, unstyled toast.
<script lang="ts" setup>
import { defineComponent, h, markRaw } from 'vue'
const CustomDiv = defineComponent({
setup() {
return () =>
h('div', {
innerHTML: 'A custom toast with unstyling'
})
}
})
toast(markRaw(CustomDiv))
</script>
Customization
Headless
You can use toast.custom
to render an unstyled toast with custom jsx while maintaining the functionality.
<script lang="ts" setup>
import { markRaw } from 'vue'
import HeadlessToast from './HeadlessToast.vue'
toast.custom(markRaw(HeadlessToast), { duration: 999999 })
</script>
Theme
You can change the theme using the theme
prop. Default theme is light.
<Toaster theme="dark" />
Position
You can change the position through the position
prop on the <Toaster />
component. Default is top-right
.
<!-- Available positions -->
<!-- top-left, top-center, top-right, bottom-left, bottom-center, bottom-right -->
<Toaster position="top-center" />
Expanded
Toasts can also be expanded by default through the expand
prop. You can also change the amount of visible toasts which is 3 by default.
<Toaster expand :visibleToasts="9" />
Styling for all toasts
You can style your toasts globally with the toastOptions
prop in the Toaster
component.
<Toaster
:toastOptions="{
style: { background: 'red' },
class: 'my-toast',
descriptionClass: 'my-toast-description'
}"
/>
Styling for individual toast
toast('Event has been created', {
style: {
background: 'red'
},
class: 'my-toast',
descriptionClass: 'my-toast-description'
})
Tailwind CSS
The preferred way to style the toasts with tailwind is by using the unstyled
prop. That will give you an unstyled toast which you can then style with tailwind.
<Toaster
:toastOptions="{
unstyled: true,
classes: {
toast: 'bg-blue-400',
title: 'text-red-400',
description: 'text-red-400',
actionButton: 'bg-zinc-400',
cancelButton: 'bg-orange-400',
closeButton: 'bg-lime-400'
}
}"
/>
You can do the same when calling toast()
.
toast('Hello World', {
unstyled: true,
classes: {
toast: 'bg-blue-400',
title: 'text-red-400 text-2xl',
description: 'text-red-400',
actionButton: 'bg-zinc-400',
cancelButton: 'bg-orange-400',
closeButton: 'bg-lime-400'
}
})
Styling per toast type is also possible.
<Toaster
:toastOptions="{
unstyled: true,
classes: {
error: 'bg-red-400',
success: 'text-green-400',
warning: 'text-yellow-400',
info: 'bg-blue-400',
}
}"
/>
Changing Icon
You can change the default icons using slots:
<Toaster>
<template #loading-icon>
<LoadingIcon />
</template>
<template #success-icon>
<SuccessIcon />
</template>
<template #error-icon>
<ErrorIcon />
</template>
<template #info-icon>
<InfoIcon />
</template>
<template #warning-icon>
<WarningIcon />
</template>
</Toaster>
Close button
Add a close button to all toasts that shows on hover by adding the closeButton
prop.
<Toaster closeButton />
Rich colors
You can make error and success state more colorful by adding the richColors
prop.
<Toaster richColors />
Custom offset
Offset from the edges of the screen.
<Toaster offset="80px" />
Programmatically remove toast
To remove a toast programmatically use toast.dismiss(id)
.
const toastId = toast('Event has been created')
toast.dismiss(toastId)
You can also use the dismiss method without the id to dismiss all toasts.
toast.dismiss()
Programmatically remove toast
You can change the duration of each toast by using the duration property, or change the duration of all toasts like this:
<Toaster :duration="10000" />
toast('Event has been created', {
duration: 10000
})
// Persisent toast
toast('Event has been created', {
duration: Infinity
})
On Close Callback
You can pass onDismiss
and onAutoClose
callbacks. onDismiss
gets fired when either the close button gets clicked or the toast is swiped. onAutoClose
fires when the toast disappears automatically after it's timeout (duration
prop).
toast('Event has been created', {
onDismiss: (t) => console.log(`Toast with id ${t.id} has been dismissed`),
onAutoClose: (t) =>
console.log(`Toast with id ${t.id} has been closed automatically`)
})
Keyboard focus
You can focus on the toast area by pressing ⌥/alt + T. You can override it by providing an array of event.code values for each key.
<Toaster hotkey="['KeyC']" />
Inspiration
- sonner - An opinionated toast component for React.
License
MIT @xiaoluoboding