https://github.com/emmanuelsw/notiwind
A headless Vue 3 notification library to use with Tailwind CSS.
https://github.com/emmanuelsw/notiwind
notifications tailwindcss tailwindui toast vite vue3
Last synced: 11 months ago
JSON representation
A headless Vue 3 notification library to use with Tailwind CSS.
- Host: GitHub
- URL: https://github.com/emmanuelsw/notiwind
- Owner: emmanuelsw
- License: mit
- Created: 2021-05-21T02:44:59.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2024-04-16T13:34:22.000Z (about 2 years ago)
- Last Synced: 2024-12-01T15:12:30.503Z (over 1 year ago)
- Topics: notifications, tailwindcss, tailwindui, toast, vite, vue3
- Language: Vue
- Homepage: https://notiwind-demo.netlify.app
- Size: 444 KB
- Stars: 278
- Watchers: 4
- Forks: 28
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Notiwind
A headless Vue 3 notification library to use with Tailwind CSS.
This is a fork and port of [vue3-vt-notifications](https://github.com/killmenot/vue3-vt-notifications) created and modified by [killmenot](https://github.com/killmenot) to support Vue 3. Initially created by [sansil](https://github.com/sansil).
## 🌟 Features
- 100% Customizable
- Composition API support
- Create different groups of notifications
- Permanent and stay on hover options
## 🤖 Demo
[Live Preview](https://notiwind-demo.netlify.app)
## ⚡️ Installation
```bash
pnpm add notiwind
```
or
```bash
npm i notiwind
```
You can then register `Notifications` as a Vue plugin:
```js
import { createApp } from 'vue'
import Notifications from 'notiwind'
import App from './App.vue'
createApp(App).use(Notifications).mount('#app')
```
## 🍞 How to use
Add the notification components to your main layout or in `App.vue`:
```vue
...
...
```
Then, trigger notifications from your `.vue` files:
###### Options API
```javascript
this.$notify(
{
group: 'foo',
title: 'Success',
text: 'Your account was registered!',
},
2000,
) // 2s
```
###### Composition API
```javascript
import { notify } from 'notiwind'
notify(
{
group: 'foo',
title: 'Success',
text: 'Your account was registered!',
},
4000,
) // 4s
```
### Basic example
For example in your `App.vue`
```vue
{{ notification.title }}
{{ notification.text }}
```
Then in any of your `.vue` files:
```javascript
this.$notify(
{
group: 'foo',
title: 'Success',
text: 'Your account was registered!',
},
2000,
) // 2s
```
The first argument is an object containing the data for the `Notification` element, it's important to specify the group where the notificatoins are going to be displayed, the second argument is the timeout. The default timeout is 3 seconds.
If you need to keep the notification on the screen forever use `-1` as a timeout:
```javascript
this.$notify(
{
group: 'foo',
title: 'Success',
text: 'Your account was registered!',
},
-1,
) // it's not going to disappear automatically
```
### Example with differents groups
You can use the `NotificationGroup` component to have different types of notifications. For example, notifications error messages in top center and generic app notifications in bottom-right corner.
```vue
{{ notification.title }}
{{ notification.text }}
{{ notification.title }}Info
{{ notification.text }}
```
Then in any of your `.vue` files:
```javascript
// Error notification
this.$notify(
{
group: 'error',
title: 'Error',
text: 'Your email is already used!',
},
4000,
)
// Generic notification
this.$notify(
{
group: 'generic',
title: 'Info',
text: 'This channel archived by the owner',
},
4000,
)
```
### Using different types of notifications
You can render different types of notifications in the same group using a conditional, for example `v-if="notification.type === 'info'"`
```vue
{{ notification.title }}
{{ notification.text }}
{{ notification.title }}
{{ notification.text }}
```
Then in any of your `.vue` files:
```javascript
// Error notification
this.$notify(
{
title: 'Info',
text: 'This channel archived by the owner!',
type: 'info',
group: 'foo',
},
4000,
)
// Generic notification
this.$notify(
{
title: 'Warning',
text: 'Your image size is too large!',
type: 'warning',
group: 'foo',
},
4000,
)
```
## Props
##### Props for the `Notification` component, all are optional.
| Name | Type | Default | Description |
| ---------------- | ------ | ------- | ---------------------------------------------------------------------------------- |
| maxNotifications | Number | 10 | Maximum notifications displayed simultaneously |
| enter | String | "" | _enter-active-class_ transition classes. Applied during the entire entering phase. |
| enterFrom | String | "" | _enter-from-class_ transition classes. Starting state for enter. |
| enterTo | String | "" | _enter-to-class_ transition classes. Ending state for enter. |
| leave | String | "" | _leave-active-class_ transition classes. Applied during the entire leaving phase. |
| leaveFrom | String | "" | _leave-from-class_ transition classes. Starting state for leave. |
| leaveTo | String | "" | _leave-to-class_ transition classes. Ending state for leave. |
| move | String | "" | _move-class_ transition classes. Added when items are changing positions. |
| moveDelay | String | "" | Delay between the position change. `delay-300` recommended value. |
Check the Vue docs to know more about [Enter & Leave Transitions](https://v3.vuejs.org/guide/transitions-enterleave.html#transition-classes) and [List Move Transitions](https://v3.vuejs.org/guide/transitions-list.html#list-move-transitions).
##### Props for `NotificationGroup` component, all are optional.
| Name | Type | Description |
| -------- | ------ | ----------------------------------------- |
| position | String | "bottom" or "top" are the posible values. |
| group | String | Name of the group of notifications. |
## Defualt scoped slots
Scope props:
| Name | Type | Description |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| notifications | Array | Array of notification objects. |
| close | Function | Closes the notification. Expects the notification ID as parameter |
| hovering | Function | Prevents notification from closing if being hovered. Expected the notification ID, the hover value (true or false) and optionally, a timeout to be used in the mouse leave (hover ended). |
### Example
```vue
Holy smokes!
Something seriously bad happened.
Close
```
## Typescript
Typed notifications supported using the Composition API only.
```typescript
// notiwind.ts
import { createNotifier, NotificationGroup, defineNotificationComponent } from 'notiwind'
export type NotificationSchema = {
title: string
text: string
}
export const notify = createNotifier()
export const Notification = defineNotificationComponent()
export { NotificationGroup }
```
```vue
import { notify, Notification, NotificationGroup } from './notiwind.ts'
notify(
{
title: 'title',
text: 'text',
},
4000,
)
```
## TODO
- Add tests
## Contributing
1. Fork it
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Added some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request
## License
MIT