Dropdown Menu Pattern

Build dropdown menus that work correctly in list/card contexts, handling z-index stacking and click-outside dismissal properly.

Why This Pattern?

Dropdown menus in list items have three common bugs:

1. Clipped by parent's overflow-hidden - dropdown gets cut off
2. Covered by sibling cards - z-index doesn't help across stacking contexts
3. Double-toggle on trigger click - menu closes then reopens immediately

This pattern solves all three.

Core Implementation

"use client";

import { useState, useRef, useEffect } from "react";
import { MoreVertical, Pause, X } from "lucide-react";

// The dropdown menu component
function DropdownMenu({
  dark = false,
  onClose,
}: {
  dark?: boolean;
  onClose: () => void;
}) {
  const menuRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    function handleClickOutside(event: MouseEvent) {
      if (menuRef.current && !menuRef.current.contains(event.target as Node)) {
        onClose();
      }
    }
    // IMPORTANT: Use "click" not "mousedown" to allow stopPropagation on trigger
    document.addEventListener("click", handleClickOutside);
    return () => document.removeEventListener("click", handleClickOutside);
  }, [onClose]);

  return (
    <div
      ref={menuRef}
      className={`absolute right-0 top-full mt-1 z-20 rounded-lg shadow-lg border overflow-hidden ${
        dark ? "bg-zinc-800 border-zinc-700" : "bg-white border-zinc-200"
      }`}
    >
      <button
        className={`flex items-center gap-2 w-full px-3 py-2 text-xs font-medium transition-colors ${
          dark
            ? "text-zinc-300 hover:bg-zinc-700"
            : "text-zinc-700 hover:bg-zinc-50"
        }`}
        onClick={(e) => {
          e.stopPropagation();
          onClose();
        }}
      >
        <Pause className="w-3.5 h-3.5" strokeWidth={1.5} />
        Pause
      </button>
      <button
        className={`flex items-center gap-2 w-full px-3 py-2 text-xs font-medium transition-colors ${
          dark ? "text-red-400 hover:bg-zinc-700" : "text-red-600 hover:bg-red-50"
        }`}
        onClick={(e) => {
          e.stopPropagation();
          onClose();
        }}
      >
        <X className="w-3.5 h-3.5" strokeWidth={1.5} />
        Cancel
      </button>
    </div>
  );
}

Key Elements

1. Click-Outside Detection (Use click, NOT mousedown)

// CORRECT - allows stopPropagation on trigger button
document.addEventListener("click", handleClickOutside);

// WRONG - fires before button's onClick, causing double-toggle
document.addEventListener("mousedown", handleClickOutside);

Why? With mousedown, the sequence is:

1. mousedown fires → click-outside closes menu
2. click fires on button → toggle reopens menu

With click, stopPropagation() on the button prevents the document listener from firing.

2. Parent Card Z-Index Elevation

When menu is open, elevate the entire parent card above siblings:

<div
  className={`rounded-xl border cursor-pointer relative ${
    menuOpen ? "z-30" : "z-0"
  }`}
>
  {/* card content with dropdown inside */}
</div>

Why? Each card creates its own stacking context. The dropdown's z-20 only applies within its card. Sibling cards rendered later in the DOM naturally stack on top.

3. Avoid overflow-hidden on Dropdown Containers

// BAD - clips dropdown regardless of z-index
<div className="rounded-xl overflow-hidden">
  <DropdownMenu />
</div>

// GOOD - only use overflow-hidden where needed (e.g., expandable sections)
<div className="rounded-xl">
  <div className="relative">
    <DropdownMenu />
  </div>
  <div className="overflow-hidden">
    {/* expandable content only */}
  </div>
</div>

4. Trigger Button with stopPropagation

<div className="relative">
  <button
    onClick={(e) => {
      e.stopPropagation(); // Prevents parent card click AND click-outside
      onMenuToggle?.();
    }}
    className="p-1.5 -m-1.5 rounded-lg hover:bg-zinc-100 transition-colors cursor-pointer"
  >
    <MoreVertical className="w-5 h-5 text-zinc-400" strokeWidth={1.5} />
  </button>
  {menuOpen && onMenuClose && <DropdownMenu onClose={onMenuClose} />}
</div>

Note the -m-1.5 negative margin - this increases the clickable area without affecting layout.

Full Card Example with Dropdown

interface CardProps {
  title: string;
  menuOpen?: boolean;
  onMenuToggle?: () => void;
  onMenuClose?: () => void;
}

function Card({ title, menuOpen = false, onMenuToggle, onMenuClose }: CardProps) {
  return (
    <div
      className={`rounded-xl border border-zinc-200 p-4 cursor-pointer relative ${
        menuOpen ? "z-30" : "z-0"
      }`}
      onClick={() => console.log("card clicked")}
    >
      <div className="flex items-center justify-between">
        <span className="font-medium">{title}</span>
        <div className="relative">
          <button
            onClick={(e) => {
              e.stopPropagation();
              onMenuToggle?.();
            }}
            className="p-1.5 -m-1.5 rounded-lg hover:bg-zinc-100 transition-colors"
          >
            <MoreVertical className="w-5 h-5 text-zinc-400" strokeWidth={1.5} />
          </button>
          {menuOpen && onMenuClose && <DropdownMenu onClose={onMenuClose} />}
        </div>
      </div>
    </div>
  );
}

// Parent component managing which menu is open
function CardList() {
  const [openMenu, setOpenMenu] = useState<number | null>(null);
  const items = ["Item 1", "Item 2", "Item 3"];

  return (
    <div className="flex flex-col gap-3">
      {items.map((item, index) => (
        <Card
          key={index}
          title={item}
          menuOpen={openMenu === index}
          onMenuToggle={() => setOpenMenu(openMenu === index ? null : index)}
          onMenuClose={() => setOpenMenu(null)}
        />
      ))}
    </div>
  );
}

Menu Positioning Options

// Below, right-aligned (default)
className="absolute right-0 top-full mt-1"

// Below, left-aligned
className="absolute left-0 top-full mt-1"

// Above, right-aligned
className="absolute right-0 bottom-full mb-1"

// Above, left-aligned
className="absolute left-0 bottom-full mb-1"

Related: Tooltips in Stacked Items

When showing tooltips on items that have varying z-indexes (like stacked cards), the tooltip will be trapped in its parent's stacking context. The solution is to render the tooltip outside the item loop as a sibling element, calculating its position based on which item is hovered.

See the stacked-cards skill for the full pattern.

// WRONG - Tooltip trapped in parent's z-index
{items.map((item, i) => (
  <div style={{ zIndex: items.length - i }}>
    <Card />
    {hovered === i && <Tooltip />}  {/* Trapped! */}
  </div>
))}

// CORRECT - Tooltip outside the loop
{items.map((item, i) => (
  <div style={{ zIndex: items.length - i }}>
    <Card />
  </div>
))}
{hovered !== null && (
  <Tooltip style={{ /* calculated position */ }} />
)}

Checklist

• Click-outside uses click event (not mousedown)
• Parent card has conditional z-30 when menu is open
• No overflow-hidden on containers that hold the dropdown
• Trigger button has stopPropagation() in onClick
• Menu items have stopPropagation() in onClick
• Trigger wrapper has relative positioning
• Dropdown has absolute positioning with top-full or bottom-full
• For stacked items, tooltip rendered outside the loop (see stacked-cards skill)