Skip to content

termehui/vpopper

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

2 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Popper

PopperJs powered popup for vue 3

Installation

Note: this package require @popperjs/core and animejs npm package.

CDN

This package published as vPopper module in umd.

<link
  rel="stylesheet"
  href="https://unpkg.com/@termehui/vpopper/dist/style.css"
/>
<script src="https://unpkg.com/@termehui/vpopper"></script>

NPM

npm i @termehui/vpopper

Install popper container ,popup and tooltip component with default name (popper, popup and tooltip):

import { createApp } from "vue";
import App from "./App.vue";
import vPopper from "@termehui/vpopper";

createApp(App).use(vPopper).mount("#app");

Install popper container, popup and tooltip component with custom name:

import { createApp } from "vue";
import App from "./App.vue";
import { Popper, Popup, Tooltip } from "@termehui/vpopper";
createApp(App)
  .component("v-popper", Popper)
  .component("v-popup", Popup)
  .component("v-tooltip", Tooltip)
  .mount("#app");

Options

Popper has two level options:

  • global options (used by default for all popper)
  • popper options (passed as popper property and override global options)
Property Type Description Default
enterAnimation AnimeParams|PopperFullAnimation show animation (animejs animation option) slide in
leaveAnimation AnimeParams|PopperFullAnimation hide animation (animejs animation option) slide out

Change Global Options

You can change global options using setGlobalOptions helper.

import { setGlobalOptions } from "@termehui/vpopper";
setGlobalOptions({
  enterAnimation: {
    opacity: [0, 1],
    duration: 200,
  },
});

Popper Animation

popper use animejs for animating. you can use single anime js options or use a object contains four top, left, right and bottom animation for different popup placement.

// Single animation (use for all placements in popper)
const singleAnimation = {
  opacity: [0, 1],
  duration: 200,
};
// Select animation based on popper placement
const fullAnimation = {
  top: {
    translateY: [-20, 0],
    duration: 200,
  },
  left: {
    translateX: [-20, 0],
    duration: 200,
  },
  bottom: {
    translateY: [20, 0],
    duration: 200,
  },
  right: {
    translateX: [20, 0],
    duration: 200,
  },
};

Usage

Popper (Wrapper Component)

Popper is main container for popper plugin. It contains reference element, popup and configurations of popper. Popper contains two slot:

  • the default slot (reference content)
  • the popup slot (popup content)

Note: reference element can be a single element or a set of elements. if you need to use single element as reference you can change tag property and put content inside default slot.

Scoped Slots

Default slot contains following attributes:

  • open: function to show popup
  • close: function to hide popup
  • action: function to call popup action handler
  • loading: reactive object of loading state

Note: you can use default slot attributes with manual mode to show/hide popup with custom functionality.

Popper Component Properties

Property Type Description Default
tag string reference element tag. you can set tag name for single element reference (e.g. button) span
trigger "click" | "focus" | "hover" | "manualy" popup show/hide trigger mode hover
onAction (key: string, data?: unknown) => Promise<boolean> action handler function null
closable boolean close popup when click outside of popper true
options PopperOptions popper options {}
config PopperJsOptions popperJs options {}

Popper Component Events

Event Signature Description
initialized (instance: popperJs) => void triggered when popper component initialized and pass popperJs created instance as event arg
show () => void triggered after popup opened
hide (mode: "auto" | "click" | "action") => void triggered after popup closed
<!-- Single element -->
<popper tag="button" trigger="hover">
  Hover me
  <template #popup>
    <p>This paragraph shown on element hover</p>
  </template>
</popper>
<!-- Multiple Element -->
<popper tag="div" trigger="focus" :config="{ placement: 'right' }">
  <input type="text" value="first input" />
  <input type="text" value="second input" />
  <input type="text" value="third input" />
  <template #popup>
    <div>This div shown on right side when any of inputs got focus</div>
  </template>
</popper>

Popup (Popup UI Element)

Popup is a graphical popup component and can used inside Popper container as popup ui.

Scoped Slots

Default slot contains following attributes:

  • close: function to hide popup
  • action: function to call popup action handler
  • loading: reactive object of loading state

Caution if you want to using this functionality in your popup, use stop modifier on action button events.

Popup Properties

Property Type Description Default
closable boolean close popup when click on popup body true

Popup Events

Event Signature Description
show () => void trigger when popup show
hide ("blur" | "click" | "action") => void trigger when popup hide
<popper trigger="manualy" :closable="false">
  <template #default="{open, close}">
    <button class="is-error" @click.stop="close">Close</button>
    <button class="is-success" @click.stop="open">Open</button>
  </template>
  <template #popup>
    <popup :closable="false">
      <template #default="{ close }">
        This popup shown manualy. <span @click.stop="close">X</span>
      </template>
    </popup>
  </template>
</popper>

Tooltip (Tooltip UI Element)

Tooltip is a graphical popup component and can used inside Popper container as popup ui.

Scoped Slots

Default slot contains following attributes:

  • close: function to hide popup
  • action: function to call popup action handler
  • loading: reactive object of loading state

Caution if you want to using this functionality in your popup, use stop modifier on action button events.

Popup Properties

Property Type Description Default
closable boolean close popup when click on popup body true

Popup Events

Event Signature Description
show () => void trigger when popup show
hide ("blur" | "click" | "action") => void trigger when popup hide
<popper trigger="hover">
  <div>Hover me to view tooltip</div>
  <template #popup>
    <tooltip>This is a simple tooltip</tooltip>
  </template>
</popper>

Custom Popup

To create custom popup you need define a normal vue component with popper library composition api usePopup helper.

Note: for arrow element define a element with data-popper-arrow attribute inside your component.

Note: use scoped slot for passing usePopup functionality to template.

Cation: use stop modifier on events otherwise global functionality failed!

usePopup Return Values

Name Type Description
close () => void close popup
action (key: string, data?: unknown) => void helper method to call popup action handler
loading boolean loading state
onShow (cb: MinimalFunction) => void helper function to register a callback for show event
onHide (cb: CloseHandler) => void helper function to register a callback for hide event
<template>
  <div class="v-popup" :class="{ 'is-loading': loading }" @click.stop="close">
    <!-- Pass usePopup functionality as scoped slot -->
    <slot :action="action" :close="close" :loading="loading" />
    <!-- Define arrow -->
    <div class="arrow" data-popper-arrow></div>
  </div>
</template>

<script lang="ts">
import { defineComponent } from "vue";
import { usePopup } from "@termehui/vpopper";
export default defineComponent({
  emits: ["show", "hide"],
  setup(props, { emit }) {
    const { close, action, loading, onShow, onHide } = usePopup();
    onShow(() => emit("show"));
    onHide((mode: "blur" | "click" | "action") => emit("hide", mode));
    return { loading, action, close };
  },
});
</script>

Styling

for using default styles you can use one of static (CSS) or termeh (SCSS) predefined files.

Note: advanced feature (change default vars, padding classes and color classes) only available in termeh version of style.

// Static
@import "@termehui/vpopper/style.css";
@import "@termehui/vpopper/dist/style.css"; // old node version
// Termeh
@import "@termehui/vpopper/style.scss";
@import "@termehui/vpopper/dist/style.scss"; // old node version

Popup Styles

Popup by default can contains following parts:

  • arrow: arrow element.
  • separator: separator line.
  • attachment: section for putting content.

Note: this elements must placed directly as popup child.

<div class="v-popup">
  <div class="attachment">{{ topContent }}</div>
  <div class="separator"></div>
  <div class="gaper is-auto">
    <button class="is-simple">Cancel</button>
    <button class="is-primary">Approve</button>
  </div>
  <div class="attachment is-footer is-secondary">{{ footerContent }}</div>
  <div class="arrow" data-popper-arrow></div>
</div>

Popup Classes

You could style your custom component by v-popup class.

  • is-loading: add loading ui to popup.
  • is-{gap}-gaped: set popup gap (padding and spacing) to registered iterable gaps (Termeh only).
  • is-{color}: set popup color scheme to registered iterable colors (Termeh only).

Attachment Classes

  • is-header: attach attachment to top of popup.
  • is-footer: attach attachment to bottom of popup.
  • is-secondary: make section with darker background.

Tooltip Styles

Tooltip by default can contains following parts:

  • arrow: arrow element.

Note: this elements must placed directly as popup child.

<div class="v-tooltip">
  <p>{{ content }}</p>
  <div class="arrow" data-popper-arrow></div>
</div>

Tooltip Classes

You could style your custom component by v-tooltip class.

  • is-loading: add loading ui to tooltip.
  • is-{gap}-padded: set popup padding to registered iterable gaps (Termeh only).
  • is-{color}: set popup color scheme to registered iterable colors (Termeh only).

Customize Styling

You can override following pre-defined component variable to override default popup styling.

@include _var("popup", "border", none);
@include _var("tooltip", "primary-shadow", none);
Component Variable Description Default
popup border default popup border 1px solid _color("separator")
popup shadow default popup shadow a soft shadow
popup arrow-color default popup arrow color _color("shade")
popup gap default popup padding 1em
popup gaps list of non-iterable gaps to include in popup gaps ()
popup colors list of non-iterable colors to include in popup colors ()
popup {color}-border colored popup border 1px solid $color
popup {color}-shadow colored popup shadow same as default popup
popup {color}-arrow-color colored popup arrow color $color
tooltip background tooltip background color rgb(0, 0, 0, 0.9)
tooltip shadow default tooltip shadow a soft shadow
tooltip overlay tooltip overlay color rgba(0, 0, 0, 0.75)
tooltip gaps list of non-iterable gaps to include in tooltip gaps ()
tooltip colors list of non-iterable colors to include in tooltip colors ()
tooltip {color}-shadow colored tooltip shadow same as default tooltip