@cssninja/nuxt-toaster
v0.3.12
Published
π A simple toaster (notifier) handler for Nuxt.js
Downloads
4,590
Readme
@cssninja/nuxt-toaster
π A simple toaster (notifier) 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 (a.k.a stateless component)
*
* @type {string | number | Record<string, any> | (() => Component)}
* @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: {
/**
* The container id where the toast will be rendered
* If not exists, it will be created automatically
*
* @default 'nt-container'
*/
containerId: 'nt-container',
/**
* The class name for the toaster container (applyed to toast container)
*
* @type {string | string[]}
* @default ''
*/
containerClass: 'nt-container-class',
/**
* The class name for the toast wrapper (applyed to each toast)
*
* @type {string | string[]}
* @default ''
*/
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. Here we are using tailwindcss to style the toast.
- 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'
],
wrapperClass: [
'pointer-events-auto',
'cursor-pointer',
],
}
// 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'
})Theming
Minimal CSS theme
#nt-container {
/* make container fit the screen */
position: fixed;
top: 0;
left: 0;
right: 0;
bottom: 0;
overflow: hidden;
z-index: 100;
pointer-events: none;
/* position the toasts using flexbox */
display: flex;
/**
* position all toasts in bottom of the screen
* - use "flex-direction: column;" to position in top screen
*/
flex-direction: column-reverse;
/**
* align all toasts to the center
* - use "align-items: start" to aling to the left
* - use "align-items: end" to aling to the right
*/
align-items: center;
/* add some space between toasts and screen */
padding: 2rem;
gap: 1rem;
}
#nt-container [role='alert'] {
/* allow toasts to be interactive */
pointer-events: auto;
/* add styles to toasts */
padding: 1rem;
border-radius: 0.5rem;
background-color: #fff;
box-shadow: 0 0 1rem rgba(0, 0, 0, 0.1);
}
@media (max-width: 767px) {
#nt-container {
/* fit toasts to screen on mobile */
padding: 0;
}
}
Development
- Run
npm run dev:prepareto generate type stubs. - Use
npm run devto start playground in development mode.