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

    app.toast.show(parameters)- create Toast instance and show immediately

    • parameters - object. Object with toast parameters

    Method returns created 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
    closeTimeout number Timeout delay (in ms) to close toast automatically
    cssClass string Additional css class to add
    destroyOnClose boolean false Destroys toast instance on close
    render function Custom function to render Toast. Must return toast html
    on object Object with events handlers. For example:
    var toast = app.toast.create({
      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();
    });