Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: about 1 month 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 (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-04-16T13:34:22.000Z (9 months ago)
- Last Synced: 2024-12-01T15:12:30.503Z (about 1 month 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
- Tailwind's JIT support
## 🤖 Demo
[Live Preview](https://notiwind-demo.netlify.app)
## ⚡️ Installation
```bash
yarn 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