Recommended pattern for Base UI Drawer with Next.js Intercepting Routes: exit animations and scroll restoration

[alekseykurylev]

Hi! What is the recommended way to use the Base UI version of shadcn Drawer with Next.js Parallel Routes and Intercepting Routes?

The basic routing works, but coordinating the drawer’s animation lifecycle with navigation and scroll restoration has been tricky.

Use case

A product opens in a drawer above the catalog through client-side navigation. Opening the same URL directly or refreshing renders a full product page.

app/
├── layout.tsx
├── page.tsx
├── products/[slug]/page.tsx
└── @modal/
    ├── default.tsx          // returns null
    ├── page.tsx             // returns null
    ├── [...catchAll]/page.tsx // returns null
    └── (.)products/[slug]/page.tsx

The layout renders {children} and {modal}. The intercepted page wraps server-rendered product content in a client drawer component.

Environment

• Next.js 16.4.5, App Router
• React 19.3.1
• @base-ui/react 1.9.0
• Tailwind CSS 4
  This concerns the Base UI Drawer, not the Vaul version.

Current implementation

"use client"

import { useRouter } from "next/navigation"
import { useEffect, useState, type ReactNode } from "react"

import { Drawer, DrawerContent } from "@/components/ui/drawer"
import { ScrollArea } from "@/components/ui/scroll-area"

export function ProductDrawer({ children }: { children: ReactNode }) {
  const router = useRouter()
  const [open, setOpen] = useState(false)

  useEffect(() => {
    const frame = requestAnimationFrame(() => setOpen(true))
    return () => cancelAnimationFrame(frame)
  }, [])

  return (
    <Drawer
      open={open}
      onOpenChange={setOpen}
      onOpenChangeComplete={(isOpen) => {
        if (!isOpen) router.back()
      }}
    >
      <DrawerContent className="h-[calc(100dvh-6rem)]">
        <ScrollArea className="min-h-0 flex-1">
          <div className="flex min-h-full flex-col p-4">
            {children}
          </div>
        </ScrollArea>
      </DrawerContent>
    </Drawer>
  )
}

Mounting the drawer closed and then opening it allows the entrance transition to run. Calling router.back() after onOpenChangeComplete(false) allows the exit animation to finish before the route unmounts.

The remaining problem: scrolling during dismissal

There seems to be a gap between scroll unlocking and history navigation:

1. Open a product while the catalog is scrolled to 900px.
2. Dismiss the drawer.
3. While the exit animation is finishing, start scrolling the catalog.
4. The catalog reaches, for example, 1100px.
5. onOpenChangeComplete(false) calls router.back().
6. The page jumps back to 900px.
   This was reproduced in Chromium. Temporarily setting history.scrollRestoration = "manual" in an isolated test prevented the jump: the page remained at 1100px.

However, that property affects document history globally, so I’m unsure whether managing it around drawer dismissal is the right integration strategy.

I also tried modal="trap-focus". It removes scroll locking, but the subsequent Back navigation still restores the previous position. In my local shadcn wrapper, the backdrop also disappears because it is only rendered when modal === true.

Questions

1. Is setOpen(false) → onOpenChangeComplete(false) → router.back() the recommended pattern for an intercepted Drawer?
2. Should background scrolling remain locked throughout the exit animation and until navigation completes? Is there a supported way to achieve this with Base UI?
3. If background scrolling is intentionally allowed with modal="trap-focus", how should scroll restoration be handled when closing via Back?
4. Is it preferable to keep Drawer.Root in a persistent layout and pass the parallel slot as its children? How should content remain visible during exit when the slot switches to a page returning null?
   I understand that browser Back can unmount the intercepted route immediately. I’m mainly looking for a reliable pattern for UI-initiated dismissal—swipe, outside press, Escape, or a close button—while preserving the expected browser history behavior.

A small official example covering these interactions would be very helpful.

[amartya1523]

Short answers in order:

1. setOpen(false) → onOpenChangeComplete(false) → router.back(): yes, that's the right shape for UI-initiated dismissal. The popup stays mounted through the exit animation and onOpenChangeComplete only fires once it has finished, so navigating there is what keeps the animation intact. Browser Back is the case where the route unmounts first and you just don't get an exit animation. That's fine, and nothing calls router.back() twice because the component is already gone.

2. Scroll lock during the exit: there's no prop for it. In Base UI the lock is literally

// packages/react/src/dialog/root/useDialogRoot.ts
useScrollLock(open && modal === true, popupElement);

so it's released the moment open flips to false, at the start of the exit animation rather than the end. That's why the page under the drawer becomes scrollable while it slides out.

One way around it is to take a second lock that I hold until the route actually unmounts. The locker is a ref-counted singleton, so two holders don't fight:

import { useScrollLock } from "@base-ui/utils/useScrollLock"

export function ProductDrawer({ children }: { children: ReactNode }) {
  const router = useRouter()
  const [open, setOpen] = useState(false)
  const [closing, setClosing] = useState(false)

  // stays locked from open until this component unmounts after router.back()
  useScrollLock(open || closing)

  useEffect(() => {
    const frame = requestAnimationFrame(() => setOpen(true))
    return () => cancelAnimationFrame(frame)
  }, [])

  return (
    <Drawer
      open={open}
      onOpenChange={(next) => {
        if (!next) setClosing(true)
        setOpen(next)
      }}
      onOpenChangeComplete={(isOpen) => {
        if (!isOpen) router.back()
      }}
    >
      {/* ... */}
    </Drawer>
  )
}

@base-ui/utils is the package @base-ui/react itself depends on (exports: "./*"), but it's not the documented public API, so pin it to the same version as @base-ui/react. If you'd rather not depend on it, toggling overflow: hidden on <html> in the same open || closing effect does the same job, minus the scrollbar-gutter handling.

3. modal="trap-focus" and scroll restoration: I'd avoid it here. With the page scrollable underneath, the user scrolls the catalog, then router.back() restores the scroll position Next saved when the product was pushed, so the page jumps back. Keeping modal={true} plus the lock above means the position can't drift, and Back has nothing to "restore". (The disappearing backdrop is just your wrapper only rendering <DrawerBackdrop> when modal === true; render it unconditionally if you keep trap-focus.)

4. Drawer.Root in the layout: only worth it if you want exit animations on browser Back too. The catch is exactly what you noticed: once the slot resolves to default.tsx (null), the content is gone mid-animation. You'd have to cache the last non-null slot children in a ref and keep rendering those until onOpenChangeComplete(false). It works, but it's a fair bit of extra state for one animation. For UI-initiated close, keeping the root inside the intercepted page like you have now is simpler and behaves correctly.