codebender828 / popper-vue

🎊 A lightweight Popper utility component for Vue.js

🎊 popper-vue

A lightweight bring-your-own-component(BYOC) Popper for Vue.js

🌟 Features

popper-vue neatly and snugly implements Popper.js into a simple <Popper> component that you can use to wrap it's children inside of a popper around an anchor element in your Vue applications.

• Render whatever you want: Utilize the render callback to create entirely custom poppers.
• Functional default styles: Import the provided css for some nice styling defaults or write your own styles.
• Portal your poppers anywhere in the DOM: You can use a portal element to render your popper, or if you want to yet, use direct child.

Codesandbox Demo

⚡️ Installation

$ npm install popper-vue popper.js

Please note that popper-vue assumes that you already have Vue.js installed in your application. If you not have Vue installed. Install it by running npm install vue --save

Global Popper registration

In your main.js:

import { Popper } from 'popper-vue'
import 'popper-vue/dist/popper-vue.css'

Vue.component('Popper', Popper)

Local Popper import

In your templates:

<template>
  <div id="app">
    <button ref="anchorEl" @click="showPopper">Toggle portal</button>
    <Popper
      :is-open="show"
      :anchor-el="$refs.anchorEl"
      :on-close="hidePopper"
    >
      <aside id="popper-content">
        I am a Happy Popper 😀
      </aside>
    </Popper>
  </div>
</template>

<script lang="js">
import { Popper } from 'popper-vue'
import 'popper-vue/dist/popper-vue.css'

export default {
  name: 'App',
  components: {
    Popper
  },
  data () {
    return {
      show: false
    }
  },
  methods: {
    showPopper () {
      this.show = !this.show
    },
    hidePopper () {
      this.show = false
    }
  }
}
</script>

🏋🏼‍♀️ API

popper-vue provides a few components that allow to render custom popper components.

✅ - Completed! ⚠️ - WIP

🧤 Props

Props	Description	Values	Default
✅anchorEl	Anchor element around which popper is positioned	HTMLElement	N/A
✅ placement	Default position where popperEl should be placed when Popper is open	top, right, bottom, left	bottom
✅ modifiers	Modifier options for popper.js. See popper.js docs for more information	Object	{}
✅ isOpen	Determines whether the Popper is open or not	Boolean	false
✅ onClose	Handler function to be called when the popper is to be closed	Function	null
✅closeOnClickAway	Determines whether popper should close when other elements are clicked	Boolean	true
⚠️ usePortal	Determines whether popper should mount popperEl in portal before positioning it around anchor.	Boolean	false
✅ hasArrow	Determines whether popper should possess arrow when shown	Boolean	true

📅 Events

Events	Description	Payload
✅ popper:create	Emitted when popperEl is open and has been mounted by popper.js	{ el: popperEl<HTMLElement> }
✅ popper:update	Emitted when Popper.js instance undergoes an update	{ el: HTMLElement }
✅ popper:close	Emitted when popperEl is closed and has been unmounted by popper.js	{}

⚠️ Caveats

• The popper:close event is sometimes emitted twice when the popper is being closed when the closeOnClickAway props is truthy. Currently there are no implemented workarounds for this yet, so while using this component make sure to be careful of it. It's also worth pointing out that this may not be that big of a problem for most consumer use cases

📚TODO

• Publish to NPM
• Upgrade to @popperjs/core support
• Finish Popper Portal implementation
• Create usePopper utility plugin funciton hook
• Docs site
• Codesandbox examples
• Articles to illustrate how to use popper-vue in component library
• Type declaration files for plugin

🦑 Contributors

• Jonathan Bakebwa
• This could be you :)

🤝 Contributing

Here's our contribution guide.

❤️ Support this project

If you like this project, please consider supporting it by buying my a coffee!

Buy me a coffee
Made with ❤️ by Jonathan Bakebwa 🇺🇬

Contributors ✨

Thanks goes to these wonderful people (emoji key):

Jonathan Bakebwa 💻

Mesut 💻

This project follows the all-contributors specification. Contributions of any kind welcome!