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:

ParameterTypeDefaultDescription
elHTMLElementToast element. Can be useful if you already have Toast element in your HTML and want to create new instance using this element
iconstringToast icon HTML layout, e.g. <i class="f7-icons">house</i> or image <img src="path/to/icon.png" />
textstringToast inner text
positionstringbottomToast position. Can be bottom, center or top
horizontalPositionstringleftToast horizontal alignment on wide screen. Has effects only on top and bottom toasts. Can be left, center or right
closeButtonbooleanfalseAdds toast close button
closeButtonColorstringOne of the default color themes
closeButtonTextstringOkClose button text
closeTimeoutnumberTimeout delay (in ms) to close toast automatically
cssClassstringAdditional css class to add
destroyOnClosebooleanfalseDestroys toast instance on close
renderfunctionCustom function to render Toast. Must return toast html
onobject

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.appLink to global app instance
toast.elToast HTML element
toast.$elDom7 instance with toast HTML element
toast.paramsToast 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

EventTargetDescription
toast:openToast Element<div class="toast">Event will be triggered when Toast starts its opening animation
toast:openedToast Element<div class="toast">Event will be triggered after Toast completes its opening animation
toast:closeToast Element<div class="toast">Event will be triggered when Toast starts its closing animation
toast:closedToast 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.

EventArgumentsTargetDescription
closeButtonClicktoasttoastEvent will be triggered when user clicks on Toast close button. As an argument event handler receives toast instance
toastCloseButtonClicktoastapp
opentoasttoastEvent will be triggered when Toast starts its opening animation. As an argument event handler receives toast instance
toastOpentoastapp
openedtoasttoastEvent will be triggered after Toast completes its opening animation. As an argument event handler receives toast instance
toastOpenedtoastapp
closetoasttoastEvent will be triggered when Toast starts its closing animation. As an argument event handler receives toast instance
toastClosetoastapp
closedtoasttoastEvent will be triggered after Toast completes its closing animation. As an argument event handler receives toast instance
toastClosedtoastapp
beforeDestroytoasttoastEvent will be triggered right before Toast instance will be destroyed. As an argument event handler receives toast instance
toastBeforeDestroytoastapp

CSS Variables

Below is the list of related CSS variables (CSS custom properties).

:root {
  --f7-toast-text-color: #fff;
  --f7-toast-font-size: 14px;
  --f7-toast-icon-size: 48px;
  --f7-toast-max-width: 568px;
}
.ios {
  --f7-toast-bg-color: rgba(0, 0, 0, 0.75);
  --f7-toast-bg-color-rgb: 0, 0, 0;
  --f7-toast-padding-horizontal: 16px;
  --f7-toast-padding-vertical: 12px;
  --f7-toast-border-radius: 8px;
  --f7-toast-button-min-width: 64px;
}
.md {
  --f7-toast-bg-color: #323232;
  --f7-toast-padding-horizontal: 24px;
  --f7-toast-padding-vertical: 14px;
  --f7-toast-border-radius: 4px;
  --f7-toast-button-min-width: 64px;
}
.aurora {
  --f7-toast-bg-color: #323232;
  --f7-toast-padding-horizontal: 16px;
  --f7-toast-padding-vertical: 16px;
  --f7-toast-border-radius: 8px;
  --f7-toast-button-min-width: 32px;
}

Examples

<template>
  <div id="app">
    <div class="view view-main view-init">
      <!-- source start -->
      <div class="page">
        <div class="navbar">
          <div class="navbar-bg"></div>
          <div class="navbar-inner">
            <div class="title">Toast</div>
          </div>
        </div>
        <div class="page-content">
          <div class="block block-strong">
            <p>
              <a href="#" class="button button-fill" @click=${showToastBottom}>Toast on Bottom</a>
            </p>
            <p>
              <a href="#" class="button button-fill" @click=${showToastTop}>Toast on Top</a>
            </p>
            <p>
              <a href="#" class="button button-fill" @click=${showToastCenter}>Toast on Center</a>
            </p>
            <p>
              <a href="#" class="button button-fill" @click=${showToastIcon}>Toast with icon</a>
            </p>
            <p>
              <a href="#" class="button button-fill" @click=${showToastLargeMessage}>Toast with large message</a>
            </p>
            <p>
              <a href="#" class="button button-fill" @click=${showToastWithButton}>Toast with close button</a>
            </p>
            <p>
              <a href="#" class="button button-fill" @click=${showToastWithCustomButton}>Toast with custom button</a>
            </p>
            <p>
              <a href="#" class="button button-fill" @click=${showToastWithCallback}>Toast with callback on close</a>
            </p>
          </div>
        </div>
        <!-- source start -->
      </div>
    </div>
  </div>
</template>
<script>
  export default (props, { $f7, $theme, $on }) => {
    let toastBottom;
    let toastTop;
    let toastCenter;
    let toastIcon;
    let toastLargeMessage;
    let toastWithButton;
    let toastWithCustomButton;
    let toastWithCallback;

    const showToastBottom = () => {
      // Create toast
      if (!toastBottom) {
        toastBottom = $f7.toast.create({
          text: 'This is default bottom positioned toast',
          closeTimeout: 2000,
        });
      }
      // Open it
      toastBottom.open();
    }
    const showToastTop = () => {
      // Create toast
      if (!toastTop) {
        toastTop = $f7.toast.create({
          text: 'Top positioned toast',
          position: 'top',
          closeTimeout: 2000,
        });
      }
      // Open it
      toastTop.open();
    }
    const showToastCenter = () => {
      // Create toast
      if (!toastCenter) {
        toastCenter = $f7.toast.create({
          text: 'I\'m on center',
          position: 'center',
          closeTimeout: 2000,
        });
      }
      // Open it
      toastCenter.open();
    }
    const showToastIcon = () => {
      // Create toast
      if (!toastIcon) {
        toastIcon = $f7.toast.create({
          icon: $theme.ios || $theme.aurora ? '<i class="f7-icons">star_fill</i>' : '<i class="material-icons">star</i>',
          text: 'I\'m with icon',
          position: 'center',
          closeTimeout: 2000,
        });
      }
      // Open it
      toastIcon.open();
    }
    const showToastLargeMessage = () => {
      // Create toast
      if (!toastLargeMessage) {
        toastLargeMessage = $f7.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,
        });
      }
      // Open it
      toastLargeMessage.open();
    }
    const showToastWithButton = () => {
      // Create toast
      if (!toastWithButton) {
        toastWithButton = $f7.toast.create({
          text: 'Toast with additional close button',
          closeButton: true,
        });
      }
      // Open it
      toastWithButton.open();
    }
    const showToastWithCustomButton = () => {
      // Create toast
      if (!toastWithCustomButton) {
        toastWithCustomButton = $f7.toast.create({
          text: 'Custom close button',
          closeButton: true,
          closeButtonText: 'Close Me',
          closeButtonColor: 'red',
        });
      }
      // Open it
      toastWithCustomButton.open();
    }
    const showToastWithCallback = () => {
      // Create toast
      if (!toastWithCallback) {
        toastWithCallback = $f7.toast.create({
          text: 'Callback on close',
          closeButton: true,
          on: {
            close: function () {
              $f7.dialog.alert('Toast closed');
            },
          }
        });
      }
      // Open it
      toastWithCallback.open();
    }

    $on('pageBeforeOut', () => {
      $f7.toast.close();
    })

    $on('pageBeforeRemove', () => {
      // Destroy toasts when page removed
      if (toastBottom) toastBottom.destroy();
      if (toastTop) toastTop.destroy();
      if (toastCenter) toastCenter.destroy();
      if (toastIcon) toastIcon.destroy();
      if (toastLargeMessage) toastLargeMessage.destroy();
      if (toastWithButton) toastWithButton.destroy();
      if (toastWithCustomButton) toastWithCustomButton.destroy();
      if (toastWithCallback) toastWithCallback.destroy();
    })

    return $render;
  }
</script>