Routing

NextUI Components such as Tabs, Listbox, Dropdown and many others offer the flexibility to be rendered as HTML links.

Introduction

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 NextUIProvider component configures all NextUI components within it to navigate using the client side router you provide.

Set this up once in the root of your app, and any NextUI component with the href prop will automatically navigate using your router.

The NextUIProvider component accepts navigate and useHref props. navigate is a router function for client-side navigation, while useHref optionally converts router hrefs to native HTML hrefs. Here's the pattern:

import * as React from "react";

import {NextUIProvider} from "@nextui-org/react";
import {useNavigate, useHref} from "your-router";

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

  return (
    <NextUIProvider navigate={navigate} useHref={useHref}>
      <YourApplication />
    </NextUIProvider>
  );
}

Note: Framework-specific examples are shown below.

Router Options

All NextUI link components accept a routerOptions prop that passes options to the router's navigate function for controlling behavior like scrolling and history navigation.

<DropdownItem href="/login" routerOptions={{replace: true}}>
  {/* ...*/}
</DropdownItem>

When using TypeScript, you can configure the RouterConfig type globally so that all link components have auto complete and type safety using a type provided by your router.

import type {RouterOptions} from "your-router";

declare module "@react-types/shared" {
  interface RouterConfig {
    routerOptions: RouterOptions;
  }
}

Next.js

App Router

Go to your app/providers.tsx or app/providers.jsx (create it if it doesn't exist) and add the useRouter hook from next/navigation, it returns a router object that can be used to perform navigation.

Check the Next.js docs for more details.

Add the `useRouter`

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

import {useRouter} from "next/navigation";
import {NextUIProvider} from "@nextui-org/react";

// Only if using TypeScript
declare module "@react-types/shared" {
  interface RouterConfig {
    routerOptions: NonNullable<Parameters<ReturnType<typeof useRouter>["push"]>[1]>;
  }
}

export function Providers({children}: {children: React.ReactNode}) {
  const router = useRouter();

  return <NextUIProvider navigate={router.push}>{children}</NextUIProvider>;
}

Add Provider to Root

Now, Go to your root layout page and wrap it with the NextUIProvider:

// app/layout.tsx
import {Providers} from "./providers";

export default function RootLayout({children}: {children: React.ReactNode}) {
  return (
    <html lang="en" className="dark">
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Note: Skip this step if you already set up the NextUIProvider in your app.

Next.js Base Path (Optional)

If you are using the Next.js basePath setting, you'll need to configure an environment variable to access it.

// next.config.js
const basePath = "...";
const nextConfig = {
  basePath,
  env: {
    BASE_PATH: basePath,
  },
};

Then, provide a custom useHref function to prepend it to the href for all links.

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

import {useRouter} from "next/navigation";
import {NextUIProvider} from "@nextui-org/react";

export function Providers({children}: {children: React.ReactNode}) {
  const router = useRouter();
  const useHref = (href: string) => process.env.BASE_PATH + href;

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

Pages Router

Go to pages/_app.js or pages/_app.tsx (create it if it doesn't exist) and add theuseRouter hook from next/router, it returns a router object that can be used to perform navigation.

// pages/_app.tsx
import type {AppProps} from "next/app";
import {type NextRouter, useRouter} from "next/router";
import {NextUIProvider} from "@nextui-org/react";

declare module "@react-types/shared" {
  interface RouterConfig {
    routerOptions: NonNullable<
      Parameters<NextRouter['push']>[2]
    >;
  }
}

function MyApp({Component, pageProps}: AppProps) {
  const router = useRouter();

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

export default MyApp;

When using the basePath configuration option, provide a useHref option to the router passed to Provider to prepend it to links automatically.

// pages/_app.tsx
import type {AppProps} from "next/app";
import {NextUIProvider} from "@nextui-org/react";
import {useRouter} from "next/router";

function MyApp({Component, pageProps}: AppProps) {
  const router = useRouter();
  const useHref = (href: string) => router.basePath + href;

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

export default MyApp;

React Router

Use the useNavigate hook from react-router-dom to get the navigate function for routing. The useHref hook can be used with React Router's basename option.

Make sure to place the component using these hooks inside BrowserRouter and keep <Routes> within NextUIProvider. Here's how to set it up in your App component:

// App.tsx or App.jsx
import type {NavigateOptions} from "react-router-dom";

import {BrowserRouter, useNavigate, useHref} from "react-router-dom";
import {NextUIProvider} from "@nextui-org/react";

declare module "@react-types/shared" {
  interface RouterConfig {
    routerOptions: NavigateOptions;
  }
}

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

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

// main.tsx or main.jsx
ReactDOM.createRoot(document.getElementById("root")).render(
  <React.StrictMode>
    <BrowserRouter>
      <App />
    </BrowserRouter>
  </React.StrictMode>,
);

Ensure that the component that calls useNavigate and renders NextUIProvider 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 NextUIProvider so that links inside the rendered routes have access to the router.

Remix

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

// app/root.tsx
import type {NavigateOptions} from 'react-router-dom';

import {useNavigate, useHref, Outlet} from "@remix-run/react";
import {NextUIProvider} from "@nextui-org/react";

declare module "@react-types/shared" {
  interface RouterConfig {
    routerOptions: NavigateOptions;
  }
}

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

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

TanStack

To use TanStack Router with NextUI, render NextUI's RouterProvider inside your root route. Use router.navigate in the navigate prop, and router.buildLocation in the useHref prop.

// app/root.tsx
import type {NavigateOptions, ToOptions} from '@tanstack/react-router';

import {useRouter} from '@tanstack/react-router';
import {NextUIProvider} from "@nextui-org/react";


declare module "@react-types/shared" {
  interface RouterConfig {
    href: ToOptions['to'];
    routerOptions: Omit<NavigateOptions, keyof ToOptions>;
  }
}

function RootRoute() {
  let router = useRouter();

  return (
    <NextUIProvider
      navigate={(to, options) => router.navigate({to, ...options})}
      useHref={(to) => router.buildLocation({to}).href}
    >
      {/* You app here... */}
    </NextUIProvider>
  );
}

Usage examples

Now that you have set up the NextUIProvider in your app, you can use the href prop in the Tabs, Listbox and Dropdown items to navigate between pages.

The Link component will also use the navigate function from the NextUIProvider to navigate between pages.

import {  Tabs,
  Tab,
  Listbox,
  ListboxItem,
  Dropdown,
  DropdownTrigger,
  DropdownMenu,
  DropdownItem,
  Button,
  Link,} from "@nextui-org/react";
  Tabs,
  Tab,
  Listbox,
  ListboxItem,
  Dropdown,
  DropdownTrigger,
  DropdownMenu,
  DropdownItem,
  Button,
  Link,
} from "@nextui-org/react";

function App() {
  return (
    <>
      <Tabs aria-label="Navigation">
        <Tab key="home" href="/home">
          Home
        </Tab>
        <Tab key="about" href="/about">
          About
        </Tab>
      </Tabs>
      <Listbox aria-label="Navigation">
        <ListboxItem key="home" href="/home">
          Home
        </ListboxItem>
        <ListboxItem key="about" href="/about">
          About
        </ListboxItem>
      </Listbox>
      <Dropdown>
        <DropdownTrigger>
          <Button>Open</Button>
        </DropdownTrigger>
        <DropdownMenu aria-label="Navigation">
          <DropdownItem key="home" href="/home">
            Home
          </DropdownItem>
          <DropdownItem key="about" href="/about">
            About
          </DropdownItem>
        </DropdownMenu>
      </Dropdown>
      <Link href="/home">Home</Link>
      <Link href="/about">About</Link>
    </>
  );
}

For more information about routing in React Aria, visit the React Aria Routing Guide.