Popover

Popover component 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.

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

<body>
    ...
    <div class="popover">
        <!-- Popover's arrow -->
        <div class="popover-arrow"></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.

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

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
arrow	boolean	true	Enables Popover arrow/corner
content	string		Full Popover HTML layout string. Can be useful if you want to create Popover element dynamically
verticalPosition	string	auto	Force popover vertical position, can be `auto`, `top` or `bottom`
backdrop	boolean	true	Enables Popover backdrop (dark semi transparent layer behind)
backdropUnique	boolean	false	If enabled it creates unique backdrop element exclusively for this modal
backdropEl	HTMLElement string		HTML element or string CSS selector of custom backdrop element
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
closeOnEscape	boolean	false	When enabled, popover will be closed on ESC keyboard key press
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`)
containerEl	HTMLElement string		Element to mount modal to (default to app root element)
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,
  }
});

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

<!-- Pass parameters as kebab-case data attributes -->
<div class="popover" data-close-on-escape="true" data-backdrop="false">
  ...
</div>

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

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 (preferred to link)
To close popover we need to add "popover-close" class to any HTML element (preferred 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 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

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

CSS Variables

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

:root {
  --f7-popover-width: 260px;
}
.ios {
  --f7-popover-border-radius: 13px;
  --f7-popover-actions-icon-size: 28px;
  --f7-popover-transition-timing-function: initial;
  --f7-popover-bg-color: rgba(255, 255, 255, 0.95);
  --f7-popover-actions-label-text-color: rgba(0, 0, 0, 0.45);
}
.ios .dark,
.ios.dark {
  --f7-popover-bg-color: rgba(30, 30, 30, 0.95);
  --f7-popover-actions-label-text-color: rgba(255, 255, 255, 0.55);
}
.md {
  --f7-popover-transition-timing-function: cubic-bezier(0, 0.8, 0.34, 1);
  --f7-popover-border-radius: 28px;
  --f7-popover-actions-icon-size: 24px;
}
.md,
.md .dark,
.md [class*='color-'] {
  --f7-popover-bg-color: var(--f7-md-surface-3);
  --f7-popover-actions-label-text-color: var(--f7-md-on-surface-variant);
}

Examples

popover.html

<div class="page">
  <div class="navbar">
    <div class="navbar-bg"></div>
    <div class="navbar-inner sliding">
      <div class="left">
        <a class="link back">
          <i class="icon icon-back"></i>
          <span class="if-not-md">返回</span>
        </a>
      </div>
      <div class="title">弹出提示</div>
      <div class="right">
        <a class="link popover-open" data-popover=".popover-menu">提示</a>
      </div>
    </div>
  </div>
  <div class="toolbar toolbar-bottom">
    <div class="toolbar-inner">
      <a href="" class="link popover-open" data-popover=".popover-menu">弹出链接</a>
      <a href="" class="link popover-open" data-popover=".popover-menu">打开弹出提示</a>
    </div>
  </div>
  <div class="page-content">
    <div class="block">
      <p><a data-popover=".popover-menu" class="button button-fill popover-open">在这里打开提示操作</a></p>
      <p>从前有一个小村庄，村庄里住着一群快乐的农民。他们过着简单而宁静的生活，每天努力工作，互相帮助。然而，村庄的水井却出了问题，水源渐渐枯竭，农民们陷入了困境。

        为了解决这个问题，村庄的领导决定召开一次村民大会。在会上，一位年轻的农民提出了一个创新的想法：利用雨水收集系统来解决水井干涸的问题。他详细解释了如何设计和建造这个系统，并列出了所需的材料和步骤。</p>
      <p>农民们被这个想法所激发，他们积极参与到项目中。大家分工合作，有的负责收集材料，有的负责挖掘水渠，有的负责安装雨水收集设备。大家一起努力，克服了各种困难和挑战。.</p>
      <p>最终，雨水收集系统建成了。当第一场雨来临时，水渠迅速充满了清澈的雨水。农民们欢呼雀跃，他们终于解决了水井干涸的问题。村庄重新恢复了生机，农作物茁壮成长。

        这个小故事告诉我们，团结合作和创新思维可以克服各种困难。只要我们齐心协力，勇于尝试新的解决方案，就能够找到问题的答案，并创造出美好的未来。</p>
    </div>
  </div>
  <div class="popover popover-menu">
    <div class="popover-angle"></div>
    <div class="popover-inner">
      <div class="list">
        <ul>
          <li><a href="/dialog/" class="list-button popover-close">对话框</a></li>
          <li><a href="/tabs/" class="list-button popover-close">tabs表单</a></li>
          <li><a href="/panel/" class="list-button popover-close">侧边panel</a></li>
          <li><a href="/list/" class="list-button popover-close">列表视图</a></li>
          <li><a href="/inputs/" class="list-button popover-close">表单输入框</a></li>
        </ul>
      </div>
    </div>
  </div>
</div>

Improve this Doc

On this page

Popover Layout
Popover App Methods
Popover Parameters
Popover Methods & Properties
Control Popover With Links
Popover Events

DOM Events
App and Popover Instance Events

CSS Variables
Examples

Popover

Popover Layout

Popover App Methods

Popover Parameters

Popover Methods & Properties

Control Popover With Links

Popover Events

DOM Events

App and Popover Instance Events

CSS Variables

Examples