@cssninja/nuxt-toaster
A simple toaster handler for Nuxt.js
Features
- Unstyled by default
- Render any component as a toast
- Fully customizable
- Simple to use
Installation
- Add
@cssninja/nuxt-toasterdependency to your project
# Using pnpm
pnpm add -D @cssninja/nuxt-toaster
# Using yarn
pnpm add -D @cssninja/nuxt-toaster
# Using npm
npm install --save-dev @cssninja/nuxt-toaster
- Add
@cssninja/nuxt-toasterto themodulessection ofnuxt.config.js
export default defineNuxtConfig({
modules: [
'@cssninja/nuxt-toaster'
]
})
Basic Usage
Show a toast
// get the ninjaToaster instance
const { $nt } = useNuxtApp()
// show a toast with a string as content
$nt.show('Hello world')
Show a toast with a custom component
// define or import a component
const MyToast = defineComponent({
/* ... */
})
// get the ninjaToaster instance
const { $nt } = useNuxtApp()
// show a toast with render function as content
$nt.show(() => h(MyToast))
Configuration
Using ninjaToaster.show options
// get the ninjaToaster instance
const { $nt } = useNuxtApp()
$nt.show({
/**
* The content of the toast, can be a render function
*
* @required
*/
content: 'Hello world',
/**
* The duration of the toast
*
* @default 5000
*/
duration: 5000,
/**
* Pause the duration timer on hover, or focus
*
* @default true
*/
pauseOnHover: true,
/**
* Whereas the toast can be closed on click,
* or on pressing Enter/Space keys when focused
*
* @default true
*/
dismissible: false,
/**
* Maximum number of toasts to show
* on the same `theme.containerId`
*
* @default Infinity
*/
maxToasts: 5,
/**
* Transition property for the toast
*
* @see https://vuejs.org/api/built-in-components.html#transition
*/
transition: {
name: 'fadeIn',
},
/**
* The theme used for the toast
*/
theme: {
containerId: 'nt-container',
containerClass: 'nt-container-class',
wrapperClass: 'nt-wrapper-class',
}
})
This will create a toast with the following HTML structure:
<body> <!-- ... --> <div id="nt-container" class="nt-container-class"> <div class="nt-wrapper-class" role="alert" tabindex="0" > Hello world </div> </div> </body>note: the
themeproperty is used to customize the toaster behavior. Eachtheme.containerIdwill have their own context (e.g. themaxToastswill count how many toaster are visible in the container with matching id).
Using toaster app config
To avoid to repeat yourself, you can set defaults values for ninjaToaster.show method in the nuxt app.config.ts at the root of your project.
// app.config.ts
export default defineAppConfig({
toaster: {
// default options for ninjaToaster.show
}
})
Using a custom plugin
By default, the module create an instance of ninjaToaster and inject it in the nuxt context in useNuxtApp().$nt.
You can create your own instance and inject it in the context by using a custom plugin.
- Disable default plugin in
nuxt.config.tsmodule options
// nuxt.config.ts
export default defineNuxtConfig({
modules: [
'@cssninja/nuxt-toaster'
],
toaster: {
// disable the default plugin
installPlugin: false
}
})
- Create a custom toast component
<script setup lang="ts">
// components/MyToast.vue
const props = defineProps<{
title: string
message?: string
type: 'info' | 'error'
}>()
const {
isHovered,
isActive,
timer,
duration,
click,
close,
} = useNinjaToasterState()
const {
percent,
endAt,
closeIn
} = useNinjaToasterProgress()
</script>
<template>
<div
class="rounded p-4"
:class="[
props.type === 'info' && 'bg-indigo-600 text-indigo-500'
props.type === 'error' && 'bg-rose-600 text-rose-500'
]"
>
<h1>{{ props.title }}</h1>
<p v-if="props.message">{{ props.message }}</p>
<button @click="close()">Close</button>
</div>
</template>
- Create a custom plugin
// plugins/toaster.ts
import MyToast from '~/components/MyToast.vue'
interface ToasterOptions {
message: string
title?: string
}
export default defineNuxtPlugin(() => {
// define or import a theme
const theme = {
containerId: 'nt-container-bottom-right',
containerClass: [
'absolute',
'inset-0',
'pointer-events-none',
'p-4',
'flex',
'flex-col-reverse',
'items-start',
'gap-2'
].join(' '),
wrapperClass: [
'pointer-events-auto',
'cursor-pointer',
].join(' '),
}
// set default show options here
const nt = createNinjaToaster({
theme,
maxToasts: 5,
transition: {
enterActiveClass: 'transition duration-300 ease-out',
enterFromClass: 'transform translate-x-full opacity-0',
enterToClass: 'transform translate-x-0 opacity-100',
leaveActiveClass: 'transition duration-300 ease-in',
leaveFromClass: 'transform translate-x-0 opacity-100',
leaveToClass: 'transform translate-x-full opacity-0'
}
})
const toaster = {
info (options: ToasterOptions) {
nt.show(() => h(MyToast, {
...options,
type: 'info'
}))
},
async error (options: ToasterOptions) {
// wait for the toast to be mounted
const { el, close } = await nt.show(() => h(MyToastError, {
...options,
type: 'error'
}))
// focus the toast once it's mounted
el.focus()
},
close() {
// close all toasts
nt.closeAll()
// or close toasts in a specific containerId
nt.close('nt-container-bottom-right')
// or close toasts using a theme
nt.close(theme)
},
}
return {
provide {
toaster
}
}
})
- Use your
toasterinstance in your app
// pages/index.vue
const { $toaster } = useNuxtApp()
$toaster.info({
title: 'Hello world',
message: 'This is a toaster info message'
})
$toaster.error({
title: 'Hello world',
message: 'This is a toaster error message'
})
Development
- Run
npm run dev:prepareto generate type stubs. - Use
npm run devto start playground in development mode.
15 Dec 3, 2022
19 Dec 17, 2022
5 May 24, 2022
231 Dec 30, 2022
208 Dec 27, 2022
128 Jan 7, 2023
25 Dec 15, 2022
26 Dec 27, 2022
211 Dec 28, 2022