Anatomy

The root is a semantic nav element with aria-label. Inside, a flex row renders one DropdownSegment per path entry. Each DropdownSegment holds three parts: a slash separator (skipped for the first segment), a button trigger showing an optional icon, the segment label, and a rotating ChevronDown, then an AnimatePresence-gated floating div for the dropdown panel listing child links as anchor tags.

How it works

Each segment manages its own open/closed state with useState. A useEffect attaches a mousedown listener to document and compares the click target against the segment ref, if outside, the panel closes. The dropdown panel animates with initial `{ opacity: 0, y: -4, scale: 0.96 }` and animate `{ opacity: 1, y: 0, scale: 1 }` via Framer Motion, using the spring-like ease `[0.16, 1, 0.3, 1]`. The ChevronDown icon itself is a motion.span with `animate={{ rotate: open ? 180 : 0 }}`, providing clear visual feedback of the panel state.

How to build it in React

1. Define the data types and icon map

   Start with two interfaces: BreadcrumbChild (label + href) and BreadcrumbSegment (label, optional href, optional icon key, optional children array). Build an iconMap object that maps the string keys 'home', 'folder', 'file' to their Lucide components, so segments declare an icon by name rather than by importing it directly.

   interface BreadcrumbSegment {
     label: string;
     href?: string;
     icon?: "home" | "folder" | "file";
     children?: { label: string; href: string }[];
   }
   const iconMap: Record<string, React.ElementType> = {
     home: Home, folder: Folder, file: FileText,
   };

2. Build the DropdownSegment with click-outside detection

   Give each segment its own useState(false) for open/closed. Attach a ref to the wrapping motion.div, then in a useEffect add a mousedown listener on document. Inside the handler, check if the event target is outside the ref, if so, call setOpen(false). Return a cleanup that removes the listener. This pattern isolates each segment so multiple dropdowns never conflict.

   const ref = useRef<HTMLDivElement>(null);
   useEffect(() => {
     function handler(e: MouseEvent) {
       if (ref.current && !ref.current.contains(e.target as Node))
         setOpen(false);
     }
     document.addEventListener("mousedown", handler);
     return () => document.removeEventListener("mousedown", handler);
   }, []);

3. Animate the dropdown panel with AnimatePresence

   Wrap the conditional panel in AnimatePresence so Framer Motion can play the exit animation before unmounting. Give the motion.div initial and exit states of opacity 0, y -4, and scale 0.96, with animate restoring them to 1/0/1. Use the custom easing array [0.16, 1, 0.3, 1] for an overshoot-free spring feel without a real spring config.

   <AnimatePresence>
     {open && (
       <motion.div
         initial={{ opacity: 0, y: -4, scale: 0.96 }}
         animate={{ opacity: 1, y: 0, scale: 1 }}
         exit={{ opacity: 0, y: -4, scale: 0.96 }}
         transition={{ duration: 0.2, ease: [0.16, 1, 0.3, 1] }}
         style={{ position: "absolute", top: "calc(100% + 4px)", left: 0 }}
       >
         {children}
       </motion.div>
     )}
   </AnimatePresence>

4. Stagger the breadcrumb entrance on mount

   Pass the segment index down to DropdownSegment and use it in the motion.div transition delay: index * 0.08 seconds. Combined with initial opacity 0 and y -8, this makes the breadcrumb appear to assemble left to right on first render, giving the nav a polished feel without a separate orchestrator component.

   <motion.div
     initial={{ opacity: 0, y: -8 }}
     animate={{ opacity: 1, y: 0 }}
     transition={{ delay: index * 0.08, duration: 0.3, ease: [0.16, 1, 0.3, 1] }}
   >

When to use it

Reach for this pattern on documentation sites, e-commerce category trees, SaaS dashboards with deep hierarchies, or any admin panel where users frequently need to navigate laterally within a section. Skip it for flat sites with two or three levels, a plain breadcrumb is cleaner. On mobile the dropdowns still work via tap, but make sure tap targets are at least 44px tall for comfortable use.

Used by

• Notion, Uses an inline breadcrumb with clickable parent-page dropdowns for navigating workspace hierarchies.
• Vercel, Dashboard breadcrumbs expose project and team selectors as dropdown menus for fast context switching.
• GitHub, Repository file browser uses a path breadcrumb where each segment links or branches to sibling directories.
• Linear, Issue detail breadcrumbs offer inline team and project pickers as compact dropdown overlays.

FAQ