Skip to content

Commit 263f206

Browse files
tmorehousetmorehouse
authored
feat(toast): updates to toaster SCSS and structure and enable hover-pause (#3135)
1 parent 61cca79 commit 263f206

File tree

5 files changed

+279
-137
lines changed

5 files changed

+279
-137
lines changed

‎src/_variables.scss

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,6 @@ $b-toaster-offset-top: 0.5rem !default;
1010
$b-toaster-offset-bottom: $b-toaster-offset-top !default;
1111
$b-toaster-offset-left: $b-toaster-offset-top !default;
1212
$b-toaster-offset-right: $b-toaster-offset-top !default;
13-
$b-toaster-max-width: $toast-max-width !default;
14-
// Make toasts fit within small screens
15-
$b-toaster-min-width: calc(#{min(320px, $toast-max-width)} - #{$b-toaster-offset-left + $b-toaster-offset-right}) !default;
1613

1714
$b-toast-bg-level: $alert-bg-level !default;
1815
$b-toast-border-level: $alert-border-level !default;

‎src/components/toast/README.md

Lines changed: 124 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,7 @@
44
> which are easily customizable for generating alert messages.
55
66
Toasts are lightweight notifications designed to mimic the push notifications that have been
7-
popularized by mobile and desktop operating systems. They’re built with flexbox, so they’re easy to
8-
align and position inside a `<b-toaster>` target component.
7+
popularized by mobile and desktop operating systems.
98

109
Toasts are intended to be small interruptions to your visitors or users, and therefore should
1110
contain minimal, to-the-point, non-interactive content.
@@ -23,8 +22,8 @@ Toast headers use the style `'display: flex'`, allowing easy alignment of conten
2322
Bootstrap's [margin and flexbox utility classes](/docs/reference/utility-classes).
2423

2524
Toasts are slightly translucent, too, so they blend over whatever they might appear over. For
26-
browsers that support the `backdrop-filter` CSS property, we’ll also attempt to blur the elements
27-
under a toast.
25+
browsers that support the `backdrop-filter` CSS property, they also attempt to blur the elements
26+
under the toast.
2827

2928
```html
3029
<template>
@@ -40,29 +39,34 @@ under a toast.
4039

4140
**Note:** we are using the `static` prop in the above example to render the toast in-pace in the
4241
document, rather than transporting it to a `<b-toaster>` target container. And we have added classes
43-
`bg-secondary` and `progress-bar-striped` to the outer <samp>&lt;div&gt;</samp> for illustrative
44-
purposes of toast transparency only.
42+
`bg-secondary` and `progress-bar-striped` to the outer `<div>` for illustrative purposes of toast
43+
transparency only.
4544

46-
### Toast features
45+
### Toast features and notes
4746

4847
- Toasts can be generated on demand via the injection `this.$bvToast` object, or manually created
4948
using the `<b-toast>` component.
5049
- Toasts will auto hide after a default of 5 seconds (5000ms). The duration can be changed via the
5150
`auto-hide-delay` prop (value is specified in milliseconds), and disabled with the `no-auto-hide`
5251
prop.
52+
- When auto-hide is enabled, and you hover over the toast, the auto-hide countdown will be paused
53+
until you unhover the toast. You can disabled this feature by setting the `no-hover-pause` prop
54+
to `true`.
5355
- Toasts include a close button on their top right to allow users to manually dismiss them. The
54-
close button can be hidden via the `no-close-button` prop.
56+
close button can be removed via the `no-close-button` prop.
5557
- Titles are optional, but should be included, titles are rendered inside a `<strong>` element,
5658
unless using the `toast-title` slot.
5759
- If you disable the auto-hide feature, avoid hiding the close button, or if you hide the close
5860
button be sure to allow the toast to auto-dismiss.
5961
- Toast transparency can be disabled by setting the `solid` prop to `true`.
60-
- Toasts will show inside a named `<b-toaster>` target component. BootstrapVue comes with four
62+
- Toasts will show inside a named `<b-toaster>` target component. BootstrapVue comes with several
6163
pre-defined toaster targets. Toasts will check for the named toaster in the document before they
6264
are shown, and will dynamically create the named toaster target if one is not found.
6365
- Toaster targets are defined completely with CSS for controlling the positioning of the contained
6466
`<b-toast>` components.
6567
- Toasts can can targeted to any named toaster.
68+
- Toasts are wrapped in a `<div>` with class `b-toast` to allow for Vue list-transition support when
69+
displayed in a toaster component.
6670

6771
BootstrapVue uses [PortalVue](https://portal-vue.linusb.org/) to transport toasts into the toasters.
6872

@@ -75,10 +79,12 @@ Use the `this.$bvToast.toast()` method to generate on demand toasts. The method
7579
arguments:
7680

7781
- `message`: the content of the toast body (either a string, or an array of `VNodes`)
78-
- `options`: an options object for providing a title and/or additional configuration options.
82+
- `options`: an optional options object for providing a title and/or additional configuration
83+
options.
7984

8085
The options argument accepts most of the props that the `<b-toast>` component accepts (with the
81-
exception of `static`, and `visible`) in <samp>camelCase</samp> name format.
86+
exception of `static`, and `visible`) in <samp>camelCase</samp> name format instead of
87+
<samp>kebab-case</samp>.
8288

8389
```html
8490
<template>
@@ -129,20 +135,20 @@ the `solid` prop to `true`
129135

130136
### Variants
131137

132-
BootstrapVue toasts provide custom CSS to define color variants. variants follow the standard
138+
BootstrapVue toasts provide custom CSS to define color variants. Variants follow the standard
133139
Bootstrap V4 variant names. If you have custom SCSS defined Bootstrap color variants, the toast
134140
custom SCSS will automatically create toast variants for you.
135141

136142
```html
137143
<template>
138144
<div>
139-
<b-button @click="makeToast()">Default</b-button>
140-
<b-button variant="primary" @click="makeToast('primary')">Primary</b-button>
141-
<b-button variant="secondary" @click="makeToast('secondary')">Secondary</b-button>
142-
<b-button variant="danger" @click="makeToast('danger')">Danger</b-button>
143-
<b-button variant="warning" @click="makeToast('warning')">Warning</b-button>
144-
<b-button variant="success" @click="makeToast('success')">Success</b-button>
145-
<b-button variant="info" @click="makeToast('info')">Info</b-button>
145+
<b-button @click="makeToast()" class="mb-2">Default</b-button>
146+
<b-button variant="primary" @click="makeToast('primary')" class="mb-2">Primary</b-button>
147+
<b-button variant="secondary" @click="makeToast('secondary')" class="mb-2">Secondary</b-button>
148+
<b-button variant="danger" @click="makeToast('danger')" class="mb-2">Danger</b-button>
149+
<b-button variant="warning" @click="makeToast('warning')" class="mb-2">Warning</b-button>
150+
<b-button variant="success" @click="makeToast('success')" class="mb-2">Success</b-button>
151+
<b-button variant="info" @click="makeToast('info')" class="mb-2">Info</b-button>
146152
</div>
147153
</template>
148154

@@ -170,16 +176,24 @@ SCSS):
170176

171177
- `b-toaster-top-right`
172178
- `b-toaster-top-left`
179+
- `b-toaster-top-center`
180+
- `b-toaster-top-full`
173181
- `b-toaster-bottom-right`
174182
- `b-toaster-bottom-left`
183+
- `b-toaster-bottom-center`
184+
- `b-toaster-bottom-full`
175185

176186
```html
177187
<template>
178188
<div>
179-
<b-button @click="toast('b-toaster-top-right')">b-toaster-top-right</b-button>
180-
<b-button @click="toast('b-toaster-top-left')">b-toaster-top-left</b-button>
181-
<b-button @click="toast('b-toaster-bottom-right')">b-toaster-bottom-right</b-button>
182-
<b-button @click="toast('b-toaster-bottom-left')">b-toaster-bottom-left</b-button>
189+
<b-button @click="toast('b-toaster-top-right')" class="mb-2">b-toaster-top-right</b-button>
190+
<b-button @click="toast('b-toaster-top-left')" class="mb-2">b-toaster-top-left</b-button>
191+
<b-button @click="toast('b-toaster-top-center')" class="mb-2">b-toaster-top-center</b-button>
192+
<b-button @click="toast('b-toaster-top-full')" class="mb-2">b-toaster-top-full</b-button>
193+
<b-button @click="toast('b-toaster-bottom-right', true)" class="mb-2">b-toaster-bottom-right</b-button>
194+
<b-button @click="toast('b-toaster-bottom-left', true)" class="mb-2">b-toaster-bottom-left</b-button>
195+
<b-button @click="toast('b-toaster-bottom-center', true)" class="mb-2">b-toaster-bottom-center</b-button>
196+
<b-button @click="toast('b-toaster-bottom-full', true)" class="mb-2">b-toaster-bottom-full</b-button>
183197
</div>
184198
</template>
185199

@@ -191,12 +205,13 @@ SCSS):
191205
}
192206
},
193207
methods: {
194-
toast(toaster) {
208+
toast(toaster, append = false) {
195209
this.counter++
196210
this.$bvToast.toast(`Toast ${this.counter} body content`, {
197211
title: `Toaster ${toaster}`,
198212
toaster: toaster,
199-
solid: true
213+
solid: true,
214+
appendToast: append
200215
})
201216
}
202217
}
@@ -206,14 +221,13 @@ SCSS):
206221
<!-- toast-targets.vue -->
207222
```
208223

209-
**Note**: Toaster target names that have not been defined in CSS will render at the bottom of the
210-
document, stacked and not positioned (appended to `<body>` inside a `<b-toaster>` with class name
211-
and ID set to the toaster target name). The only default styling the toaster will have is
212-
`position: fixed;`, a `max-width` and a `z-index` of `1100`.
213-
214-
Avoid using both `b-toaster-top-left` and `b-toaster-top-right`, or `b-toaster-bottom-left` and
215-
`b-toaster-bottom-right`, at the same time in your app as notifications could be obscured on small
216-
screens (i.e. `xs`).
224+
**Notes:**
225+
- Toaster target names that have not been defined in CSS will render at the bottom of the
226+
document, stacked and not positioned (appended to `<body>` inside a `<b-toaster>` with class name
227+
and ID set to the toaster target name). The only default styling the toaster will have is a
228+
`z-index` of `1100`.
229+
- Avoid using `b-toaster-top-*` together, or `b-toaster-bottom-*` togehter, at the same time in your
230+
app as notifications could be obscured/overlap on small screens (i.e. `xs`).
217231

218232
### Prepend and append
219233

@@ -224,8 +238,12 @@ the order they were created. To append new toasts to the bottom, set the `append
224238
### Auto-hide
225239

226240
Change to auto hide delay time via the `auto-hide-delay` prop (value is in milliseconds), which
227-
defaults to `5000`. Or, disable the auto-hide feature completely by setting the `no-auto-hide` prop
228-
to `true`.
241+
defaults to `5000` (minimum value `1000`). Or, disable the auto-hide feature completely by setting
242+
the `no-auto-hide` prop to `true`.
243+
244+
When auto-hide is enabled, hovering over the toast will pause the auto-hide timer. When you
245+
un-hover the toast, the auto-hide timer will be resumed. You can disable this feature by setting
246+
the `no-hover-pause` prop to `true`.
229247

230248
### Toast roles
231249

@@ -241,18 +259,28 @@ For more information, please the the [Accessibility](#accessibility) section bel
241259
Optionally convert the toast body to a link (`<a>`) or `<router-link>` (or `<nuxt-link>`) via the
242260
`href` and `to` props respectively. When set, the entire toast body becomes a link.
243261

244-
### Slots
245-
246-
- `toast-title`: Content to replace the default title element.
247-
- `default`: Content of the toast body
248-
249-
Both slots are optionally scoped with the following scope:
262+
```html
263+
<template>
264+
<div>
265+
<b-button @click="toast()">Toast with link</b-button>
266+
</div>
267+
</template>
250268

251-
| Method or property | Description |
252-
| ------------------ | ------------------------------------------------------------------------------- |
253-
| `hide()` | Hides the toast when called. Useful if you are providing your own close button. |
269+
<script>
270+
export default {
271+
methods: {
272+
toast() {
273+
this.$bvToast.toast(`Toast with action link`, {
274+
href: '#foo',
275+
title: 'Example'
276+
})
277+
}
278+
}
279+
}
280+
</script>
254281

255-
Slots are only available when using the `<b-toast>` component.
282+
<!-- toast-link.vue -->
283+
```
256284

257285
## `<b-toast>` component
258286

@@ -272,6 +300,39 @@ You can force a `<b-toast>` to appear in-place in the document by setting the `s
272300
`true`. you still need to show and hide the toast, but it will not be transported into a toaster
273301
component.
274302

303+
```html
304+
<template>
305+
<div>
306+
<b-button @click="$bvToast.show('my-toast')">Show toast</b-button>
307+
308+
<b-toast id="my-toast" variant="warning" solid>
309+
<div slot="toast-title" class="d-flex flex-grow-1 align-items-baseline">
310+
<b-img blank blank-color="#ff5555" class="mr-2" width="12" height="12"></b-img>
311+
<strong class="mr-auto">Notice!</strong>
312+
<small class="text-muted mr-2">42 seconds ago</small>
313+
</div>
314+
This is the content of the toast.
315+
It is short and to the point.
316+
</b-toast>
317+
</div>
318+
</template>
319+
320+
<!-- toast-component.vue -->
321+
```
322+
323+
### Slots
324+
325+
- `toast-title`: Content to replace the default title element.
326+
- `default`: Content of the toast body
327+
328+
Both slots are optionally scoped with the following scope:
329+
330+
| Method or property | Description |
331+
| ------------------ | ------------------------------------------------------------------------------- |
332+
| `hide()` | Hides the toast when called. Useful if you are providing your own close button. |
333+
334+
Slots are only available when using the `<b-toast>` component.
335+
275336
## `<b-toaster>` target component
276337

277338
The `<b-toaster>` component provides a container where toasts will appear (the _Toaster_). Toasters
@@ -292,25 +353,32 @@ SCSS:
292353

293354
- `b-toaster-top-right`
294355
- `b-toaster-top-left`
356+
- `b-toaster-top-center`
357+
- `b-toaster-top-full`
295358
- `b-toaster-bottom-right`
296359
- `b-toaster-bottom-left`
360+
- `b-toaster-bottom-center`
361+
- `b-toaster-bottom-full`
297362

298363
The above toasters place the toasts in a stacked (columnar format), fixed within the viewport
299364
(meaning they will always be in view regardless of viewport scroll position). If there are more
300-
toasts than can fit on the viewport screen, some will be visually hidden until other toasts are
301-
closed.
365+
toasts than can fit on the viewport screen, some will be visually hidden offscreen until other
366+
toasts are closed.
302367

303368
`<b-toast>` uses the `b-toaster-top-right` toaster by default.
304369

305-
**Note:** If a `<b-toaster>` with the same name already exists in document (either auto-created by
306-
`<b-toast>`, or manually placed), then `<b-toaster>` will just render an empty `<div>` element and
307-
issue a console warning.
308-
309-
<!--
310-
### Toaster transition
311-
312-
TBD
313-
-->
370+
**Notes:**
371+
- If a `<b-toaster>` with the same name already exists in document (either auto-created by
372+
`<b-toast>`, `this.$bvToast.toast()`, or manually placed), then `<b-toaster>` will just render
373+
an empty `<div>` element and issue a console warning.
374+
- If manually placing a `<b-toaster>` component, make sure it is placed as the last element in
375+
bottom of your app root element, so that it will be available to all pages in your app.
376+
- Toasters that get destroyed, they will be auto re-created if a new toast targeted for the
377+
toaster name is shown.
378+
- In the majority of use cases, you should not need to manually place a `<b-toaster>` component
379+
in your app, as they will be auto generated on demand if needed. But if you need to override
380+
any of the toaster default settings, ensure that you place the toaster in your app in a location
381+
that will not be destroyed due to changes in the route.
314382

315383
## Accessibility
316384

0 commit comments

Comments
 (0)