# Popover

Add small overlays of content, like those on the iPad, to any element for housing secondary information.

# Example

TIP

Popovers whose both title and content are zero-length are never displayed.

Click the button below to toggle popover:

Title

Hello world!

<template>
  <div class="uiv">
    <btn id="btn" type="primary">Popover</btn>
    <popover title="Title" target="#btn">
      <template slot="popover">
        <h1>Hello world!</h1>
      </template>
    </popover>
  </div>
</template>

# Trigger target

Order to decide the popover trigger:

  1. Use target if exist.
  2. Use element in default slot with data-role="trigger" attribute if exist.
  3. Use the first element present in default slot.

A target can be:

  • Selector that can be recognized by querySelect.
  • Reference to Element.
  • Reference to Component.

# Directive

You can also simply use popovers via v-popover directive:

<template>
  <div class="uiv">
    <btn
      v-popover="{ title: 'Title', content: 'Popover content' }"
      type="primary"
      >Popover</btn
    >
  </div>
</template>

# With empty title

If you don't want the title of popover, just leave the title prop unset or blank.

<template>
  <div class="uiv">
    <btn v-popover="{ content: 'Popover without a title' }" type="primary"
      >Popover</btn
    >
  </div>
</template>

# Placements

Supported placements:

  • top (Default)
  • right
  • bottom
  • left
<template>
  <div class="uiv">
    <btn
      v-popover.left="{ title: 'Title', content: 'Popover on left' }"
      type="primary"
      >Left</btn
    >
    <btn
      v-popover.top="{ title: 'Title', content: 'Popover on top' }"
      type="primary"
      >Top</btn
    >
    <btn
      v-popover.bottom="{ title: 'Title', content: 'Popover on bottom' }"
      type="primary"
      >Bottom</btn
    >
    <btn
      v-popover.right="{ title: 'Title', content: 'Popover on right' }"
      type="primary"
      >Right</btn
    >
  </div>
</template>

# Auto placement

Popover will try to find the best placement for displaying while auto-placement is set to true (by default) base on the default placement setting. Useful while there does not have enough space to show the entire popover content.

auto-placement try order: right -> bottom -> left -> top, and use the set one if none of these matched.

# Viewport

Keeps the popover within the bounds of this element.

<template>
  <div id="popover-viewport" class="uiv">
    <btn
      v-popover="{
        title: 'Title',
        content: 'Popover auto',
        viewport: '#popover-viewport',
      }"
      type="primary"
      >Auto</btn
    >
    <btn
      v-popover.left="{
        title: 'Title',
        content: 'Popover on left',
        viewport: '#popover-viewport',
      }"
      type="primary"
      >Left</btn
    >
    <btn
      v-popover.top="{
        title: 'Title',
        content: 'Popover on top',
        viewport: '#popover-viewport',
      }"
      type="primary"
      >Top</btn
    >
    <btn
      v-popover.bottom="{
        title: 'Title',
        content: 'Popover on bottom',
        viewport: '#popover-viewport',
      }"
      type="primary"
      >Bottom</btn
    >
    <btn
      v-popover.right="{
        title: 'Title',
        content: 'Popover on right',
        viewport: '#popover-viewport',
      }"
      type="primary"
      >Right</btn
    >
    <btn
      v-popover="{
        title: 'Title',
        content: 'Popover auto',
        viewport: '#popover-viewport',
      }"
      type="primary"
      >Auto</btn
    >
  </div>
</template>
<style scoped>
#popover-viewport {
  display: inline-block;
  padding: 20px;
  background-color: #eee;
}
</style>

# Triggers

Supported triggers:

  • hover show on mouseenter, hide on mouseleave.
  • focus show on focus, hide on blur.
  • hover-focus combination of hover and focus trigger.
  • click toggle on trigger click.
  • outside-click (Default) same as click, but not close on popover click and close on outside click.
<template>
  <div class="uiv">
    <btn
      v-popover="{ title: 'Title', content: 'Popover content' }"
      type="primary"
      >Outside-Click (Default)</btn
    >
    <btn
      v-popover.hover="{ title: 'Title', content: 'Popover content' }"
      type="primary"
      >Hover</btn
    >
    <btn
      v-popover.focus="{ title: 'Title', content: 'Popover content' }"
      type="primary"
      >Focus</btn
    >
    <btn
      v-popover.hover-focus="{ title: 'Title', content: 'Popover content' }"
      type="primary"
      >Hover-Focus</btn
    >
    <btn
      v-popover.click="{ title: 'Title', content: 'Popover content' }"
      type="primary"
      >Click</btn
    >
  </div>
</template>

# Manual trigger

Set trigger prop to manual to disable all the event listeners, and controls popover show / hide only by v-model change.

Title

Popover content


<template>
  <section class="uiv">
    <popover v-model="show" title="Title" trigger="manual">
      <btn>You Can't Trigger Popover Here...</btn>
      <template slot="popover">
        <p>Popover content</p>
      </template>
    </popover>
    <hr />
    <btn type="primary" @click="show = !show">Toggle Popover</btn>
  </section>
</template>
<script>
export default {
  data() {
    return {
      show: false,
    }
  },
}
</script>

# API Reference

# Popover (opens new window)

# Props

Name Type Default Required Description
v-model Boolean Show / hide the popover.
target Popover trigger, can be a select or reference to Element / Component.
tag String span The HTML tag that render the component.
title String The popover title.
content String The popover content text. Use popover slot instead if you need full control.
enable Boolean true Enable the popover.
enterable Boolean true Whether mouse can enter the popover.
placement String top The popover placement, support top / bottom / left / right.
auto-placement Boolean true Try to auto adjust the placement if the set one does not have enough space to show.
trigger String outside-click The popover trigger event, support hover / focus / hover-focus / click / outside-click / manual
append-to String body Element selector that the popover append to.
position-by String (1.2.0+) Element selector that the popover position by, see #410 (opens new window).
transition Number 150 The popover show / hide transition time in ms.
show-delay Number 0 Delay showing the Popover (ms).
hide-delay Number 0 Delay hidding the Popover (ms).
viewport String or Function Keeps the popover within the bounds of this element. Example: viewport: '#viewport'. If a function is given, it is called with the triggering element DOM node as its only argument.
custom-class String Apply a custom css class to the popover.

# Slots

Name Description
popover Replace as the popover body.
default Replace as the rest of the component (e.g. trigger stuffs).

# Events

Name Params Description
show Fire after popover show.
hide Fire after popover hide.

# Directive (opens new window)

The binding value will be the title and text content of corresponding popover.

# Simplest Usage

v-popover="{title:'Title', content:'Popover content'}"

# Placements Examples

v-popover.left="{title:'Title', content:'Popover content'}"
v-popover.right="{title:'Title', content:'Popover content'}"

# Triggers Examples

v-popover.hover="{title:'Title', content:'Popover content'}"
v-popover.click="{title:'Title', content:'Popover content'}"

# Unenterable

v-popover.unenterable="{title:'Title', content:'Popover content'}"

# Custom append-to

v-popover:arg="{title:'Title', content:'Popover content'}"

arg is the ID (without prefix #) of the element to append to, leave it empty to use default value body.

# Combination

v-popover.left.hover="{title:'Title', content:'Popover content'}"
v-popover:some-id.right.click="{title:'Title', content:'Popover content'}"