Layercraft

A positioning engine for floating UI elements. Built to solve real problems with tooltips, dropdowns, and popovers — without the magic.

Why this exists

Positioning floating elements sounds simple until you hit:

• overflow: hidden clipping your dropdown
• z-index wars across stacking contexts
• Tooltips getting cut off at viewport edges
• Initial flicker before position is calculated
• Mysterious jumps when content resizes

Existing solutions (Popper.js, Floating UI) work, but they're often opaque. When something breaks, good luck debugging.

Layercraft takes a different approach: explicit math, predictable behavior, no magic.

Features

• 🎯 12 placement options — top, bottom, left, right with start/center/end alignment
• 🔄 Auto-flip — automatically flips when there's not enough space
• 🔀 Shift — keeps element within viewport without changing placement
• 📍 Fallback placements — custom flip order for complex layouts
• 🚀 Portal support — escape overflow: hidden containers
• ➡️ Arrow positioning — built-in arrow/caret support
• ⌨️ Keyboard support — Escape key to close
• 🖱️ Multiple triggers — click, hover
• 📏 Auto-update — responds to scroll, resize, and content changes
• ✨ Flicker-free — isReady flag prevents initial position jump
• 🪶 Lightweight — ~5KB minified + gzipped
• 📦 Tree-shakeable — only import what you use
• 🔷 TypeScript — fully typed API

Install

npm install layercraft

Quick Start

import { useAnchor } from 'layercraft';

function Tooltip() {
  const { refCallbacks, floatingStyles, isOpen, isReady } = useAnchor({
    placement: 'top',
    trigger: 'hover',
  });

  return (
    <>
      <button ref={refCallbacks.anchor}>Hover me</button>
      {isOpen && (
        <div 
          ref={refCallbacks.floating} 
          style={{
            ...floatingStyles,
            visibility: isReady ? 'visible' : 'hidden', // Prevents flicker
          }}
        >
          Tooltip content
        </div>
      )}
    </>
  );
}

Placements

        top-start      top      top-end
            ┌───────────────────────┐
            │                       │
 left-start │                       │ right-start
            │                       │
       left │       ANCHOR          │ right
            │                       │
   left-end │                       │ right-end
            │                       │
            └───────────────────────┘
     bottom-start   bottom   bottom-end

Examples

Click Trigger (Popover/Dropdown)

function Dropdown() {
  const { refCallbacks, floatingStyles, isOpen } = useAnchor({
    placement: 'bottom-start',
    trigger: 'click',
    closeOnOutsideClick: true,
    closeOnEscape: true,
  });

  return (
    <>
      <button ref={refCallbacks.anchor}>Open Menu</button>
      {isOpen && (
        <ul ref={refCallbacks.floating} style={floatingStyles}>
          <li>Option 1</li>
          <li>Option 2</li>
          <li>Option 3</li>
        </ul>
      )}
    </>
  );
}

Hover Trigger (Tooltip)

function Tooltip() {
  const { refCallbacks, floatingStyles, isOpen, isReady } = useAnchor({
    placement: 'top',
    trigger: 'hover',
    offset: 6,
  });

  return (
    <>
      <span ref={refCallbacks.anchor}>Hover for info</span>
      {isOpen && (
        <div 
          ref={refCallbacks.floating} 
          style={{
            ...floatingStyles,
            visibility: isReady ? 'visible' : 'hidden',
            background: '#333',
            color: 'white',
            padding: '4px 8px',
            borderRadius: '4px',
            fontSize: '14px',
          }}
        >
          Helpful tooltip text
        </div>
      )}
    </>
  );
}

With Portal (Escape overflow: hidden)

Use Portal when your anchor is inside an overflow: hidden container:

import { useAnchor, Portal } from 'layercraft';

function PopoverWithPortal() {
  const { refCallbacks, floatingStyles, isOpen } = useAnchor({
    placement: 'bottom',
    trigger: 'click',
  });

  return (
    <div style={{ overflow: 'hidden', position: 'relative' }}>
      <button ref={refCallbacks.anchor}>Click me</button>
      {isOpen && (
        <Portal>
          <div ref={refCallbacks.floating} style={floatingStyles}>
            I escape the overflow container!
          </div>
        </Portal>
      )}
    </div>
  );
}

When to use Portal:

• Anchor is inside overflow: hidden or overflow: auto
• Anchor is inside a scrollable container
• Floating element gets clipped by parent boundaries

With Arrow

function TooltipWithArrow() {
  const { refCallbacks, floatingStyles, arrowStyles, isOpen, isReady } = useAnchor({
    placement: 'top',
    trigger: 'hover',
    arrow: { size: 8 },
  });

  return (
    <>
      <button ref={refCallbacks.anchor}>Hover me</button>
      {isOpen && (
        <div 
          ref={refCallbacks.floating} 
          style={{
            ...floatingStyles,
            visibility: isReady ? 'visible' : 'hidden',
            background: '#333',
            color: 'white',
            padding: '8px 12px',
            borderRadius: '4px',
          }}
        >
          Tooltip with arrow
          <div 
            ref={refCallbacks.arrow} 
            style={{
              ...arrowStyles,
              position: 'absolute',
              width: 8,
              height: 8,
              background: '#333',
              transform: `${arrowStyles.transform} rotate(45deg)`,
            }} 
          />
        </div>
      )}
    </>
  );
}

Fallback Placements

Control the flip order when preferred placement doesn't fit:

const { actualPlacement } = useAnchor({
  placement: 'right',
  fallbackPlacements: ['left', 'bottom', 'top'], // Try these in order
});

// actualPlacement tells you which placement was actually used
console.log(`Using: ${actualPlacement}`);

Shift (Prevent Edge Clipping)

Shift keeps the floating element within viewport bounds without changing placement:

const { refCallbacks, floatingStyles, isOpen } = useAnchor({
  placement: 'right',
  shift: true,        // Enabled by default
  shiftPadding: 8,    // Padding from viewport edge
});

Without shift:              With shift:
┌─────────────────┐        ┌─────────────────┐
│            ┌────────     │         ┌──────┐│
│   Anchor   │Tooltip│     │ Anchor  │Tooltip│
│            └────────     │         └──────┘│
└─────────────────┘        └─────────────────┘
    (clips at edge)           (shifted to fit)

To disable shift:

const { ... } = useAnchor({
  placement: 'top',
  shift: false,  // Disable shifting
});

Controlled Mode

Manage open state yourself:

function ControlledPopover() {
  const [isOpen, setIsOpen] = useState(false);
  
  const { refCallbacks, floatingStyles } = useAnchor({
    placement: 'bottom',
    trigger: 'click',
  });

  return (
    <>
      <button 
        ref={refCallbacks.anchor}
        onClick={() => setIsOpen(!isOpen)}
      >
        {isOpen ? 'Close' : 'Open'}
      </button>
      {isOpen && (
        <div ref={refCallbacks.floating} style={floatingStyles}>
          Controlled content
          <button onClick={() => setIsOpen(false)}>Close</button>
        </div>
      )}
    </>
  );
}

Vanilla JavaScript

Use the core functions without React:

import { getPosition, getPositionWithFlip, shiftToViewport, getViewport } from 'layercraft';

const anchor = document.querySelector('#anchor');
const floating = document.querySelector('#floating');

const anchorRect = anchor.getBoundingClientRect();
const floatingRect = floating.getBoundingClientRect();
const viewport = getViewport();

// Step 1: Calculate position with auto-flip
const result = getPositionWithFlip(
  anchorRect,
  floatingRect,
  { placement: 'bottom', offset: 8 },
  viewport
);

// Step 2: Apply shift to keep within viewport
const shifted = shiftToViewport(
  result.top,
  result.left,
  floatingRect.width,
  floatingRect.height,
  viewport,
  8 // padding
);

// Step 3: Apply styles
floating.style.position = 'fixed';
floating.style.top = `${shifted.top}px`;
floating.style.left = `${shifted.left}px`;

API Reference

useAnchor(options)

Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | placement | Placement | 'bottom' | Where to position the floating element | | offset | number | 8 | Gap between anchor and floating element (px) | | trigger | 'click' \| 'hover' | 'click' | How to open the floating element | | closeOnOutsideClick | boolean | true | Close when clicking outside | | closeOnEscape | boolean | true | Close when pressing Escape | | autoFlip | boolean | true | Flip to opposite side if no space | | fallbackPlacements | Placement[] | undefined | Custom fallback placement order | | shift | boolean | true | Keep floating element within viewport by shifting | | shiftPadding | number | 8 | Padding from viewport edge when shifting (px) | | arrow | boolean \| { size: number } | false | Enable arrow positioning | | zIndex | number | 9999 | z-index for floating element |

Return Value

| Property | Type | Description | |----------|------|-------------| | isOpen | boolean | Current open state | | setIsOpen | function | Manually control open state | | isReady | boolean | true after position is calculated (use for visibility) | | floatingStyles | CSSProperties | Apply to floating element | | arrowStyles | CSSProperties | Apply to arrow element | | actualPlacement | Placement | The placement used (may differ if flipped) | | refCallbacks.anchor | function | Attach to anchor element | | refCallbacks.floating | function | Attach to floating element | | refCallbacks.arrow | function | Attach to arrow element |

Portal

Renders children into document.body (or custom container) to escape overflow containers.

import { Portal } from 'layercraft';

// Default: renders to document.body
<Portal>
  <div>Rendered at document.body</div>
</Portal>

// Custom container
<Portal container={document.getElementById('portal-root')}>
  <div>Rendered in #portal-root</div>
</Portal>

Core Functions

For vanilla JS or custom implementations:

import { 
  getPosition,           // Basic positioning
  getPositionWithFlip,   // Positioning with auto-flip
  shiftToViewport,       // Keep within viewport by shifting
  getArrowPosition,      // Arrow positioning
  clampToViewport,       // Clamp to viewport bounds
  isOutOfBounds,         // Check if position overflows
  getViewport,           // Get viewport dimensions
} from 'layercraft';

Architecture

src/
├── core/           # Pure positioning math, framework-agnostic
│   ├── getPosition.ts
│   ├── flip.ts
│   └── viewport.ts
└── react/          # React adapter
    ├── useAnchor.ts
    └── Portal.tsx

The core is framework-agnostic. The React hook is a thin wrapper. You could build Vue, Svelte, or vanilla adapters on the same core.

Limitations

• No z-index coordination — Use the zIndex option to manually manage stacking order between multiple floating elements
• No animations — Use CSS transitions or animation libraries
• React 17+ — Uses modern React features

Demo

👉 Live Demo

Local Development

# Install dependencies
npm install

# Start dev server
npm run dev

# Run tests
npm run test

# Build for production
npm run build

# Run Storybook
npm run storybook

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

License

MIT © Venkatesh M