Popup

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

Popup layout is pretty simple:

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

Popup Size

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>

Popup App Methods

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

Popup Parameters

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

Parameter	Type	Default	Description
el	HTMLElement		Popup element. Can be useful if you already have Popup element in your HTML and want to create new instance using this element
content	string		Full Popup HTML layout string. Can be useful if you want to create Popup element dynamically
backdrop	boolean	true	Enables Popup backdrop (dark semi transparent layer behind)
backdropEl	HTMLElement string		HTML element or string CSS selector of custom backdrop element
closeByBackdropClick	boolean	true	When enabled, popup will be closed on backdrop click
closeOnEscape	boolean	false	When enabled, popup will be closed on ESC keyboard key press
animate	boolean	true	Whether the Popup should be opened/closed with animation or not. Can be overwritten in `.open()` and `.close()` methods
swipeToClose	boolean string	false	Whether 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.
swipeHandler	HTMLElement 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)
push	boolean	false	When 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.
on	object		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>

Popup Methods & Properties

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.app	Link to global app instance
popup.el	Popup HTML element
popup.$el	Dom7 instance with popup HTML element
popup.backdropEl	Backdrop HTML element
popup.$backdropEl	Dom7 instance with backdrop HTML element
popup.params	Popup parameters
popup.opened	Boolean 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

Control Popup With Links

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 (prefered to link)
To close popup we need to add “popup-close“ class to any HTML element (prefered 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 Events

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

DOM Events

Event	Target	Description
popup:open	Popup Element<div class=”popup”>	Event will be triggered when Popup starts its opening animation
popup:opened	Popup Element<div class=”popup”>	Event will be triggered after Popup completes its opening animation
popup:close	Popup Element<div class=”popup”>	Event will be triggered when Popup starts its closing animation
popup:closed	Popup Element<div class=”popup”>	Event will be triggered after Popup completes its closing animation
popup:swipestart	Popup Element<div class=”popup”>	Event will be triggered in the beginning of swipe-to-close interaction (when user just started to drag popup)
popup:swipemove	Popup Element<div class=”popup”>	Event will be triggered on swipe-to-close move interaction
popup:swipeend	Popup Element<div class=”popup”>	Event will be triggered on swipe-to-close release
popup:swipeclose	Popup Element<div class=”popup”>	Event will be triggered when popup closed with swipe

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.

Event	Arguments	Target	Description
open	popup	popup	Event will be triggered when Popup starts its opening animation. As an argument event handler receives popup instance
popupOpen	popup	app
opened	popup	popup	Event will be triggered after Popup completes its opening animation. As an argument event handler receives popup instance
popupOpened	popup	app
close	popup	popup	Event will be triggered when Popup starts its closing animation. As an argument event handler receives popup instance
popupClose	popup	app
closed	popup	popup	Event will be triggered after Popup completes its closing animation. As an argument event handler receives popup instance
popupClosed	popup	app
beforeDestroy	popup	popup	Event will be triggered right before Popup instance will be destroyed. As an argument event handler receives popup instance
popupBeforeDestroy	popup	app
swipeStart	popup	popup	Event will be triggered in the beginning of swipe-to-close interaction (when user just started to drag popup)
popupSwipeStart	popup	app
swipeMove	popup	popup	Event will be triggered on swipe-to-close move interaction
popupSwipeMove	popup	app	Event will be triggered on swipe-to-close move interaction
swipeEnd	popup	popup	Event will be triggered on swipe-to-close release
popupSwipeEnd	popup	app	Event will be triggered on swipe-to-close release
swipeClose	popup	popup	Event will be triggered when popup closed with swipe
popupSwipeClose	popup	app	Event will be triggered when popup closed with swipe

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-transition-duration: 400ms;
  --f7-popup-push-border-radius: 10px;
  --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-box-shadow: none;
}
.md {
  --f7-popup-tablet-border-radius: 4px;
  --f7-popup-box-shadow: 0px 20px 44px rgba(0, 0, 0, 0.5);
}
.aurora {
  --f7-popup-tablet-border-radius: 4px;
  --f7-popup-box-shadow: 0px 20px 44px rgba(0, 0, 0, 0.5);
}

Examples

<body>
  ...
    <div class="page-content">
      <div class="block">
        <!-- Open About Popup -->
        <p><a class="button popup-open" href="#" data-popup=".popup-about">Open About Popup</a></p>
        <!-- Open Services Popup -->
        <p><a class="button popup-open" href="#" data-popup=".popup-services">Open Services Popup</a></p>
        <!-- Create Dynamic Popup -->
        <p><a class="button dynamic-popup" href="#">Create dynamic popup</a></p>
        <!-- Popup with swipe-to-close -->
        <p><a class="button popup-open" href="#" data-popup=".popup-swipe-to-close">Popup with swipe to close</a></p>
        <!-- Popup with swipe-to-close handler -->
        <p><a class="button popup-open" href="#" data-popup=".popup-swipe-to-close-handler">Popup with swipe to close handler</a></p>
        <!-- Popup push -->
        <p><a class="button popup-open" href="#" data-popup=".popup-push">Popup Push</a></p>
      </div>
    </div>
  ...
  <div class="popup popup-about">
    <div class="block">
      <p>About</p>
      <!-- Close Popup -->
      <p><a class="link popup-close" href="#">Close popup</a></p>
      <p>Lorem ipsum dolor sit amet...</p>
    </div>
  </div>
  <div class="popup popup-services">
    <div class="block">
      <p>Services</p>
      <!-- Close Popup -->
      <p><a class="link popup-close" href="#">Close popup</a></p>
      <p>Lorem ipsum dolor sit amet...</p>
    </div>
  </div>
  <div class="popup popup-swipe-to-close">
    <div class="block text-align-center">
      <p>Swipe me up or down to close</p>
    </div>
  </div>
  <div class="popup popup-swipe-to-close-handler">
    <div class="block">
      <p class="my-swipe-to-close-handler"><b>Swipe works only on this paragraph</b></p>
      <p>Lorem ipsum dolor sit amet...</p>
    </div>
  </div>
  <div class="popup popup-push">
    <div class="block">
      <p>Popup Push </p>
      <p><a class="link popup-close" href="#">Close popup</a></p>
      <p>Lorem ipsum dolor sit amet...</p>
    </div>
  </div>
</body>

var app = new Framework7();
var $$ = Dom7;
// DOM events for About popup
$$('.popup-about').on('popup:open', function (e) {
  console.log('About popup open');
});
$$('.popup-about').on('popup:opened', function (e) {
  console.log('About popup opened');
});
// Create dynamic Popup
var dynamicPopup = app.popup.create({
  content: '<div class="popup">'+
              '<div class="block">'+
                '<p>Popup created dynamically.</p>'+
                '<p><a href="#" class="link popup-close">Close me</a></p>'+
              '</div>'+
            '</div>',
  // Events
  on: {
    open: function (popup) {
      console.log('Popup open');
    },
    opened: function (popup) {
      console.log('Popup opened');
    },
  }
});
// Events also can be assigned on instance later
dynamicPopup.on('close', function (popup) {
  console.log('Popup close');
});
dynamicPopup.on('closed', function (popup) {
  console.log('Popup closed');
});
// Open dynamic popup
$$('.dynamic-popup').on('click', function () {
  dynamicPopup.open();
});
// Create Popup with swipe to close
var swipeToClosePopup = app.popup.create({
  el: '.popup-swipe-to-close',
  swipeToClose: true,
});
// Create Popup with swipe to close handler
var swipeToClosePopup = app.popup.create({
  el: '.popup-swipe-to-close-handler',
  swipeToClose: true,
  swipeHandler: '.my-swipe-to-close-handler',
});

← Popover

Preloader →