🔥 Meet Our New Project: t0ggles - Your Ultimate Project Management Tool!
SponsorsBecome a sponsor

Popup

Popup is a popup window with any HTML content that pops up over App's main content. Popup as all other overlays is part of so called "Temporary Views".

Popup layout is pretty simple:

<body>
  ...
  <div class="popup">
    Any HTML content goes here
  </div>
</body>

By default Popup has a bit different size on phones and tablets (iPad). On phones it is fullscreen while on tablets it is 630px width and height. If you want to make it fullscreen size on tablets, you should add additional "popup-tablet-fullscreen" class to the required popup:

<body>
  ...
  <!-- This popup has fullscreen size on tablets -->
  <div class="popup popup-tablet-fullscreen">
    Any HTML content goes here
  </div>
</body>

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

app.popup.create(parameters)- create Popup instance

  • parameters - object. Object with popup parameters

Method returns created Popup's instance

app.popup.destroy(el)- destroy Popup instance

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

app.popup.get(el)- get Popup instance by HTML element

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

Method returns Popup's instance

app.popup.open(el, animate)- opens Popup

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

Method returns Popup's instance

app.popup.close(el, animate)- closes Popup

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

Method returns Popup's instance

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

ParameterTypeDefaultDescription
elHTMLElementPopup element. Can be useful if you already have Popup element in your HTML and want to create new instance using this element
contentstringFull Popup HTML layout string. Can be useful if you want to create Popup element dynamically
backdropbooleantrueEnables Popup backdrop (dark semi transparent layer behind)
backdropElHTMLElement
string		HTML element or string CSS selector of custom backdrop element
backdropUniquebooleanIf enabled it creates unique backdrop element exclusively for this modal
closeByBackdropClickbooleantrueWhen enabled, popup will be closed on backdrop click
closeOnEscapebooleanfalseWhen enabled, popup will be closed on ESC keyboard key press
animatebooleantrueWhether the Popup should be opened/closed with animation or not. Can be overwritten in .open() and .close() methods
swipeToCloseboolean
string		falseWhether the Popup can be closed with swipe gesture. Can be true to allow to close popup with swipes to top and to bottom, or can be to-top (string) to allow only swipe to top to close popup, or to-bottom (string) to allow only swipe to bottom to close.
swipeHandlerHTMLElement
string		If not passed, then whole popup can be swiped to close. You can pass here HTML element or string CSS selector of custom element that will be used as a swipe target. (swipeToClose must be also enabled)
pushbooleanfalseWhen enabled it will push view behind on open. Works only when top safe area is in place. It can also be enabled by adding popup-push class to Popup element.
containerElHTMLElement
string		Element to mount modal to (default to app root element)
onobject

Object with events handlers. For example:

var popup = app.popup.create({
  content: '<div class="popup">...</div>',
  on: {
    opened: function () {
      console.log('Popup opened')
    }
  }
})

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

var app = new Framework7({
  popup: {
    closeByBackdropClick: false,
  }
});

If you use auto-initialized popups (e.g. you don't create them via app.popup.create), it is possible to pass all available popup parameters via data- attributes. For example:

<!-- Pass parameters as kebab-case data attributes -->
<div class="popup" data-close-on-escape="true" data-swipe-to-close="to-bottom">
  ...
</div>

So to create Popup we have to call:

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

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

Properties
popup.appLink to global app instance
popup.elPopup HTML element
popup.$elDom7 instance with popup HTML element
popup.backdropElBackdrop HTML element
popup.$backdropElDom7 instance with backdrop HTML element
popup.paramsPopup parameters
popup.openedBoolean prop indicating whether popup is opened or not
Methods
popup.open(animate)Open popup. Where
  • animate - boolean (by default true) - defines whether it should be opened with animation
popup.close(animate)Close popup. Where
  • animate - boolean (by default true) - defines whether it should be closed with animation
popup.destroy()Destroy popup
popup.on(event, handler)Add event handler
popup.once(event, handler)Add event handler that will be removed after it was fired
popup.off(event, handler)Remove event handler
popup.off(event)Remove all handlers for specified event
popup.emit(event, ...args)Fire event on instance

It is possible to open and close required popup (if you have them in DOM) using special classes and data attributes on links:

  • To open popup we need to add "popup-open" class to any HTML element (preferred to link)

  • To close popup we need to add "popup-close" class to any HTML element (preferred to link)

  • If you have more than one popup in DOM, you need to specify appropriate popup via additional data-popup=".my-popup" attribute on this HTML element

According to above note:

<!-- In data-popup attribute we specify CSS selector of popup we need to open -->
<p><a href="#" data-popup=".my-popup" class="popup-open">Open Popup</a></p>

<!-- And somewhere in DOM -->
<div class="popup my-popup">
  <div class="view">
    <div class="page">
      <div class="navbar">
        <div class="navbar-bg"></div>
        <div class="navbar-inner">
          <div class="title">Popup</div>
          <div class="right">
            <!-- Link to close popup -->
            <a class="link popup-close">Close</a>
          </div>
        </div>
      </div>
      <div class="page-content">
        ...
      </div>
    </div>
  </div>
  ...
</div>

Popup will fire the following DOM events on popup element and events on app and popup instance:

DOM Events

EventTargetDescription
popup:openPopup Element<div class="popup">Event will be triggered when Popup starts its opening animation
popup:openedPopup Element<div class="popup">Event will be triggered after Popup completes its opening animation
popup:closePopup Element<div class="popup">Event will be triggered when Popup starts its closing animation
popup:closedPopup Element<div class="popup">Event will be triggered after Popup completes its closing animation
popup:swipestartPopup Element<div class="popup">Event will be triggered in the beginning of swipe-to-close interaction (when user just started to drag popup)
popup:swipemovePopup Element<div class="popup">Event will be triggered on swipe-to-close move interaction
popup:swipeendPopup Element<div class="popup">Event will be triggered on swipe-to-close release
popup:swipeclosePopup Element<div class="popup">Event will be triggered when popup closed with swipe
popup:beforedestroyPopup Element<div class="popup">Event will be triggered right before Popup instance will be destroyed

App and Popup Instance Events

Popup instance emits events on both self instance and app instance. App instance events has same names prefixed with popup.

EventArgumentsTargetDescription
openpopuppopupEvent will be triggered when Popup starts its opening animation. As an argument event handler receives popup instance
popupOpenpopupapp
openedpopuppopupEvent will be triggered after Popup completes its opening animation. As an argument event handler receives popup instance
popupOpenedpopupapp
closepopuppopupEvent will be triggered when Popup starts its closing animation. As an argument event handler receives popup instance
popupClosepopupapp
closedpopuppopupEvent will be triggered after Popup completes its closing animation. As an argument event handler receives popup instance
popupClosedpopupapp
beforeDestroypopuppopupEvent will be triggered right before Popup instance will be destroyed. As an argument event handler receives popup instance
popupBeforeDestroypopupapp
swipeStartpopuppopup Event will be triggered in the beginning of swipe-to-close interaction (when user just started to drag popup)
popupSwipeStartpopupapp
swipeMovepopuppopup Event will be triggered on swipe-to-close move interaction
popupSwipeMovepopupapp
swipeEndpopuppopup Event will be triggered on swipe-to-close release
popupSwipeEndpopupapp
swipeClosepopuppopup Event will be triggered when popup closed with swipe
popupSwipeClosepopupapp

CSS Variables

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

Note that commented variables are not specified by default and their values is what they fallback to in this case.

:root {
  --f7-popup-border-radius: 0px;
  --f7-popup-tablet-width: 630px;
  --f7-popup-tablet-height: 630px;
  --f7-popup-push-offset: var(--f7-safe-area-top);
  /*
  --f7-popup-tablet-border-radius: var(--f7-popup-border-radius);
  */
}
.ios {
  --f7-popup-tablet-border-radius: 5px;
  --f7-popup-transition-duration: 400ms;
  --f7-popup-transition-timing-function: initial;
  --f7-popup-push-border-radius: 10px;
}
.md {
  --f7-popup-tablet-border-radius: 28px;
  --f7-popup-transition-duration: 600ms;
  --f7-popup-transition-timing-function: cubic-bezier(0, 1, 0.2, 1);
  --f7-popup-push-border-radius: 28px;
}

Examples

popup.html
<template>
  <div class="page">
    <div class="navbar">
      <div class="navbar-bg"></div>
      <div class="navbar-inner sliding">
        <div class="title">Popup</div>
      </div>
    </div>
    <div class="page-content">
      <div class="block block-strong-ios block-outline-ios">
        <p>Popup is a modal window with any HTML content that pops up over App's main content. Popup as all other
          overlays is part of so called "Temporary Views".</p>
        <p>
          <a class="button button-fill popup-open" data-popup=".demo-popup">Open Popup</a>
        </p>
        <p>
          <a class="button button-fill" @click=${createPopup}>Create Dynamic Popup</a>
        </p>
      </div>
      <div class="block-title">Swipe To Close</div>
      <div class="block block-strong-ios block-outline-ios">
        <p>Popup can be closed with swipe to top or bottom:</p>
        <p>
          <a class="button button-fill popup-open" data-popup=".demo-popup-swipe">Swipe To Close</a>
        </p>
        <p>Or it can be closed with swipe on special swipe handler and, for example, only to bottom:</p>
        <p>
          <a class="button button-fill popup-open" data-popup=".demo-popup-swipe-handler">With Swipe
            Handler</a>
        </p>
      </div>
      <div class="block-title">Push View</div>
      <div class="block block-strong-ios block-outline-ios">
        <p>Popup can push view behind. By default it has effect only when "safe-area-inset-top" is more than zero (iOS
          fullscreen webapp or iOS cordova app)</p>
        <p>
          <a class="button button-fill popup-open" data-popup=".demo-popup-push">Popup Push</a>
        </p>
      </div>
    </div>
    <div class="popup demo-popup">
      <div class="page">
        <div class="navbar">
          <div class="navbar-bg"></div>
          <div class="navbar-inner">
            <div class="title">Popup Title</div>
            <div class="right"><a class="link popup-close">Close</a></div>
          </div>
        </div>
        <div class="page-content">
          <div class="block">
            <p>Here comes popup. You can put here anything, even independent view with its own navigation. Also not,
              that by default popup looks a bit different on iPhone/iPod and iPad, on iPhone it is fullscreen.</p>
            <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse faucibus mauris leo, eu bibendum
              neque congue non. Ut leo mauris, eleifend eu commodo a, egestas ac urna. Maecenas in lacus faucibus,
              viverra ipsum pulvinar, molestie arcu. Etiam lacinia venenatis dignissim. Suspendisse non nisl semper
              tellus malesuada suscipit eu et eros. Nulla eu enim quis quam elementum vulputate. Mauris ornare consequat
              nunc viverra pellentesque. Aenean semper eu massa sit amet aliquam. Integer et neque sed libero mollis
              elementum at vitae ligula. Vestibulum pharetra sed libero sed porttitor. Suspendisse a faucibus lectus.
            </p>
            <p>Duis ut mauris sollicitudin, venenatis nisi sed, luctus ligula. Phasellus blandit nisl ut lorem semper
              pharetra. Nullam tortor nibh, suscipit in consequat vel, feugiat sed quam. Nam risus libero, auctor vel
              tristique ac, malesuada ut ante. Sed molestie, est in eleifend sagittis, leo tortor ullamcorper erat, at
              vulputate eros sapien nec libero. Mauris dapibus laoreet nibh quis bibendum. Fusce dolor sem, suscipit in
              iaculis id, pharetra at urna. Pellentesque tempor congue massa quis faucibus. Vestibulum nunc eros,
              convallis blandit dui sit amet, gravida adipiscing libero.</p>
          </div>
        </div>
      </div>
    </div>

    <div class="popup demo-popup-push">
      <div class="view view-init">
        <div class="page page-with-navbar-large">
          <div class="navbar navbar-large navbar-transparent">
            <div class="navbar-bg"></div>
            <div class="navbar-inner">
              <div class="title">Push Popup</div>
              <div class="right"><a class="link popup-close">Close</a></div>
              <div class="title-large">
                <div class="title-large-text">Push Popup</div>
              </div>
            </div>
          </div>
          <div class="page-content">
            <div class="block">
              <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse faucibus mauris leo, eu bibendum
                neque congue non. Ut leo mauris, eleifend eu commodo a, egestas ac urna. Maecenas in lacus faucibus,
                viverra ipsum pulvinar, molestie arcu. Etiam lacinia venenatis dignissim. Suspendisse non nisl semper
                tellus malesuada suscipit eu et eros. Nulla eu enim quis quam elementum vulputate. Mauris ornare
                consequat nunc viverra pellentesque. Aenean semper eu massa sit amet aliquam. Integer et neque sed
                libero mollis elementum at vitae ligula. Vestibulum pharetra sed libero sed porttitor. Suspendisse a
                faucibus lectus.</p>
              <p>Duis ut mauris sollicitudin, venenatis nisi sed, luctus ligula. Phasellus blandit nisl ut lorem semper
                pharetra. Nullam tortor nibh, suscipit in consequat vel, feugiat sed quam. Nam risus libero, auctor vel
                tristique ac, malesuada ut ante. Sed molestie, est in eleifend sagittis, leo tortor ullamcorper erat, at
                vulputate eros sapien nec libero. Mauris dapibus laoreet nibh quis bibendum. Fusce dolor sem, suscipit
                in iaculis id, pharetra at urna. Pellentesque tempor congue massa quis faucibus. Vestibulum nunc eros,
                convallis blandit dui sit amet, gravida adipiscing libero.</p>
              <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse faucibus mauris leo, eu bibendum
                neque congue non. Ut leo mauris, eleifend eu commodo a, egestas ac urna. Maecenas in lacus faucibus,
                viverra ipsum pulvinar, molestie arcu. Etiam lacinia venenatis dignissim. Suspendisse non nisl semper
                tellus malesuada suscipit eu et eros. Nulla eu enim quis quam elementum vulputate. Mauris ornare
                consequat nunc viverra pellentesque. Aenean semper eu massa sit amet aliquam. Integer et neque sed
                libero mollis elementum at vitae ligula. Vestibulum pharetra sed libero sed porttitor. Suspendisse a
                faucibus lectus.</p>
            </div>
          </div>
        </div>
      </div>
    </div>

    <div class="popup demo-popup-swipe">
      <div class="page">
        <div class="navbar">
          <div class="navbar-bg"></div>
          <div class="navbar-inner">
            <div class="title">Swipe To Close</div>
            <div class="right"><a class="link popup-close">Close</a></div>
          </div>
        </div>
        <div class="page-content">
          <div style="height: 100%" class="display-flex justify-content-center align-items-center">
            <p>Swipe me up or down</p>
          </div>
        </div>
      </div>
    </div>
    <div class="popup demo-popup-swipe-handler">
      <div class="page">
        <div class="swipe-handler"></div>
        <div class="page-content">
          <div class="block-title block-title-large">Hello!</div>
          <div class="block block-strong-ios block-outline-ios">
            <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse faucibus mauris leo, eu bibendum
              neque congue non. Ut leo mauris, eleifend eu commodo a, egestas ac urna. Maecenas in lacus faucibus,
              viverra ipsum pulvinar, molestie arcu. Etiam lacinia venenatis dignissim. Suspendisse non nisl semper
              tellus malesuada suscipit eu et eros. Nulla eu enim quis quam elementum vulputate. Mauris ornare consequat
              nunc viverra pellentesque. Aenean semper eu massa sit amet aliquam. Integer et neque sed libero mollis
              elementum at vitae ligula. Vestibulum pharetra sed libero sed porttitor. Suspendisse a faucibus lectus.
            </p>
            <p>Duis ut mauris sollicitudin, venenatis nisi sed, luctus ligula. Phasellus blandit nisl ut lorem semper
              pharetra. Nullam tortor nibh, suscipit in consequat vel, feugiat sed quam. Nam risus libero, auctor vel
              tristique ac, malesuada ut ante. Sed molestie, est in eleifend sagittis, leo tortor ullamcorper erat, at
              vulputate eros sapien nec libero. Mauris dapibus laoreet nibh quis bibendum. Fusce dolor sem, suscipit in
              iaculis id, pharetra at urna. Pellentesque tempor congue massa quis faucibus. Vestibulum nunc eros,
              convallis blandit dui sit amet, gravida adipiscing libero.</p>
            <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse faucibus mauris leo, eu bibendum
              neque congue non. Ut leo mauris, eleifend eu commodo a, egestas ac urna. Maecenas in lacus faucibus,
              viverra ipsum pulvinar, molestie arcu. Etiam lacinia venenatis dignissim. Suspendisse non nisl semper
              tellus malesuada suscipit eu et eros. Nulla eu enim quis quam elementum vulputate. Mauris ornare consequat
              nunc viverra pellentesque. Aenean semper eu massa sit amet aliquam. Integer et neque sed libero mollis
              elementum at vitae ligula. Vestibulum pharetra sed libero sed porttitor. Suspendisse a faucibus lectus.
            </p>
            <p>Duis ut mauris sollicitudin, venenatis nisi sed, luctus ligula. Phasellus blandit nisl ut lorem semper
              pharetra. Nullam tortor nibh, suscipit in consequat vel, feugiat sed quam. Nam risus libero, auctor vel
              tristique ac, malesuada ut ante. Sed molestie, est in eleifend sagittis, leo tortor ullamcorper erat, at
              vulputate eros sapien nec libero. Mauris dapibus laoreet nibh quis bibendum. Fusce dolor sem, suscipit in
              iaculis id, pharetra at urna. Pellentesque tempor congue massa quis faucibus. Vestibulum nunc eros,
              convallis blandit dui sit amet, gravida adipiscing libero.</p>
          </div>
        </div>
      </div>
    </div>
  </div>
</template>
<script>
  export default (props, { $f7, $onMounted, $onBeforeUnmount }) => {
    let popup;
    let popupSwipe;
    let popupSwipeHandler;
    let popupPush;

    const createPopup = () => {
      // Create popup
      if (!popup) {
        popup = $f7.popup.create({
          content: /*html*/`
            <div class="popup">
              <div class="page">
                <div class="navbar">
                  <div class="navbar-bg"></div>
                  <div class="navbar-inner">
                    <div class="title">Dynamic Popup</div>
                    <div class="right"><a  class="link popup-close">Close</a></div>
                  </div>
                </div>
                <div class="page-content">
                  <div class="block">
                    <p>This popup was created dynamically</p>
                    <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Suspendisse faucibus mauris leo, eu bibendum neque congue non. Ut leo mauris, eleifend eu commodo a, egestas ac urna. Maecenas in lacus faucibus, viverra ipsum pulvinar, molestie arcu. Etiam lacinia venenatis dignissim. Suspendisse non nisl semper tellus malesuada suscipit eu et eros. Nulla eu enim quis quam elementum vulputate. Mauris ornare consequat nunc viverra pellentesque. Aenean semper eu massa sit amet aliquam. Integer et neque sed libero mollis elementum at vitae ligula. Vestibulum pharetra sed libero sed porttitor. Suspendisse a faucibus lectus.</p>
                  </div>
                </div>
              </div>
            </div>
          `
        });
      }
      // Open it
      popup.open();
    }

    $onMounted(() => {
      popupSwipe = $f7.popup.create({
        el: '.demo-popup-swipe',
        swipeToClose: true,
      });
      popupSwipeHandler = $f7.popup.create({
        el: '.demo-popup-swipe-handler',
        swipeToClose: 'to-bottom',
        swipeHandler: '.swipe-handler'
      });
      popupPush = $f7.popup.create({
        el: '.demo-popup-push',
        swipeToClose: true,
        push: true,
      });
    })

    $onBeforeUnmount(() => {
      // Destroy popup when page removed
      if (popup) popup.destroy();
      if (popupSwipe) popupSwipe.destroy();
      if (popupSwipeHandler) popupSwipeHandler.destroy();
      if (popupPush) popupPush.destroy();
    })

    return $render;
  }
</script>
Improve this Doc
On this page