![npm bundle size](https://img.shields.io/bundlephobia/minzip/@kyvg/vue3-notification)
Upgrade to v3.x
Breaking changes
title
and text
no longer render with v-html
. Use dangerouslySetInnerHtml
prop to render title
and text
with v-html
Vue.js notifications
This is a fork and port of Vue 2 vue-notifications created by euvl to now support Vue 3. If you're using Vue 2.x use his version.
Setup
npm install --save @kyvg/vue3-notification
yarn add @kyvg/vue3-notification
Add dependencies to your main.js
:
import { createApp } from 'vue'
import Notifications from '@kyvg/vue3-notification'
const app = createApp({...})
app.use(Notifications)
Add the global component to your App.vue
:
<notifications />
Please note that this library does not inherently support Nuxt 3. To enable compatibility with Nuxt 3, use the nuxt3-notifications
wrapper
Usage
Trigger notifications from your .vue
files:
this.$notify("Hello user!");
this.$notify({
title: "Important message",
text: "Hello user!",
});
Or trigger notifications from other files, for example, your router:
import { notify } from "@kyvg/vue3-notification";
notify({
title: "Authorization",
text: "You have been logged in!",
});
Or use Composition API style:
import { useNotification } from "@kyvg/vue3-notification";
const { notify } = useNotification()
notify({
title: "Authorization",
text: "You have been logged in!",
});
Migration
Vue 2.x syntax
Vue.notify({
title: "Vue 2 notification",
});
Vue 3.x syntax
import { notify } from "@kyvg/vue3-notification";
notify({
title: "Vue 3 notification 🎉",
});
Vue 3.x Composition API syntax
import { useNotification } from "@kyvg/vue3-notification";
const notification = useNotification()
notification.notify({
title: "Vue 3 notification 🎉",
});
Also you can use destructuring assignment
import { useNotification } from "@kyvg/vue3-notification";
const { notify } = useNotification()
notify({
title: "Vue 3 notification 🎉",
});
Component props
The majority of settings for the Notifications component are configured using props:
<notifications position="bottom right" classes="my-custom-class" />
Note that all props are optional.
Name | Type | Default | Description |
---|
position | String/Array | 'top right' | Part of the screen where notifications will pop out |
width | Number/String | 300 | Width of notification holder, can be % , px string or number. Valid values: '100%', '200px', 200 |
classes | String/Array | 'vue-notification' | List of classes that will be applied to notification element |
group | String | null | Name of the notification holder, if specified |
duration | Number | 3000 | Time (in ms) to keep the notification on screen (if negative - notification will stay forever or until clicked) |
speed | Number | 300 | Time (in ms) to show / hide notifications |
animation-type | String | 'css' | Type of animation, currently supported types are css and velocity |
animation-name | String | null | Animation name required for css animation |
animation | Object | Custom | Animation configuration for Velocity animation |
max | Number | Infinity | Maximum number of notifications that can be shown in notification holder |
reverse | Boolean | false | Show notifications in reverse order |
ignoreDuplicates | Boolean | false | Ignore repeated instances of the same notification |
closeOnClick | Boolean | true | Close notification when clicked |
pauseOnHover | Boolean | false | Keep the notification open while mouse hovers on notification |
dangerouslySetInnerHtml | Boolean | false | Use v-html to set title and text |
Component events
Name | Type | Description |
---|
click | (item: NotificationItem) => void | The callback function that is triggered when notification was clicked |
destroy | (item: NotificationItem) => void | The callback function that is triggered when notification was destroyes |
start | (item: NotificationItem) => void | The callback function that is triggered when notification was appeared |
API
Notifications are triggered via the API:
this.$notify({
group: 'foo',
title: 'This is the <em>title</em>',
text: 'This is some <b>content</b>',
type: 'warn',
duration: 10000,
speed: 1000
data: {}
})
To remove notifications, include the clean: true
parameter.
this.$notify({
group: "foo",
clean: true,
});
Plugin Options
Configure the plugin itself using an additional options object:
app.use(Notifications, { name: "alert" });
All options are optional:
Name | Type | Default | Description |
---|
name | String | notify | Defines the instance name. It's prefixed with the dollar sign. E.g. $notify |
componentName | String | Notifications | The component's name |
velocity | Object | undefined | A Velocity library object (see Animation) |
Note: setting componentName
can cause issues when using SSR.
TypeScript Support
This library is written with TypeScript. Since the notification component is registered globally, you need to register its types.
You can do this manually:
import type { FunctionalComponent } from 'vue';
import type { Notifications } from '@kyvg/vue3-notification';
declare module 'vue' {
export interface GlobalComponents {
Notifications: FunctionalComponent<Notifications>;
}
}
Or, you can use built-in unplugin-vue-components
resolver. This resolver allows you to seamlessly integrate this library with Vue projects using unplugin-vue-components
. It automates the import of components, making your development process more efficient.
Installation
To get started, install the necessary packages using npm or yarn:
npm install --save @kyvg/vue3-notification unplugin-vue-components
yarn add @kyvg/vue3-notification unplugin-vue-components
Configuration
To configure the resolver, update your Vue project's plugin settings. For example, in a Vite project, modify vite.config.js:
import Components from 'unplugin-vue-components/vite';
import NotificationsResolver from '@kyvg/vue3-notification/auto-import-resolver';
export default {
plugins: [
Components({
resolvers: [NotificationsResolver()],
}),
],
}
Specify the custom component's name if you have configured it:
app.use(Notifications, { componentName: "Alert" });
Note that component name should be in PascalCase
import Components from 'unplugin-vue-components/vite';
import NotificationsResolver from '@kyvg/vue3-notification/auto-import-resolver';
export default {
plugins: [
Components({
resolvers: [NotificationsResolver("Alert")],
}),
],
}
Features
Position
Position the component on the screen using the position
prop:
<notifications position="bottom right" />
It requires a string
with two keywords for vertical and horizontal postion.
Format: "<vertical> <horizontal>"
.
- Horizontal options:
left
, center
, right
- Vertical options:
top
, bottom
Default is "top right"
.
Width
Width can be set using a number
or string
with optional %
or px
extensions:
<notifications :width="100" />
<notifications width="100" />
<notifications width="100%" />
<notifications width="100px" />
Type
Set the type
of a notification (warn, error, success, etc) by adding a type
property to the call:
this.$notify({ type: "success", text: "The operation completed" });
This will add the type
(i.e. "success") as a CSS class name to the .vue-notification
element.
See the Styling section for how to hook onto the class and style the popup.
Groups
For different classes of notifications, i.e...
- authentication errors (top center)
- app notifications (bottom-right)
...specify the group
attribute:
<notifications group="auth" position="top" />
<notifications group="app" position="bottom right" />
Trigger a notification for a specific group by specifying it in the API call:
this.$notify({ group: "auth", text: "Wrong password, please try again" });
Customisation
Styling
Vue Notifications comes with default styling, but it's easy to replace with your own.
Specify one or more class hooks via the classes
prop on the global component:
<notifications classes="my-notification" />
This will add the supplied class/classes to individual notification elements:
<div class="vue-notification-wrapper">
<div class="vue-notification-template my-notification">
<div class="notification-title">Info</div>
<div class="notification-content">You have been logged in</div>
</div>
</div>
Then include custom css rules to style the notifications:
.my-notification {
.notification-title {
}
.notification-content {
}
&.success {
}
&.info {
}
&.error {
}
}
Note that the default rules are:
.vue-notification {
margin: 0 5px 5px;
padding: 10px;
font-size: 12px;
color: #ffffff;
background: #44a4fc;
border-left: 5px solid #187fe7;
&.success {
background: #68cd86;
border-left-color: #42a85f;
}
&.warn {
background: #ffb648;
border-left-color: #f48a06;
}
&.error {
background: #e54d42;
border-left-color: #b82e24;
}
}
Content
To completely replace notification content, use Vue's slots system:
<notifications>
<template #body="props">
<div class="my-notification">
<p class="title">
{{ props.item.title }}
</p>
<button class="close" @click="props.close">
<i class="fa fa-fw fa-close"></i>
</button>
<div v-html="props.item.text"/>
</div>
</template>
</notifications>
The props
object has the following members:
Name | Type | Description |
---|
item | Object | Notification object |
close | Function | A function to close the notification |
Animation
Vue Notification can use the Velocity library to power the animations using JavaScript.
To use, manually install velocity-animate
& pass the library to the vue-notification
plugin (the reason for doing that is to reduce the size of this plugin).
In your main.js
:
import { createApp } from 'vue'
import Notifications from '@kyvg/vue3-notification'
import velocity from 'velocity-animate'
const app = createApp({...})
app.use(Notifications, { velocity })
In the template, set the animation-type
prop:
<notifications animation-type="velocity" />
The default configuration is:
{
enter: { opacity: [1, 0] },
leave: { opacity: [0, 1] }
}
To assign a custom animation, use the animation
prop:
<notifications animation-type="velocity" :animation="animation" />
Note that enter
and leave
can be an object
or a function
that returns an object
:
computed: {
animation () {
return {
enter (element) {
let height = element.clientHeight
return {
height: [height, 0],
opacity: [Math.random() * 0.5 + 0.5, 0]
}
},
leave: {
height: 0,
opacity: 0
}
}
}
}
Programatically Closing
const id = Date.now()
this.$notify({
id,
text: 'This message will be removed immediately'
});
this.$notify.close(id);
Or with composition API style:
import { useNotification } from "@kyvg/vue3-notification"
const notification = useNotification()
const id = Date.now()
notification.notify({
id,
text: 'This message will be removed immediately'
})
notification.notify.close(id)
FAQ
Check closed issues with FAQ
label to get answers for most asked questions.
Development
To contribute to the library:
npm install
npm run build
npm run test
npm run unit:watch