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;
  }}
>

Related examples

Tab with Next.js App RouterUsing Next.js Parallel Routes to create accessible Tabs and tab panels that are rendered on the server and controlled by the URL.

Select with Next.js App RouterControlling the value of a Select component via the URL using the Next.js App Router and React.useOptimistic to ensure a responsive and accessible UI.

Dialog with React RouterUsing React Router to create a modal Dialog that's controlled by the browser history.

Dialog with MenuShowing a nested dropdown Menu component inside a modal Dialog using React.

Nested DialogRendering a modal Dialog to confirm an action inside another modal dialog using React.

Warning on Dialog hidePreventing users from accidentally closing a modal Dialog component with unsaved changes by displaying a nested confirmation dialog.

View all examples

Dialog with Next.js App Router

Components

Controlling the Dialog state

Restoring focus on hide

Stay tuned