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:

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.

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.

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`

Add Provider to Root

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

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.

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

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.

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

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:

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.

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.

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.

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