Popover

    Popover compontent is used to manage the presentation of content in a popover. You use popovers to present information temporarily. The popover remains visible until the user taps outside of the popover window or you explicitly dismiss it.

    Note that is not recommended to use Popover on small screens (iPhone). On small screens you should use Action Sheet instead.

    Popover Layout

    First of all let's look on Popover layout, it is pretty simple:

    <body>
        ...
        <div class="popover">
            <!-- Popover's angle arrow -->
            <div class="popover-angle"></div>
    
            <!-- Popover content -->
            <div class="popover-inner">
                <!-- Any HTML content here -->
            </div>
        </div>
    </body>

    Popover is highly customizable element and you can put anything inside, event another view with navigation.

    Popover App Methods

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

    app.popover.create(parameters)- create Popover instance

    • parameters - object. Object with popover parameters

    Method returns created Popover's instance

    app.popover.destroy(el)- destroy Popover instance

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

    app.popover.get(el)- get Popover instance by HTML element

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

    Method returns Popover's instance

    app.popover.open(el, targetEl, animate)- opens Popover

    • el - HTMLElement or string (with CSS Selector). Popover element to open.
    • targetEl - HTMLElement or string (with CSS Selector). Target element to set popover position around this element
    • animate - boolean. Open Popover with animation.

    Method returns Popover's instance

    app.popover.close(el, animate)- closes Popover

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

    Method returns Popover's instance

    Popover Parameters

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

    Parameter Type Default Description
    el HTMLElement Popover element. Can be useful if you already have Popover element in your HTML and want to create new instance using this element
    content string Full Popover HTML layout string. Can be useful if you want to create Popover element dynamically
    backdrop boolean true Enables Popover backdrop (dark semi transparent layer behind)
    closeByBackdropClick boolean true When enabled, popover will be closed on backdrop click
    closeByOutsideClick boolean true When enabled, popover will be closed on when click outside of it
    animate boolean true Whether the Popover should be opened/closed with animation or not. Can be overwritten in .open() and .close() methods
    targetEl HTMLElement
    string
    HTML element or string CSS selector of target element
    targetX number Virtual target element horizontal offset from left side of the screen. Required without using real target element (targetEl)
    targetY number Virtual target element vertical offset from top of the screen. Required without using real target element (targetEl)
    targetWidth number 0 Virtual target element width (in px). Required without using real target element (targetEl)
    targetHeight number 0 Virtual target element height (in px). Required without using real target element (targetEl)
    on object Object with events handlers. For example:
    var popover = app.popover.create({
      content: '<div class="popover">...</div>',
      on: {
        opened: function () {
          console.log('Popover opened')
        }
      }
    })

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

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

    Popover Methods & Properties

    So to create Popover we have to call:

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

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

    Properties
    popover.app Link to global app instance
    popover.el Popover HTML element
    popover.$el Dom7 instance with popover HTML element
    popover.backdropEl Backdrop HTML element
    popover.$backdropEl Dom7 instance with backdrop HTML element
    popover.targetEl Popover target HTML element
    popover.$targetEl Dom7 instance with popover target HTML element
    popover.params Popover parameters
    popover.opened Boolean prop indicating whether popover is opened or not
    Methods
    popover.open(targetEl, animate) Open popover around target element. Where
    • targetEl - HTMLElement or string - target element to set popover position around this element
    • animate - boolean (by default true) - defines whether it should be opened with animation
    popover.open(animate) Open popover around target element passed on popover creation. Where
    • animate - boolean (by default true) - defines whether it should be opened with animation
    popover.close(animate) Close popover. Where
    • animate - boolean (by default true) - defines whether it should be closed with animation
    popover.destroy() Destroy popover
    popover.on(event, handler) Add event handler
    popover.once(event, handler) Add event handler that will be removed after it was fired
    popover.off(event, handler) Remove event handler
    popover.off(event) Remove all handlers for specified event
    popover.emit(event, ...args) Fire event on instance

    Control Popover With Links

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

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

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

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

    According to above note:

    <!-- In data-popover attribute we specify CSS selector of popover we need to open -->
    <p><a href="#" data-popover=".my-popover" class="popover-open">Open Popover</a></p>
    
    <!-- And somewhere in DOM -->
    <div class="popover my-popover">
      <div class="popover-inner">
        <!-- Link to close popover -->
        <a class="link popover-close">Close Popover</a>
      </div>
    </div>
    
    

    Popover Events

    Popover will fire the following DOM events on popover element and events on app and popover instance:

    DOM Events

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

    App and Popover Instance Events

    Popover instance emits events on both self instance and app instance. App instance events has same names prefixed with popover.

    Event Arguments Target Description
    open popover popover Event will be triggered when Popover starts its opening animation. As an argument event handler receives popover instance
    popoverOpen popover app
    opened popover popover Event will be triggered after Popover completes its opening animation. As an argument event handler receives popover instance
    popoverOpened popover app
    close popover popover Event will be triggered when Popover starts its closing animation. As an argument event handler receives popover instance
    popoverClose popover app
    closed popover popover Event will be triggered after Popover completes its closing animation. As an argument event handler receives popover instance
    popoverClosed popover app
    beforeDestroy popover popover Event will be triggered right before Popover instance will be destroyed. As an argument event handler receives popover instance
    popoverBeforeDestroy popover app

    Examples

    <body>
      ...
        <div class="page">
          <div class="navbar">
            <div class="navbar-inner">
              <div class="left">
                <!-- Additional "popover-open" class to open popover on link click -->
                <!-- In data-popover attribute we specify CSS selector of popover we need to open -->
                <a class="link popover-open" href="#" data-popover=".popover-about">About</a>
              </div>
              <div class="title">Popover</div>
              <div class="right">
                <a class="link popover-open" href="#" data-popover=".popover-links">Links</a>
              </div>
            </div>
          </div>
          <div class="page-content">
            <div class="block">
              <p>
                <!-- In data-popover attribute we specify CSS selector of popover we need to open -->
                <a class="link popover-open" href="#" data-popover=".popover-about">Open About Popover</a>
              </p>
              <p>
                <!-- In data-popover attribute we specify CSS selector of popover we need to open -->
                <a class="link popover-open" href="#" data-popover=".popover-links">Open Links Popover</a>
              </p>
              <p>
                <a class="link dynamic-popover" href="#">Create Dynamic Popover</a>
              </p>
            </div>
          </div>
        </div>
      ...
    
      <!-- Popovers -->
      <div class="popover popover-about">
        <div class="popover-inner">
          <div class="block">
            <p>About</p>
            <p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Quisque ac diam ac quam euismod porta vel a nunc. Quisque sodales scelerisque est, at porta justo cursus ac.</p>
          </div>
        </div>
      </div>
      <div class="popover popover-links">
        <div class="popover-inner">
          <div class="list">
            <ul>
              <li><a class="list-button item-link" href="#">Link 1</a></li>
              <li><a class="list-button item-link" href="#">Link 2</a></li>
              <li><a class="list-button item-link" href="#">Link 3</a></li>
              <li><a class="list-button item-link" href="#">Link 4</a></li>
            </ul>
          </div>
        </div>
      </div>
      ...
    </body>
    var app = new Framework7();
    
    var $$ = Dom7;
    
    // DOM events for About popover
    $$('.popover-about').on('popover:open', function (e, popover) {
      console.log('About popover open');
    });
    $$('.popover-about').on('popover:opened', function (e, popover) {
      console.log('About popover opened');
    });
    
    // Create dynamic Popover
    var dynamicPopover = app.popover.create({
      targetEl: 'a.dynamic-popover',
      content: '<div class="popover">'+
                  '<div class="popover-inner">'+
                    '<div class="block">'+
                      '<p>Popover created dynamically.</p>'+
                      '<p><a href="#" class="link popover-close">Close me</a></p>'+
                    '</div>'+
                  '</div>'+
                '</div>',
      // Events
      on: {
        open: function (popover) {
          console.log('Popover open');
        },
        opened: function (popover) {
          console.log('Popover opened');
        },
      }
    });
    // Events also can be assigned on instance later
    dynamicPopover.on('close', function (popover) {
      console.log('Popover close');
    });
    dynamicPopover.on('closed', function (popover) {
      console.log('Popover closed');
    });
    
    // Open dynamic popover
    $$('.dynamic-popover').on('click', function () {
      dynamicPopover.open();
    });