All components (204)

Routing

More · RouterProvider

What it is and when to use it

Takes the library's links (Link, ButtonLink, the breadcrumbs, the side menu, the title of a card with href) through the application's router: the click navigates without reloading the page and, if the router knows how to prefetch, the destination is requested before pressing. Without a provider, each link is a real <a href> and each click reloads the whole page: it works, but it is not what is expected of an application.

In Next you do not have to write the bridge. Two ready-made providers, placed once at the top of the tree:

// App Router (layout or client provider)
import { NextRouterProvider } from '@amset/ui/next'

// Pages Router (pages/_app)
import { NextPagesRouterProvider } from '@amset/ui/next/pages'

They navigate with router.push and prefetch with router.prefetch on hover or focus, like next/link. next is an optional dependency: whoever does not import those two subpaths loads nothing from Next, and in plain React the main package does not know it exists.

In React Router, Vite or any other router, the generic provider:

import { RouterProvider } from '@amset/ui'

const navigate = useNavigate()
<RouterProvider navigate={(href) => { navigate(href) }}>…</RouterProvider>

When to use it

Once, at the top of the tree, in any application with client-side routing.
prefetch is optional: if the router does not know how to prefetch, it is not passed and nothing happens. It is called once per destination.

When not to

It is not needed for a destination that leaves the application: another domain, mailto:, tel:, a download or a target of its own are resolved by the browser and the provider does not touch them.
A button that does not change place is not a link: Button.

Keyboard: it has none, it is a provider. With Control, Cmd, Shift or the middle button the link opens in another tab, like any link: the provider does not step in.

Accessibility: it changes nothing of what the reader announces: it is still an <a href> and it says "link". Copying the address, opening in another tab and the browser menus keep working.

Fine-tuning: it draws nothing.

What it looks like

This link does not reload the page: go to Button

You have not pressed the link yet.

<RouterProvider navigate={(href) => router.push(href)}>
  <Link href="/componentes/button/">go to Button</Link>
</RouterProvider>

Props

Import it with import { RouterProvider } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`children`required	`ReactNode`	—
`navigate`required	`(href: string) => void`	Takes you to that address without reloading the page. It is given the `href` exactly as written in the link: Next's `router.push`, React Router's `navigate` or whatever the project uses.
`prefetch`	`(href: string) => void`	Requests in advance what that destination needs, so the click is instant: Next's `router.prefetch`. It is optional; it is called once per destination when the mouse hovers over the link or it receives focus, which is when `next/link` starts loading its own on a link without `prefetch`.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: