Dialog with Next.js App Router

Using Next.js Parallel Routes⁠ to create an accessible modal Dialog that is rendered on the server and controlled by the URL, with built-in focus management.

Dialog Routing Next.js Next.js App Router

Edit example

12345678910
import Link from "next/link.js";

export default function Page() {
  return (
    <Link href="/previews/dialog-next-router/login" className="button">
      Login
    </Link>
  );
}

import Link from "next/link.js";

export default function Page() {
  return (
    <Link href="/previews/dialog-next-router/login" className="button">
      Login
    </Link>
  );
}

Components

DialogOpen a new window that can be either modal or non-modal and optionally rendered in a React portal. This component is based on the WAI-ARIA Dialog Pattern.

View all components

To control the open state, you can pass the open and onClose props to the Dialog component. These props allow you to synchronize the dialog state with other state sources, such as the browser history.

In this example, since the dialog is only rendered when the route matches, we can pass open={true} to the Dialog component so that the dialog is always open. Then, we can use onClose to navigate back when the dialog is closed:

const router = useRouter();

<Dialog open onClose={() => router.push("/previews/dialog-next-router")}>
const router = useRouter();

<Dialog open onClose={() => router.push("/previews/dialog-next-router")}>

Restoring focus on hide

When the dialog is closed, the focus is automatically returned to the element that was previously focused before opening the dialog. Typically, this is the element that triggered the dialog. However, in cases where a user navigates to the modal URL directly, there is no element to focus on hide.

To handle this scenario, the autoFocusOnHide prop can be used to specify a fallback element to focus on hide:

const pathname = usePathname();

<Dialog
  autoFocusOnHide={(element) => {
    if (!element) {
      document.querySelector(`[href="${pathname}"]`)?.focus();
    }
    return true;
  }}
>
const pathname = usePathname();

<Dialog
  autoFocusOnHide={(element) => {
    if (!element) {
      document.querySelector(`[href="${pathname}"]`)?.focus();
    }
    return true;
  }}
>