@cosmo-design/popper v1.2.0

Popper

Popper is a small yet powerful popper library that can automatically pop up at a suitable position adjacent to the trigger. It also supports virtual elements, which can be used in canvas and CSS class animations.

Playground

中文文档

Install

npm i @cosmo-design/popper

or via CDN

<script src="https://unpkg.com/@cosmo-design/popper@latest/dist/index.min.js"></script>
<script>
  console.log(popper)
</script>

Usage

import Popper, { PLACEMENT, EmitType } from '@cosmo-design/popper'

const container = document.querySelector('.container'); // default: document.body
const trigger = document.querySelector('.trigger'); 
// or virtual element. type: { getBoundingClientRect: () =>  { left: number, top: number, width: number, height: number } }

const content = document.createElement('div'); // You need to pop up the displayed content
content.classList.add('content');

const popper = new Popper({
  container,
  trigger, // required
  content, // required
  placement: PLACEMENT.T, // Set the position of the popper
  emit: EmitType.HOVER // Set to open the popper when the mouse hovers over the trigger
})

trigger.onclick = () => {
  popper.toggle()
  // or
  // if (popper.opened) {
  //   popper.close();
  // } else {
  //   popper.open();
  // }
}

// if you don't need it anymore
popper.destroy()

CSS Animation

The cssName parameter allows you to add CSS animations when showing and hiding the popper.

const popper = new Popper({
  cssName: 'fade'
})

Popper will add the following 6 classes through the cssName.

`${cssName}-enter-from` // Starts displaying and is removed in the next frame.
`${cssName}-enter-active` // Added in the next frame and removed when the animation ends.
`${cssName}-enter-to` // Added in the next frame and removed when the animation ends.
`${cssName}-exit-from` // Starts hiding and is removed in the next frame.
`${cssName}-exit-active` // Added in the next frame and removed when the animation ends.
`${cssName}-exit-to` // Added in the next frame and removed when the animation ends.
`${cssName}-${PLACEMENT}` // Current popper placement

You can write CSS styles like this:

.fade-enter-from, .fade-exit-to {
  transform: scale(.7);
  opacity: 0;
}
.fade-enter-active, .fade-exit-active {
  transition: transform .1s ease, opacity .1s ease;
}

Arrow

The arrow parameter allows you to add a custom arrow element.

const arrow = document.createElement('div')
arrow.classList.add('arrow')

const popper = new Popper({
  arrow
})

.arrow {
  width: 12px;
  height: 12px;
  transform: rotate(45deg);
  transform-origin: center;
  background: #000;
}

Alternatively, an arrow can be quickly created using the built-in createArrow function.

import Popper, { createArrow } from '@cosmo-design/popper' 

const popper = new Popper({
  arrow: createArrow({ background: '#000' })
})

Scroll

The autoScroll parameter controls whether the popper automatically scrolls with the trigger element when it is scrolled.

The closeOnScroll parameter controls whether the popper automatically closes when the trigger element is scrolled.

The hideOnInvisible parameter controls whether the popper automatically hides when the trigger element is not visible on the screen.

AutoUpdate

The autoUpdate parameter controls whether the popper's position is automatically updated when the size of the container, content, or trigger element changes. This feature relies on the ResizeObserver.

The autoPlacement parameter controls whether the popper's position is automatically adjusted to ensure that it is fully displayed when there is not enough space.

Hook

Popper provides rich hook functions that can execute code during various stages of the popper's lifecycle.

new Popper({
  onBeforeEnter() {
    // Executed before the CSS display animation starts.
  },
  onEntered() {
    // Executed after the CSS display animation completes.
  },
  onBeforeExit() {
    // Executed before the CSS hide animation starts.
  },
  onExited() {
    // Executed after the CSS hide animation completes.
  },
  onBeforePosition(pos) {
    // Executed before setting the popper's position.
    // pos.position: the final display position.
    // pos.xy: the position of the popper, undefined means not displayed.
    // pos.arrowXY: the position of the arrow, undefined means not displayed.
    // You can modify xy and arrowXY directly to change the final position.
    if (pos.xy) pos.xy[0] += 10
    if (pos.arrowXY) pos.arrowXY[0] += 10
  },
  onOpen() {
    // Executed when the popper is displayed.
  },
  onClose() {
    // Executed when the popper is closed.
  }
})

Virtual Element

The trigger parameter can be a virtual element in addition to a DOM element. This allows you to use Popper with canvas. When the canvas is scrolled, you can manually call the popper.onScroll() method to trigger the popper to scroll.

const popper = new Popper({
  trigger: {
    getBoundingClientRect() {
      return {
        left: 0,
        top: 0,
        width: 0,
        height: 0
      }
    }
  }
})

canvas.on('scroll', () => popper.onScroll())

API

Config

Property

Methods

open()

Open the Popper instance.

open(): void;

close()

Close the Popper instance.

close(): void;

toggle()

Toggle the Popper instance open or close.

toggle(): void;

openWithDelay()

Open the popper after config.openDelay time.

openWithDelay(): void;

closeWithDelay()

Close the popper after config.closeDelay time.

closeWithDelay(): void;

enable()

Enable.

enable(): void

disable()

Disable and close popper.

disable(): void

updateConfig()

Update config.

updateConfig(config: Partial<PopperConfig>): void;

destroy()

Destroy the Popper instance.

destroy(): void;

onScroll()

Manually trigger the onScroll event. Generally only used when using a virtual element.

onScroll(): void;

update()

Manually update the position of the Popper instance.

update(): void;

Utils

Popper also provides utility methods for quickly creating arrow elements.

import Popper, { createArrow } from '@cosmo-design/popper'

new Popper({
  arrow: createArrow()
})

createArrow()

Quickly create arrow DOM elements that can accept CSS style objects and class names as parameters.

createArrow(style?: CSSStyleDeclaration, className?: string): HTMLElement;