Vue Popper Utilites

vue-popper-utilities is a wrapper around popperjs@core for Vue.js for creating any custom popup, dropdown, multi level dropdown with nested child dropdowns, tooltip etc.

Key Features:

Vue 3 compatible!
Fully written in Typescript with full types support.
Global event bus. Only one event listener no matter how many popups are initiated in a single page. Permormance won't drop if there are many components are on a page.
Fully customizable. It is possible to make any kind of custom popup using the package.
Predefined components like Dropdown, DropdownChild, Tooltip for covering most of the use case.
Keyboard navigation between multiple children dropdowns.
transition and animation capability using vue default Transition component.

Please check the demo here

Getting started

<script setup>
import { Dropdown, DropdownItem, DropdownChild } from 'vue-popper-utilities';
import 'vue-popper-utilities/style.css';
</script>

<template>
    <Dropdown trigger="click" :offset="[0, 8]" placement="right-start">
        <template #reference="{ isOpen }">
            <button class="test-btn" :class="[isOpen ? 'active' : '']">
                Test button
            </button>
        </template>

        <template v-slot="{ isOpen, hide }">
            <DropdownItem v-for="x in 6" :key="x">
                {{ `Item ${x}` }}
            </DropdownItem>

            <DropdownChild trigger="hover">
                <template #reference>
                    <button>Item child 1</button>
                </template>

                <div class="dropdown-child-1-container">
                    <DropdownItem v-for="y in 2" :key="y">
                        {{ `Item child ${y}` }}
                    </DropdownItem>
                </div>
            </DropdownChild>

            <button @click="hide()">Hide manually</button>
        </template>
    </Dropdown>
</template>

Installation

npm i vue-popper-utilities

Usage

Global registration

import { createApp } from 'vue';
import App from './App.vue';

import {
    Popup,
    Dropdown,
    DropdownChild,
    DropdownItem,
    Tooltip,
} from 'vue-popper-utilities';
import 'vue-popper-utilities/style.css';

const app = createApp(App);
app.component('Popup', Popup)
    .component('Dropdown', Dropdown)
    .component('DropdownChild', DropdownChild)
    .component('DropdownItem', DropdownItem)
    .component('Tooltip', Tooltip)
    .mount('#app');

Use directly inside a component

<script setup>
import { Popup } from 'vue-popper-utilities';
import 'vue-popper-utilities/style.css';
</script>

Popup.vue

This is the base component of the popper. All other components are the extraction of this component.

Normal usage

<Popup>
    <template #reference>
        <button>Popup button</button>
    </template>

    <div>Popup content</div>
</Popup>

Opening popper dynamically with v-model

<Popup v-model="show" reference="#popup-reference">
    <div>Popup content</div>
</Popup>

Props

Name	Type	Default	Description
trigger	String	`click`	trigger of the popup. possible values are click, hover, focus.
placement	Placement	`bottom-start`	Placement of the popup element with respect to reference.
offset	Array [number, number] Popper offset	`[0, 4]`	Offset of the popper relative to the reference.
strategy	String Strategy	`absolute`	Positioning strategy. possible values are absolute or fixed.
options	Options	`undefined`	Can be used for having more fine control over, how the popup will aprear. Most of the times above props will work fine. This props has high priority over placement, offset and strategy props. setting this will override other values. Values are calculated by deep comparing i.e; if value exists on the options prop it will take from options prop. Otherwise if value exists on the other props, it will take other props. Otherwise it will take from default values.
on-first-update	Function	`undefined`	Callback function to run after the first update of the popper.js.
model-value	Boolean	`undefined`	Can be used to control popup dynamically from a variable. IMPORTANT: reference props must be required with this prop to work.
reference	Element or String or null	`null`	if popup is controlled by v-model, reference element is the target element where to glue in the popup. It's value can be any HTML element or any valid css selector. IMPORTANT: must be required with v-model.
is-dynamic-reference	Boolean	`false`	Sometimes the reference element can be conditionally added or removed from the DOM. while using with v-model, It may not exist on the DOM during the initialization of the popper. In that case, popup will not show. To rectify this scenerio, settings this prop to `true` will destroy old popper, related event listeners. Then it will reinitialize new popper again on every open request.
hide-on-click-outside	Boolean	`true`	Will hide the popup on clicking outside of the popup content.
arrow	Boolean	`false`	whether to show arrow on the popup.
arrow-class	String	`undefined`	css class of the arrow element.
ref-class	String	`undefined`	css class of the reference element.
popup-class	String	`undefined`	css class of the popup element.
disabled	Boolean	`false`	disable the component.
local-event-listener	Boolean	`false`	This package implements global event bus to listen on the events to optimize the performance. One event listener on the body element listen to all the event interactions. if any parent element uses `event.stopPropagation()`, it will not work with global event bus. So it is highly recommend not to use `event.stopPropagation()` on any parent element. If in case, it is absolutely needed to use stop propagation, this prop should set to `true`. In that case, event listeners will be registered locally. For every component, it will register two event listeners.
force-show	Boolean	`false`	set it to true to show the popup. Note: Need to reset before using again.
force-hide	Boolean	`false`	set it to true to hide the popup. Note: Need to reset before using again.
same-width-as-reference	Boolean	`false`	setting it to true will make the popup width to be equal to the width of the reference element (setting width with `popup-class` prop will override this value).
transition-name	String	`undefined`	transition name of the popup element. It uses vue.js `Transition` component. for details see here.
enter-from-class	String	`undefined`	enter-from-class of vue `Transition`.
enter-to-class	String	`undefined`	enter-to-class of vue `Transition`.
enter-active-class	String	`undefined`	enter-active-class of vue `Transition`.
leave-from-class	String	`undefined`	leave-from-class of vue `Transition`.
leave-to-class	String	`undefined`	leave-to-class of vue `Transition`.
leave-active-class	String	`undefined`	leave-active-class of vue `Transition`.

Events

ready
emitted when popper instance is created. event data are popper instance, popup element and reference element.

emit('ready', popper.value, popper_el.value, ref_el.value);

// typescript definition
(e: 'ready', popper: Instance, popperEl: Element | null, refEl: Element | VirtualElement | null ): void;

update:model-value
emitted if v-model is set.

emit('update:model-value', isPopperOpen.value);

// typescript definition
(e: 'update:model-value', isPopperOpen: boolean): void;

show
emitted when popup is shown.

emit('show');

// typescript definition
(e: 'show'): void;

hide
emitted when popup is hidden.

emit('hide');

// typescript definition
(e: 'hide'): void;

destroy
emitted when popper instance is destroyed.

emit('destroy');

// typescript definition
(e: 'destroy'): void;

create-error
emitted when popper is falied to initialize.

emit('create-error', popper_el.value, ref_el.value);

// typescript definition
( e: 'create-error', popperEl: Element | null, refEl: Element | VirtualElement | null ): void;

Slots

reference
reference element is rendered in this slot

Slot props:

isOpen {boolean} whether the popup is open

<template #reference="{ isOpen }">
    <button class="test-btn" :class="[isOpen ? 'active' : '']">
        Test button
    </button>
</template>

default
popup element is rendered in this slot

Slot props:

isOpen {boolean} whether the popup is open
show {function} show the popup
hide {function} hide the popup

<template #default="{ isOpen, show, hide }">
    <button class="show-btn" :class="[isOpen ? 'active' : '']" @click="show">
        Show
    </button>

    <button class="hide-btn" @click="hide">
        Hide
    </button>
</template>

Expose

Popup.vue exposes following properties:

isPopperOpen {boolean} whether the popup open
show {function} show the popup
hide {function} hide the popup
el {HTMLElement} root element of the popper

<script setup>
import { ref, onMounted } from 'vue';
const popperUtilities = ref(null);

onMounted(() => {
    console.log(popperUtilities.value?.isPopperOpen.value); // boolean
    console.log(popperUtilities.value?.el.value); // HTML element
    console.log(popperUtilities.value?.show); // Function
    console.log(popperUtilities.value?.hide); // Function
});
</script>

<template>
    <Popup ref="popperUtilities">
        <template #reference>Ref el</template>
        <div>Popup content</div>
    </Popup>
</template>

Dropdown.vue

This is the base Dropdown component. Technically any custom dropdown element can be rendered inside the popup, but it is recommended to use only DropdownItem.vue, DropdowChildren.vue as top level children for keyboard navigation. Any custom dropdown item will be skipped by keyboard navigation. If you want to render anything other than the dropdown, try Popup.vue instead.

<script setup>
import { Dropdown, DropdownItem, DropdownChild } from 'vue-popper-utilities';
import 'vue-popper-utilities/style.css';

const onItemClick = (x) => {
    console.log(`Dropdown item ${x} has been clicked`)
}
</script>

<template>
    <Dropdown trigger="click" :offset="[0, 8]" placement="right-start">
        <template #reference="{ isOpen }">
            <button class="test-btn" :class="[isOpen ? 'active' : '']">
                Test button
            </button>
        </template>

        <template v-slot="{ isOpen, hide }">
            <DropdownItem v-for="x in 6" :key="x" @click="onItemClick(x)">
                {{ `Item ${x}` }}
            </DropdownItem>

            <DropdownChild trigger="hover" :offset="[0, 0]" :hide-parent-on-item-click="false">
                <template #reference>
                    <button>Item child 1</button>
                </template>

                <div class="dropdown-child-1-container">
                    <DropdownItem v-for="y in 2" :key="y">
                        {{ `Item child ${y}` }}
                    </DropdownItem>
                </div>
            </DropdownChild>

            // this button will be skipped by keyboard navigation.
            // As this top level child is not either of DropdownItem or DropdownChild component
            <button @click="hide()">Hide manually</button>
        </template>
    </Dropdown>
</template>

If don't care about keyboard navigation, you can ignore good and bad example below.

If you want to style the wrapper container of the dropdown popup, use dropdown-class prop rather than wrapping it with a html element. Because for the keyboard navigation, it will seach for dropdown items and child items on the top level.

Bad ❌

<Dropdown>
    <template #reference>...</template>

    <template #default>
        // bad. we should not wrap the dropdown container with other element
        <div class="dropdown-wrapper">
            <DropdownItem>...</DropdownItem>
            <DropdownItem>...</DropdownItem>
        </div>
    </template>
</Dropdown>

Good ✅

// now we can style the dropdown wrapper element by `dropdown-class` props
<Dropdown dropdown-class="dropdown-wrapper">
    <template #reference>...</template>

    <template #default>
        // good. DropdownItem and DropdownChild is now top level child.
        <DropdownItem>...</DropdownItem>
        <DropdownChild>...</DropdownChild>
    </template>
</Dropdown>

Props

Same as props of Popup.vue

Additional Props:

Name	Type	Default	Description
hide-on-item-click	Boolean	`true`	whether to hide the dropdown on any item click.
hide-parent-on-item-click	Boolean	`true`	This prop is only applicable for dropdown children. if set to false, all parent dropdowns will not be hidden after close.
keyboard-navigation	Boolean	`true`	enable keyboard navigation.
dropdown-class	String	`undefined`	css classes to be appened on the dropdown container.

Events

Same as events of Popup.vue

Slots

Same as slots of Popup.vue

Expose

Same as expose of Popup.vue

DropdownChild.vue

This is the base DropdownChild component. Technically any custom dropdown element can be rendered inside the popup, but it is recommended to use only DropdownItem.vue, DropdowChildren.vue as top level children for keyboard navigation. Any custom dropdown item will be skipped by keyboard navigation. If you want to render anything other than the dropdown, try Popup.vue instead. If you want to customize the wrapper container of the dropdown popup, use dropdown-class prop.

Props

Same as events of Dropdown.vue

Additional Props:

Name	Type	Default	Description
child-arrow	Boolean	`true`	whether to show a arrow at the end for the dropdown child item.
child-arrow-class	String	`undefined`	css class to apply on the arrow.

Events

Same as events of Dropdown.vue

Slots

Same as slots of Dropdown.vue

Additional Slots:

child-arrow
arrow at end of dropdown children. any custom icon or element can be rendered here. If not used and child-arrow prop is set to true, then default arrow will be rendered.

Slot props:

isOpen {boolean} whether the popup is open

Expose

Same as expose of Dropdown.vue

DropdownItem.vue

This component has no api

Tooltip.vue

This component will render a tooltip on the target element. by default, trigger for this component is hover and placement is bottom. But can be customized throught props.

<Tooltip
    text="Lorem ipsum dolor sit amet consectetur adipisicing elit. Perspiciatis veritatis autem deserunt"
>
    <template #reference>
        <button class="tooltip-btn" >
            {{ `Tootlip button` }}
        </button>
    </template>
</Tooltip>

Props

Same as props of Popup.vue

Additional Props:

Name	Type	Default	Description
text	String	`undefined`	Text content of the tooltip. if custom tooltip content is required, use default slot instead.

Events

Same as events of Popup.vue

Slots

Same as slots of Popup.vue

Expose

Same as expose of Popup.vue

Styling

This package comes with minimal css implementation to make it unstyled as much possible. Using props like ref-class, popup-class, dropdown-class etc, it is possible to style as per your own theme.

Default styling can be changed through customizing the css variables. Default css variables are as listed.

--skn-popper-active-item-bg: #e6e6e6;
--skn-popper-active-item-hover: #fafafa;
--skn-popper-z-index: 1133;
--skn-popper-arrow-width: 12px;
--skn-popper-arrow-height: 12px;
--skn-popper-arrow-transform-plus: 6px;
--skn-popper-arrow-transform-minus: -6px;

--skn-popper-tooltip-bg: #121212;
--skn-popper-tooltip-color: #ffffff;
--skn-popper-tooltip-padding: 16px;
--skn-popper-tooltip-max-width: 320px;

--skn-popper-dropdown-container-background: #ffffff;
--skn-popper-dropdown-container-border: 1px solid #e6e6e6;
--skn-popper-dropdown-container-box-shadow: 0px 8px 10px 1px rgba(0, 0, 0, 0.14),
    0px 3px 14px 2px rgba(0, 0, 0, 0.12), 0px 5px 5px -3px rgba(0, 0, 0, 0.2);

we can also customize through css styling.

<style scoped>
:deep(.skn-popper .skn-popper__reference) {
    /* add custom styling here */
}
</style>

Bugs and new feature

Please create an issue on this repository for any bugs or any feature request.

License

This is open source project under MIT license.

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
.vscode		.vscode
src		src
.gitignore		.gitignore
README.md		README.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts

skn-036/vue-popper-utilities

Folders and files

Latest commit

History

Repository files navigation

Vue Popper Utilites

Getting started

Installation

Usage

Global registration

Use directly inside a component

Popup.vue

Normal usage

Opening popper dynamically with v-model

Props

Events

Slots

Expose

Dropdown.vue

Bad ❌

Good ✅

Props

Events

Slots

Expose

DropdownChild.vue

Props

Events

Slots

Expose

DropdownItem.vue

Tooltip.vue

Props

Events

Slots

Expose

Styling

Bugs and new feature

License

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages