Client Side Routing

Many React Aria components support rendering as HTML links. This page discusses how to set up your app to integrate React Aria links with your framework or client side router.

Introduction#

React Aria components such as Link, Menu, Tabs, Table, and many others support rendering elements as links that perform navigation when the user interacts with them. Each component that supports link behavior accepts the href prop, which causes the component to render an <a> element. Other link DOM props such as target and download are also supported.

Depending on the component, users may interact with links in different ways. For example, users can navigate between tabs using the arrow keys, or open a link in a ComboBox using the enter key. Because React Aria components accept the href prop rather than supporting arbitrary element overrides, they can ensure that link navigation occurs when it is appropriate for the component.

By default, links perform native browser navigation when they are interacted with. However, many apps and frameworks use client side routers to avoid a full page reload when navigating between pages. The RouterProvider component configures all React Aria components within it to navigate using the client side router you provide. Set this up once in the root of your app, and any React Aria component with the href prop will automatically navigate using your router.

Note that external links to different origins will not trigger client side routing, and will use native browser navigation. Additionally, if the link has a target other than "_self", uses the download attribute, or the user presses modifier keys such as Command or Alt to change the default behavior, browser native navigation will occur instead of client side routing.

RouterProvider#

The RouterProvider component accepts a single prop: navigate. This should be set to a function received from your router for performing a client side navigation programmatically. The following example shows the general pattern. Framework-specific examples are shown below.

import {RouterProvider} from 'react-aria-components';

function App() {
  let navigate = useNavigateFromYourRouter();

  return (
    <RouterProvider navigate={navigate}>
      {/* ... */}
    </RouterProvider>
  );
}

import {RouterProvider} from 'react-aria-components';

function App() {
  let navigate = useNavigateFromYourRouter();

  return (
    <RouterProvider navigate={navigate}>
      {/* ... */}
    </RouterProvider>
  );
}

import {RouterProvider} from 'react-aria-components';

function App() {
  let navigate =
    useNavigateFromYourRouter();

  return (
    <RouterProvider
      navigate={navigate}
    >
      {/* ... */}
    </RouterProvider>
  );
}

Note: if you are using React Aria hooks rather than components, you can import RouterProvider from react-aria instead.

React Router#

The useNavigate hook from react-router-dom returns a navigate function you can pass to RouterProvider. Ensure that the component that calls useNavigate and renders RouterProvider is inside the router component (e.g. BrowserRouter) so that it has access to React Router's internal context. The React Router <Routes> element should also be defined inside React Aria's <RouterProvider> so that links inside the rendered routes have access to the router.

import {BrowserRouter, useNavigate} from 'react-router-dom';
import {RouterProvider} from 'react-aria-components';

function App() {
  let navigate = useNavigate();

  return (
    <RouterProvider navigate={navigate}>
      {/* Your app here... */}
      <Routes>
        <Route path="/" element={<HomePage />} />
        {/* ... */}
      </Routes>
    </RouterProvider>
  );
}

<BrowserRouter>
  <App />
</BrowserRouter>

import {BrowserRouter, useNavigate} from 'react-router-dom';
import {RouterProvider} from 'react-aria-components';

function App() {
  let navigate = useNavigate();

  return (
    <RouterProvider navigate={navigate}>
      {/* Your app here... */}
      <Routes>
        <Route path="/" element={<HomePage />} />
        {/* ... */}
      </Routes>
    </RouterProvider>
  );
}

<BrowserRouter>
  <App />
</BrowserRouter>

import {
  BrowserRouter,
  useNavigate
} from 'react-router-dom';
import {RouterProvider} from 'react-aria-components';

function App() {
  let navigate =
    useNavigate();

  return (
    <RouterProvider
      navigate={navigate}
    >
      {/* Your app here... */}
      <Routes>
        <Route
          path="/"
          element={
            <HomePage />
          }
        />
        {/* ... */}
      </Routes>
    </RouterProvider>
  );
}

<BrowserRouter>
  <App />
</BrowserRouter>

Next.js#

App router#

The useRouter hook from next/navigation returns a router object that can be used to perform navigation. RouterProvider should be rendered from a client component at the root of each page or layout that includes React Aria links. You can create a new client component for this, or combine it with other top-level providers as described in the Next.js docs.

// app/provider.tsx
"use client";

import {useRouter} from 'next/navigation';
import {RouterProvider} from 'react-aria-components';

export function ClientProviders({children}) {
  let router = useRouter();

  return (
    <RouterProvider navigate={router.push}>
      {children}
    </RouterProvider>
  );
}

// app/provider.tsx
"use client";

import {useRouter} from 'next/navigation';
import {RouterProvider} from 'react-aria-components';

export function ClientProviders({children}) {
  let router = useRouter();

  return (
    <RouterProvider navigate={router.push}>
      {children}
    </RouterProvider>
  );
}

// app/provider.tsx
'use client';

import {useRouter} from 'next/navigation';
import {RouterProvider} from 'react-aria-components';

export function ClientProviders(
  { children }
) {
  let router =
    useRouter();

  return (
    <RouterProvider
      navigate={router
        .push}
    >
      {children}
    </RouterProvider>
  );
}

Then, in your page or layout server component, wrap your app in the ClientProviders component that you defined.

// app/layout.tsx
import {ClientProviders} from './provider';

export default function RootLayout({children}) {
  return (
    <html>
      <body>
        <ClientProviders>{children}</ClientProviders>
      </body>
    </html>
  );
}

// app/layout.tsx
import {ClientProviders} from './provider';

export default function RootLayout({children}) {
  return (
    <html>
      <body>
        <ClientProviders>{children}</ClientProviders>
      </body>
    </html>
  );
}

// app/layout.tsx
import {ClientProviders} from './provider';

export default function RootLayout(
  { children }
) {
  return (
    <html>
      <body>
        <ClientProviders>
          {children}
        </ClientProviders>
      </body>
    </html>
  );
}

Pages router#

The useRouter hook from next/router returns a router object that can be used to perform navigation. RouterProvider should be rendered at the root of each page that includes React Aria links, or in pages/_app.tsx to add it to all pages.

// pages/_app.tsx
import type { AppProps } from 'next/app';
import {useRouter} from 'next/router';
import {RouterProvider} from 'react-aria-components';

export default function MyApp({Component, pageProps}: AppProps) {
  let router = useRouter();

  return (
    <RouterProvider navigate={router.push}>
      <Component {...pageProps} />
    </RouterProvider>
  );
}

// pages/_app.tsx
import type {AppProps} from 'next/app';
import {useRouter} from 'next/router';
import {RouterProvider} from 'react-aria-components';

export default function MyApp(
  { Component, pageProps }: AppProps
) {
  let router = useRouter();

  return (
    <RouterProvider navigate={router.push}>
      <Component {...pageProps} />
    </RouterProvider>
  );
}

// pages/_app.tsx
import type {AppProps} from 'next/app';
import {useRouter} from 'next/router';
import {RouterProvider} from 'react-aria-components';

export default function MyApp(
  {
    Component,
    pageProps
  }: AppProps
) {
  let router =
    useRouter();

  return (
    <RouterProvider
      navigate={router
        .push}
    >
      <Component
        {...pageProps}
      />
    </RouterProvider>
  );
}

Remix#

Remix uses React Router under the hood, so the same useNavigate hook described above also works in Remix apps. RouterProvider should be rendered at the root of each page that includes React Aria links, or in app/root.tsx to add it to all pages. See the Remix docs for more details.

// app/root.tsx
import {useNavigate, Outlet} from '@remix-run/react';
import {RouterProvider} from 'react-aria-components';

export default function App() {
  let navigate = useNavigate();

  return (
    <html lang="en">
      <head>
        {/* ... */}
      </head>
      <body>
        <RouterProvider navigate={navigate}>
          <Outlet />
        </RouterProvider>
        {/* ... */}
      </body>
    </html>
  );
}

// app/root.tsx
import {useNavigate, Outlet} from '@remix-run/react';
import {RouterProvider} from 'react-aria-components';

export default function App() {
  let navigate = useNavigate();

  return (
    <html lang="en">
      <head>
        {/* ... */}
      </head>
      <body>
        <RouterProvider navigate={navigate}>
          <Outlet />
        </RouterProvider>
        {/* ... */}
      </body>
    </html>
  );
}

// app/root.tsx
import {
  Outlet,
  useNavigate
} from '@remix-run/react';
import {RouterProvider} from 'react-aria-components';

export default function App() {
  let navigate =
    useNavigate();

  return (
    <html lang="en">
      <head>
        {/* ... */}
      </head>
      <body>
        <RouterProvider
          navigate={navigate}
        >
          <Outlet />
        </RouterProvider>
        {/* ... */}
      </body>
    </html>
  );
}