uiv

Appearance

On this page

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:

vue
<template>
  <Btn id="btn" type="primary">Popover</Btn>
  <Popover title="Title" target="#btn">
    <template #popover>
      <h1>Hello world!</h1>
    </template>
  </Popover>
</template>

<script setup>
import { Popover, Btn } from 'uiv';
</script>

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:

vue
<template>
  <Btn
    v-popover="{ title: 'Title', content: 'Popover content' }"
    type="primary"
  >
    Popover
  </Btn>
</template>

<script setup>
import { popover as vPopover, Btn } from 'uiv';
</script>

With empty title ​

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

vue
<template>
  <Btn v-popover="{ content: 'Popover without a title' }" type="primary">
    Popover
  </Btn>
</template>

<script setup>
import { popover as vPopover, Btn } from 'uiv';
</script>

Placements ​

Supported placements:

  • top (Default)
  • right
  • bottom
  • left
vue
<template>
  <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>
</template>

<script setup>
import { popover as vPopover, Btn } from 'uiv';
</script>

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.

vue
<template>
  <div id="popover-viewport">
    <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>

<script setup>
import { popover as vPopover, Btn } from 'uiv';
</script>

<style scoped>
#popover-viewport {
  display: inline-block;
  padding: 50px;
  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.
vue
<template>
  <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>
</template>

<script setup>
import { popover as vPopover, Btn } from 'uiv';
</script>

Manual trigger ​

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

vue
<template>
  <Popover v-model="show" title="Title" trigger="manual">
    <Btn>You Can't Trigger Popover Here...</Btn>
    <template #popover>
      <p>Popover content</p>
    </template>
  </Popover>
  <hr />
  <Btn type="primary" @click="show = !show">Toggle Popover</Btn>
</template>

<script setup>
import { Popover, Btn } from 'uiv';
import { ref } from 'vue';

const show = ref(false);
</script>

API Reference ​

Popover ​

Props ​

NameTypeDefaultRequiredDescription
v-modelBooleanShow / hide the popover.
targetPopover trigger, can be a select or reference to Element / Component.
tagStringspanThe HTML tag that render the component.
titleStringThe popover title.
contentStringThe popover content text. Use popover slot instead if you need full control.
enableBooleantrueEnable the popover.
enterableBooleantrueWhether mouse can enter the popover.
placementStringtopThe popover placement, support top / bottom / left / right.
auto-placementBooleantrueTry to auto adjust the placement if the set one does not have enough space to show.
triggerStringoutside-clickThe popover trigger event, support hover / focus / hover-focus / click / outside-click / manual
append-toStringbodyElement selector that the popover append to.
position-byStringElement selector that the popover position by, see #410.
transitionNumber150The popover show / hide transition time in ms.
show-delayNumber0Delay showing the Popover (ms).
hide-delayNumber0Delay hidding the Popover (ms).
viewportString or FunctionKeeps 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-classStringApply a custom css class to the popover.

Slots ​

NameDescription
popoverReplace as the popover body.
defaultReplace as the rest of the component (e.g. trigger stuffs).

Events ​

NameParamsDescription
showFire after popover show.
hideFire after popover hide.

Directive ​

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'}"

Released under the MIT License.

Copyright © 2017-present Kairui Guo