Default

Click the trigger to open a popover below (default side). Uses native Popover API — no JS for open/close.

<button class="btn" data-variant="outline" popovertarget="my-popover">Open Popover</button>

<div class="popover" id="my-popover" popover>
  <div class="popover-header">
    <p class="popover-title">Dimensions</p>
    <p class="popover-description">Set the dimensions for the layer.</p>
  </div>
  <div class="popover-content">...</div>
</div>

With Form

Popover containing form fields — the canonical shadcn popover pattern.

Dimensions

Set the dimensions for the layer.

Align

Use data-align on the popover to control horizontal alignment: start, center (default), or end.

Start aligned

Popover aligned to the start edge.

Center aligned

Default center alignment.

End aligned

Popover aligned to the end edge.

Side

Use data-side to position the popover on a specific side of the trigger: top, right, bottom (default), or left.

Top side

Positioned above the trigger.

Right side

Positioned to the right.

Bottom side

Default bottom positioning.

Left side

Positioned to the left.

CSS view file

Defines the panel size, spacing, and animation. CSS anchor positioning provides the default placement before the positioning module runs.

@layer components {
  .popover {
    position: fixed;
    inset: var(--popover-y, auto) auto auto var(--popover-x, auto);
    position-area: bottom;
    position-try-fallbacks: flip-block;
    margin: 0;
    box-sizing: border-box;
    width: 18rem;
    max-width: calc(100dvw - 1rem);
    max-height: calc(100dvh - 1rem);
    overflow: auto;
    overscroll-behavior: contain;
    border: none;
    border-radius: var(--radius-lg);
    background-color: var(--popover);
    color: var(--popover-foreground);
    padding: 0.625rem;
    font-size: 0.875rem;
    line-height: 1.25rem;
    box-shadow: var(--shadow-md), 0 0 0 1px color-mix(in oklch, var(--foreground) 10%, transparent);
    opacity: 0;
    transition: opacity 100ms ease, display 100ms allow-discrete, overlay 100ms allow-discrete;

    /* Use the measured coordinates when positioning JS is loaded. */
    &[data-positioned] { position-area: none; }

    &:popover-open {
      display: flex;
      flex-direction: column;
      gap: 0.625rem;
      opacity: 1;
    }
  }

  @starting-style {
    .popover:popover-open { opacity: 0; }
  }

  .popover-header { display: flex; flex-direction: column; gap: 0.125rem; }
  .popover-title { margin: 0; font-weight: 500; }
  .popover-description { margin: 0; color: var(--muted-foreground); }

  @media (prefers-reduced-motion: reduce) {
    .popover { transition: none; }
  }

  @media (forced-colors: active) {
    .popover { outline: 1px solid CanvasText; }
  }
}

JavaScript view file

Positions the panel against its opener, flips sides when space is tight, and keeps the panel within the viewport. The native Popover API handles opening, closing, and light-dismiss.

// Placement for native popovers. The browser owns activation, dismissal and focus.
const openPopovers = new Map();
const recentTriggers = new WeakMap();
const edges = { top: 'bottom', bottom: 'top', left: 'right', right: 'left' };
const gutter = 8;
const gap = 4;
let frame = 0;

function position(popover, trigger) {
  const viewport = window.visualViewport;
  const left = (viewport?.offsetLeft ?? 0) + gutter;
  const top = (viewport?.offsetTop ?? 0) + gutter;
  const right = left + (viewport?.width ?? document.documentElement.clientWidth) - gutter * 2;
  const bottom = top + (viewport?.height ?? document.documentElement.clientHeight) - gutter * 2;
  popover.dataset.positioned = '';
  const anchor = trigger.getBoundingClientRect();
  const { width, height } = popover.getBoundingClientRect();
  const available = {
    top: anchor.top - top - gap,
    bottom: bottom - anchor.bottom - gap,
    left: anchor.left - left - gap,
    right: right - anchor.right - gap,
  };

  let side = Object.hasOwn(edges, popover.dataset.side) ? popover.dataset.side : 'bottom';
  const vertical = side === 'top' || side === 'bottom';
  const opposite = edges[side];
  if (available[side] < (vertical ? height : width) && available[opposite] > available[side]) {
    side = opposite;
  }

  let align = popover.dataset.align;
  if (vertical && getComputedStyle(trigger).direction === 'rtl') {
    if (align === 'start') align = 'end';
    else if (align === 'end') align = 'start';
  }

  const crossStart = vertical ? anchor.left : anchor.top;
  const crossEnd = vertical ? anchor.right : anchor.bottom;
  const crossSize = vertical ? width : height;
  let cross = (crossStart + crossEnd - crossSize) / 2;
  if (align === 'start') cross = crossStart;
  else if (align === 'end') cross = crossEnd - crossSize;

  const x = vertical ? cross : side === 'left' ? anchor.left - gap - width : anchor.right + gap;
  const y = vertical ? side === 'top' ? anchor.top - gap - height : anchor.bottom + gap : cross;
  popover.style.setProperty('--popover-x', `${Math.max(left, Math.min(x, right - width))}px`);
  popover.style.setProperty('--popover-y', `${Math.max(top, Math.min(y, bottom - height))}px`);
}

function updatePositions() {
  frame = 0;
  for (const [popover, entry] of openPopovers) {
    if (popover.isConnected && popover.matches(':popover-open') && entry.trigger.isConnected) {
      position(popover, entry.trigger);
    } else {
      entry.observer.disconnect();
      openPopovers.delete(popover);
    }
  }
}

function schedulePositions() {
  if (openPopovers.size && !frame) frame = requestAnimationFrame(updatePositions);
}

document.addEventListener('click', event => {
  const trigger = event.target instanceof Element && event.target.closest('[popovertarget]');
  const popover = trigger?.popoverTargetElement;
  if (popover?.matches('.popover') && !popover.matches(':popover-open')) recentTriggers.set(popover, trigger);
}, true);

document.addEventListener('toggle', event => {
  const popover = event.target;
  if (!(popover instanceof HTMLElement) || !popover.matches('.popover[popover]')) return;

  openPopovers.get(popover)?.observer.disconnect();
  openPopovers.delete(popover);
  if (event.newState === 'closed') {
    delete popover.dataset.positioned;
    popover.style.removeProperty('--popover-x');
    popover.style.removeProperty('--popover-y');
    recentTriggers.delete(popover);
    return;
  }

  const trigger = event.source ?? recentTriggers.get(popover);
  if (!(trigger instanceof HTMLElement)) return;
  const observer = new ResizeObserver(schedulePositions);
  observer.observe(trigger);
  observer.observe(popover);
  openPopovers.set(popover, { trigger, observer });
  position(popover, trigger);
}, true);

window.addEventListener('scroll', schedulePositions, { capture: true, passive: true });
window.addEventListener('resize', schedulePositions);
window.visualViewport?.addEventListener('resize', schedulePositions);
window.visualViewport?.addEventListener('scroll', schedulePositions);