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

| Name | Type | Description | | -- | -- | -- | | container | HTMLElement | The container of the popup. Default value: document.body. | | content | Element | The content element to be popped up | | trigger | { getBoundingClientRect: () => Rect } \| Element | The trigger element | | arrow | Element | The arrow element. | | placement | PLACEMENT | The placement of the popup. Default: 't'. | | translate | [number, number] | The custom xy offset. | | autoPlacement | boolean | Whether to automatically switch the position when there is not enough space. Default: true. | | autoUpdate | boolean | Whether to automatically update the position when the container, content, or trigger size changes. Default: true. | | autoScroll | boolean | Whether to automatically follow the trigger element when it is scrolled. Default: true. | | cssName | string | The CSS animation class name. | | overflowHidden | boolean | Whether the container has overflow hidden. Default: automatically detected. | | coverTrigger | boolean | Whether to cover the trigger element with the popup. | | closeOnScroll | boolean | Whether to automatically close the popup when the trigger element is scrolled. | | hideOnInvisible | boolean | Whether to automatically hide the popup when the trigger element is invisible on the screen. | | onBeforeEnter | () => void | Called before the CSS enter animation starts. | | onEntered | () => void | Called when the CSS enter animation ends. | | onBeforeExit | () => void | Called before the CSS exit animation starts. | | onExited | () => void | Called when the CSS exit animation ends. | | onBeforePosition | (pos: Position) => void | Called before setting the position of the popup. You can modify the pos object to set the final position of the popup. | | onOpen | () => void | Called when the popup is opened. | | onClose | () => void | Called when the popup is closed. |

Property

| Name | Type | Description | | -- | -- | -- | | el | HTMLElement | The pop-up layer element | | config | PopFlowConfig | PopFlow configuration object | | opening | boolean | Indicates whether the pop-up layer is currently displayed | | isAnimation | boolean | Indicates whether a CSS animation is currently in progress |

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;