# @billow/toast

> Toasts for Vuejs Apps

Latest version **1.0.7** (published 2022-06-06) · UNLICENSED license · 0 weekly downloads

## Install

```sh
npm install @billow/toast
pnpm add @billow/toast
yarn add @billow/toast
bun add @billow/toast
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.7 |
| Published | 2022-06-06 |
| First published | 2018-08-13 |
| Weekly downloads | 0 |
| License | UNLICENSED |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 1 |
| Unpacked size | 20.6 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | billow |
| Keywords | vuejs toasts, bulma toasts, vuejs alerts, bulma alerts, vue toasts |

## Links

- npm: https://www.npmjs.com/package/@billow/toast
- Repository: https://gitlab.com/billow-thunder/toast
- Homepage: https://gitlab.com/billow-thunder/toast#readme
- Issues: https://gitlab.com/billow-thunder/toast/issues
- npm.io page: https://npm.io/package/@billow/toast

## Dependencies (1)

- [velocity-animate](https://npm.io/package/velocity-animate.md) ^1.5.0

## Alternatives

- [update-check](https://npm.io/package/update-check.md) — 4.0M weekly downloads
- [react-native-onesignal](https://npm.io/package/react-native-onesignal.md) — 134.5K weekly downloads
- [react-redux-toastr](https://npm.io/package/react-redux-toastr.md) — 33.7K weekly downloads
- [@nocobase/plugin-notification-manager](https://npm.io/package/@nocobase/plugin-notification-manager.md) — 2.0K weekly downloads
- [react-simple-toasts](https://npm.io/package/react-simple-toasts.md) — 1.9K weekly downloads

## Recent versions

- 1.0.7 (latest) — 2022-06-06
- 1.0.6 — 2018-11-29
- 1.0.5 — 2018-11-29
- 1.0.4 — 2018-11-29
- 1.0.3 — 2018-11-29
- 1.0.2 — 2018-11-29
- 1.0.1 — 2018-09-30
- 1.0.0 — 2018-08-13

## README

# Toast for Vue

Toast alerts/notifications for Vue apps. Originally authored by Yev Vlasenko, this clone only uses Velocity animations and adds additional features, such as shortcut prototypes and callback handling at toast and toaster level. It’s also designed specifically for Bulma, though it doesn’t enforce it – you can always provide your own styles.

Original package: https://github.com/euvl/vue-notification

## Install

```shell
npm install --save @billow/toast
```

If you use NPM 5+, you can omit `--save`.

### Usage

```javascript
import Vue from 'vue'
import Toast from '@billow/toast'

Vue.use(Toast)
```

Install the toaster in the app root (wherever Vue is mounted):

```html
<!-- Default toaster -->
<toaster/>

<!-- If you need another group -->
<toaster group="french" />

<!-- if you need close buttons to appear on the toasts (the value will be used as the class) -->
<toaster close-button="delete" group="french" />
```

Pop a toast from a component:

```js
this.$toast({
  group: 'french', // omit if you don't have a group name
  title: 'Important message',
  text: 'Toasty toast toast.',
  closeButton: 'delete', // defaults to false, and not available to the shortcut methods
});
```

If you’d like to change the prototype name, simple provide your own:

```js
Vue.use(Toast, {
  name: 'bread'
})

// In your component
this.$bread(…)
```

In the same way, you can also change the container name:

```js
Vue.use(Toast, {
  name: 'bread',
  containerName: 'basket'
})
```

```html
// In your root
<basket/>
```

## Props

All props are optional.

Name | Type | Default | Description
-- | -- | -- | --
animation | Object  | (see below) | Optional animation configuration
callback | Function | false | The function to call when a toast in the toaster is clicked. See the callback example for more.
classes | String/Array | 'toast' | List of classes that will be applied to toast element
ease-enter | String | 'easeOutSine' | The easing function to call for the `enter` animation function on all toasts within the toaster
ease-leave | String | 'easeInSine' | The easing function to call for the `leave` animation function on all toasts within the toaster
delay | Number | 100 | The delay before the toast appears
duration | Number  | 4000 | Time in ms that toast stays visible (if **negative**, it will stay **forever** or until clicked)
group | String  | null | Name of the toaster (holds toasts), if specified
max | Number  | 3 | Maximum number of toast that can be shown in its toaster
position | String/Array | 'bottom right' | Part of the screen where toast will pop out
reverse | Boolean | false | Show toasts in reverse order in its toaster
speed | Number  | 375 | Animation speed in ms
width | Number/String  | 375 | Width of toaster –  `%` or `px` CSS string or number.<br>Valid values: '100%', '200px', 200

### Default animation

```js
{
  enter: element => {
    let height = element.clientHeight
    return {
      height: [height, 0],
      opacity: [1, 0]
    }
  },
  leave: {
    height: 0,
    opacity: [0, 1]
  }
}
```

## `$toast`

```js
this.$toast({
  group: 'french',
  type: 'info', // corresponds to a Bulma color (see the colours section)
  title: 'Look!',
  text: 'This is <em>italic</em>.',
  duration: 10000,
  speed: 1000
  data: {
    something: 'I’ll be available in a custom slot.'
  },

  // Callback to fire when toast is clicked
  callback: (toast, close) => {
    say('what!')
    close() // closes the toast
  }
})
```

> Title and Text can be HTML.

### Simplified `$toast` and prototype shortcuts

```js
// Just a simple toast.
this.$toast('text')

// These are shortcut helpers for simple toasts.
this.$success('Operation was successful')
this.$warning('Warning emitted.')
this.$error('There was an error.')
this.$info('Some info.')
this.$log('Logging here.')

// If you'd like a title, pass it in as the first argument.
// This only works on the helpers above, and not on $toast.
this.$success('Done!', 'Operation was successful')
```

If you find a prototype shortcut is interfering with another prototype from another plugin, simply specify which ones you want at install-time:

```js
Vue.use(Toast, {
  types: ['success', 'error']
})
```

As an alternative: If you need both a prototype shortcut and the interfering prototype, simply tell Toast to namespace the shortcuts:

```js
Vue.use(Toast, {
  namespaced: true,
})
```

This will install the prototypes under the `$toast` namespace (or whatever you may have called it using the `name` option).

```js
this.$toast.error(…)
```

You can also provide your own prototype shortcuts and use them:

```js
Vue.use(Toast, {
  types: ['notify', 'moan']
})

this.$moan(':(', 'Something went wrong.')
```

You can add types to the existing ones:

```js
Vue.use(Toast, {
  types: [...Toast.types, 'notify', 'moan']
})
```

If you do this, remember to add custom styles for them. If you don’t, the default style will be used.

And lastly, you can skip the prototypes altogether:

```js
Vue.use(Toast, {
  types: []
})
```

This will mean that you can only use `$toast` directly.

## Calling outside a component

If you’d like to make toast outside a component (like in a store module, for example), you can just call it on Vue.

```js
import Vue from 'vue'

Vue.$toast(...)
Vue.$success(...)
// etc.
```

## Groups

If you are planning to have two or more completely different types of toasts (for example, authentication error messages in the top center and generic app notifications in the bottom-right corner), specify `group` property on the `toasts` container (the toaster):

```html
<toaster group="auth"/>
<toaster group="app"/>
```

```js
this.$toast({
  type: 'error',
  group: 'auth',
  text: 'Invalid credentials.'
})
```

## Position

The `position` toaster prop requires a string with 2 keywords for vertical and horizontal postion.

Format: `"<vertical> <horizontal>"`.

- Horizontal options: `left`, `center`, `right`
- Vertical options: `top`, `bottom`

Default is "bottom right".

Example:

```vue
<toaster position="top left"/>
```

## Styling

Styles are not loaded by default. However, Toast comes with a default stylesheet that makes use of Bulma. To use the stylesheet:

```scss
// ... Import anything Bulma related first (such as a custom scaffold, or the entire Bulma library)

@import '~@billow/toast/styles'
```

### Colours

The following table shows which toast types are mapped wo which colours:

Type | Colour
-- | --
default | `$primary`
`error` | `$danger`
`info` | `$info`
`log` | `$ark`
`success` | `$success`
`warning` | `$warning`

### Variables

You can override the following variables by declaring them _before_ you import the stylesheet:

```scss
$toast-border-radius: $radius;
$toast-default-background-color: $primary;
$toast-default-text-color: $primary-invert;
$toast-font-size: 1rem;
$toast-left-border-width: 5px;
$toast-margin: 0 0.4rem 0.4rem;
$toast-padding: 0.75rem;
$toast-title-font-weight: $weight-bold;
$toast-z-index: 999;
```

### Custom styling

You can add custom styles for toasts. Here's the SCSS structure:

```scss
.french-toast {
  // Style of the notification itself

  .toast-title {
    // Style for title line
  }

  .toast-content {
    // Style for content
  }

  &.french {
    /**
     * Style for specific type of toast that will be applied when you
     * call toast with the type parameter:
     *   this.$toast({ type: 'french', message: 'I’m French.' })
     */
  }
}
```

Use the `classes` prop to apply the style to all toasts within the toaster.

```html
<toaster classes="french-toast"/>
```

## Custom slots

A scoped slot named `toast` is available if you'd like to override the structure of a toast for a specific toaster.

Scope props:

Name | Type | Description
-- | -- | --
toast | Object | The toast object
close | Function | Closes the toast

Example:

```vue
<toaster group="french-toast" position="top center">
  <template slot="toast" slot-scope="props">
    <div class="notification-toast">
      <icon icon="bell lg" class="is-medium" />
      <div class="toast-content" @click="event(props.item, props.close)">
        <p class="has-text-weight-bold">{{ props.item.title }}</p>
        <div class="custom-template-text">{{ props.item.text }}</div>
      </div>
      <a @click="props.close" class="delete"></a>
    </div>
  </template>
</toaster>
```

## Cleaning up

To remove all toasts, use `clean: true` parameter.

```javascript
this.$toast({
  group: 'foo', // optional
  clean: true
})
```

## Development

If you’d like to contribute to Toast, simply clone the package, install the demo dependencies, and run the demo.

```shell
git clone git@gitlab.com:billow-thunder/toast.git
cd toast/demo
npm ci # Install against the package-lock
npx poi # Starts the dev-server at localhost:4000
```

---
_Source: https://npm.io/package/@billow/toast · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._