popflow v1.0.0

PopFlow

PopFlow is a small yet powerful pop-up tool 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 popflow

or via CDN

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

Usage

import { PopFlow } from 'popflow'

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 popflow = new PopFlow({
  container,
  trigger, // required
  content, // required
})

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

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

CSS Animation

The cssName parameter allows you to add CSS animations when showing and hiding a pop-up layer.

const popflow = new PopFlow({
  cssName: 'fade'
})

PopFlow 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.

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 popflow = new PopFlow({
  arrow
})

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

Scroll

The autoScroll parameter controls whether the pop-up layer automatically scrolls with the trigger element when it is scrolled.

The closeOnScroll parameter controls whether the pop-up layer automatically closes when the trigger element is scrolled.

The hideOnInvisible parameter controls whether the pop-up layer automatically hides when the trigger element is not visible on the screen.

AutoUpdate

The autoUpdate parameter controls whether the pop-up layer'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 pop-up layer's position is automatically adjusted to ensure that it is fully displayed when there is not enough space.

Hook

PopFlow provides rich hook functions that can execute code during various stages of the pop-up layer's lifecycle.

new PopFlow({
  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 pop-up layer's position.
    // pos.position: the final display position.
    // pos.xy: the position of the pop-up layer, 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 pop-up layer is displayed.
  },
  onClose() {
    // Executed when the pop-up layer is closed.
  }
})

Virtual Element

The trigger parameter can be a virtual element in addition to a DOM element. This allows you to use PopFlow with canvas. When the canvas is scrolled, you can manually call the popflow.onScroll() method to trigger the pop-up layer to scroll.

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

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

API

Config

Property

Methods

open()

Open the PopFlow instance.

open(): void;

close()

Close the PopFlow instance.

close(): void;

toggle()

Toggle the PopFlow instance open or close.

toggle(): void;

destroy()

Destroy the PopFlow 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 PopFlow instance.

update(): void;