Overlay

Overlay is a complete positioning and interaction system for floating UI elements. It handles trigger/content refs, dynamic positioning with viewport edge flipping, event listeners, and nested overlay blocking.

Basic Usage

import { Overlay } from '@vitus-labs/elements'

// Dropdown
<Overlay trigger={<button>Menu</button>}>
  <div>Dropdown content</div>
</Overlay>

// Tooltip on hover
<Overlay
  type="tooltip"
  openOn="hover"
  closeOn="hover"
  align="top"
  trigger={<span>Hover me</span>}
>
  <div>Tooltip text</div>
</Overlay>

Props

Content

Behavior

Positioning

Render Props

When using render functions, trigger and content receive interaction props:

Trigger Render Props

<Overlay
  trigger={(props) => (
    <button ref={props.ref}>
      {props.active ? 'Close' : 'Open'}
    </button>
  )}
>
  <div>Content</div>
</Overlay>

Content Render Props

<Overlay trigger={<button>Open</button>}>
  {(props) => (
    <div ref={props.ref}>
      Aligned: {props.align} / {props.alignX}
      <button onClick={props.hideContent}>Close</button>
    </div>
  )}
</Overlay>

Positioning Types

Dropdown

Positioned relative to trigger, below by default. Flips to top if not enough space.

<Overlay type="dropdown" align="bottom" alignX="left">
  ...
</Overlay>

Tooltip

Similar to dropdown but typically used with hover:

<Overlay type="tooltip" openOn="hover" closeOn="hover" align="top">
  ...
</Overlay>

Modal

Centered in viewport:

<Overlay
  type="modal"
  openOn="click"
  closeOn="clickOutsideContent"
  closeOnEsc
>
  {(props) => (
    <div style={{ background: 'white', padding: 24, borderRadius: 8 }}>
      Modal content
      <button onClick={props.hideContent}>Close</button>
    </div>
  )}
</Overlay>

Dynamic Positioning

Overlay automatically flips direction when content would go off-screen:

• If align="bottom" but there's no space below, flips to "top"
• If alignX="left" but content overflows right, adjusts to "right"
• Center alignment centers the content relative to the trigger

How Positioning Works

1. Content mounts in portal — contentRef callback fires, signals ready
2. getBoundingClientRect() — Measures trigger and content dimensions
3. Viewport check — Tests if content fits in preferred direction (fitsTop, fitsBottom, fitsLeft, fitsRight)
4. Auto-flip — If preferred direction doesn't fit, selects the best alternative
5. Offset application — Adds offsetX/offsetY margins
6. Style assignment — Sets position, top, left, right, bottom directly on the content element

Absolute vs Fixed Positioning

• position: 'fixed' (default): Content positioned relative to the viewport
• position: 'absolute': Content positioned relative to its offsetParent. The system automatically subtracts the offsetParent's viewport rect to compute correct placement.

Modal Body Scroll Lock

When type="modal" and the overlay is active:

• document.body.style.overflow = 'hidden' — prevents background scrolling
• Reset to original on close

Performance

• Position recalculation is throttled by throttleDelay (default: 200ms)
• Scroll and resize listeners use { passive: true } for better scrolling performance
• useLayoutEffect + requestAnimationFrame — positions immediately, then re-measures after browser reflow
• Throttled callbacks use the "latest ref" pattern to access current state without stale closures

Nested Overlays

Child overlays automatically block parent from closing when interacting with nested content:

<Overlay trigger={<button>Main Menu</button>}>
  {(props) => (
    <div ref={props.ref}>
      <div>Item 1</div>
      <Overlay trigger={<div>Submenu</div>} align="right">
        {(subProps) => (
          <div ref={subProps.ref}>
            <div>Sub Item 1</div>
            <div>Sub Item 2</div>
          </div>
        )}
      </Overlay>
    </div>
  )}
</Overlay>

useOverlay Hook

For full control without the Overlay component:

import { useOverlay } from '@vitus-labs/elements'

function CustomDropdown() {
  const {
    active,
    triggerRef,
    contentRef,  // callback ref!
    showContent,
    hideContent,
    Provider,
    ...ctx
  } = useOverlay({
    openOn: 'click',
    closeOnEsc: true,
  })

  return (
    <>
      <button ref={triggerRef} onClick={showContent}>
        Toggle
      </button>
      {active && (
        <Portal>
          <Provider {...ctx}>
            <div ref={contentRef}>Content</div>
          </Provider>
        </Portal>
      )}
    </>
  )
}

Important: contentRef is a callback ref — assign it directly as ref={contentRef}.

useOverlay Return Value

Event Listeners

When the overlay is active, these listeners are attached (web only):

All listeners are cleaned up on unmount or when the overlay closes.

API Reference