Toast

Toasts provide brief feedback about an operation through a message on the screen.

Toast App Methods

Let's look at related App methods to work with Toast:

app.toast.create(parameters)- create Toast instance

  • parameters - object. Object with toast parameters

Method returns created Toast's instance

app.toast.destroy(el)- destroy Toast instance

  • el - HTMLElement or string (with CSS Selector) or object. Toast element or Toast instance to destroy.

app.toast.get(el)- get Toast instance by HTML element

  • el - HTMLElement or string (with CSS Selector). Toast element.

Method returns Toast's instance

app.toast.open(el, animate)- opens Toast

  • el - HTMLElement or string (with CSS Selector). Toast element to open.
  • animate - boolean. Open Toast with animation.

Method returns Toast's instance

app.toast.close(el, animate)- closes Toast

  • el - HTMLElement or string (with CSS Selector). Toast element to close.
  • animate - boolean. Close Toast with animation.

Method returns Toast's instance

Toast Parameters

Now let's look at list of available parameters we need to create Toast:

Parameter Type Default Description
el HTMLElement Toast element. Can be useful if you already have Toast element in your HTML and want to create new instance using this element
icon string Toast icon HTML layout, e.g. <i class="f7-icons">home</i> or image <img src="path/to/icon.png">
text string Toast inner text
position string bottom Toast position. Can be bottom, center or top
closeButton boolean false Adds toast close button
closeButtonColor string One of the default color themes
closeButtonText string Ok Close button text
cssClass string Additional css class to add
render function Custom function to render Toast. Must return toast html
on object Object with events handlers. For example:
var toast = app.toast.create({
  title: 'John Doe'
  text: 'Hello, how are you?',
  on: {
    opened: function () {
      console.log('Toast opened')
    }
  }
})

Note that all following parameters can be used in global app parameters under toast property to set defaults for all toasts. For example:

var app = new Framework7({
  toast: {
    closeTimeout: 3000,
    closeButton: true,
  }
});

Toast Methods & Properties

So to create Toast we have to call:

var toast = app.toast.create({ /* parameters */ })

After that we have its initialized instance (like toast variable in example above) with useful methods and properties:

Properties
toast.app Link to global app instance
toast.el Toast HTML element
toast.$el Dom7 instance with toast HTML element
toast.params Toast parameters
Methods
toast.open() Open toast
toast.close() Close toast
toast.on(event, handler) Add event handler
toast.once(event, handler) Add event handler that will be removed after it was fired
toast.off(event, handler) Remove event handler
toast.off(event) Remove all handlers for specified event
toast.emit(event, ...args) Fire event on instance

Toast Events

Toast will fire the following DOM events on toast element and events on app and toast instance:

DOM Events

Event Target Description
toast:open Toast Element<div class="toast"> Event will be triggered when Toast starts its opening animation
toast:opened Toast Element<div class="toast"> Event will be triggered after Toast completes its opening animation
toast:close Toast Element<div class="toast"> Event will be triggered when Toast starts its closing animation
toast:closed Toast Element<div class="toast"> Event will be triggered after Toast completes its closing animation

App and Toast Instance Events

Toast instance emits events on both self instance and app instance. App instance events has same names prefixed with toast.

Event Arguments Target Description
closeButtonClick toast toast Event will be triggered when user clicks on Toast close button. As an argument event handler receives toast instance
toastCloseButtonClick toast app
open toast toast Event will be triggered when Toast starts its opening animation. As an argument event handler receives toast instance
toastOpen toast app
opened toast toast Event will be triggered after Toast completes its opening animation. As an argument event handler receives toast instance
toastOpened toast app
close toast toast Event will be triggered when Toast starts its closing animation. As an argument event handler receives toast instance
toastClose toast app
closed toast toast Event will be triggered after Toast completes its closing animation. As an argument event handler receives toast instance
toastClosed toast app
beforeDestroy toast toast Event will be triggered right before Toast instance will be destroyed. As an argument event handler receives toast instance
toastBeforeDestroy toast app

Examples

<div class="block">
  <p>
    <a href="#" class="button button-raised open-toast-bottom">Toast on Bottom</a>
  </p>
  <p>
    <a href="#" class="button button-raised open-toast-top">Toast on Top</a>
  </p>
  <p>
    <a href="#" class="button button-raised open-toast-center">Toast on Center</a>
  </p>
  <p>
    <a href="#" class="button button-raised open-toast-icon">Toast with icon</a>
  </p>
  <p>
    <a href="#" class="button button-raised open-toast-large">Toast with large message</a>
  </p>
  <p>
    <a href="#" class="button button-raised open-toast-button">Toast with close button</a>
  </p>
  <p>
    <a href="#" class="button button-raised open-toast-custom-button">Toast with custom button</a>
  </p>
  <p>
    <a href="#" class="button button-raised open-toast-callback">Toast with callback on close</a>
  </p>
</div>
var app = new Framework7();

var $$ = Dom7;

// Create bottom toast
var toastBottom = app.toast.create({
  text: 'This is default bottom positioned toast',
  closeTimeout: 2000,
});
// Create top toast
var toastTop = app.toast.create({
  text: 'Top positioned toast',
  position: 'top',
  closeTimeout: 2000,
});
// Create center toast
var toastCenter = app.toast.create({
  text: 'I\'m on center',
  position: 'center',
  closeTimeout: 2000,
});
// Create toast with icon
var toastIcon = app.toast.create({
  icon: app.theme === 'ios' ? '<i class="f7-icons">star</i>' : '<i class="material-icons">star</i>',
  text: 'I\'m with icon',
  position: 'center',
  closeTimeout: 2000,
});
// Create toast with large message
var toastLargeMessage = app.toast.create({
  text: 'This toast contains a lot of text. Lorem ipsum dolor sit amet, consectetur adipisicing elit. Nihil, quae, ab. Delectus amet optio facere autem sapiente quisquam beatae culpa dolore.',
  closeTimeout: 2000,
});
// Create toast with button
var toastWithButton = app.toast.create({
  text: 'Toast with additional close button',
  closeButton: true,
});
// Create toast with custom button text
var toastWithCustomButton = app.toast.create({
  text: 'Custom close button',
  closeButton: true,
  closeButtonText: 'Close Me',
  closeButtonColor: 'red',
});
// Create toast with callback on close
var toastWithCallback = app.toast.create({
  text: 'Callback on close',
  closeButton: true,
  on: {
    close: function () {
      app.dialog.alert('Toast closed');
    },
  }
});

// Open toasts
$$('.open-toast-bottom').on('click', function () {
  toastBottom.open();
});
$$('.open-toast-top').on('click', function () {
  toastTop.open();
});
$$('.open-toast-center').on('click', function () {
  toastCenter.open();
});
$$('.open-toast-icon').on('click', function () {
  toastIcon.open();
});
$$('.open-toast-large').on('click', function () {
  toastLargeMessage.open();
});
$$('.open-toast-button').on('click', function () {
  toastWithButton.open();
});
$$('.open-toast-custom-button').on('click', function () {
  toastWithCustomButton.open();
});
$$('.open-toast-callback').on('click', function () {
  toastWithCallback.open();
});