Skip to main content

RouterNavLink

export interface RouterNavLinkProps extends Omit<RouterLinkProps, 'className' | 'style'> {
    activeClassName?: string;
    className?: string | ActiveModifier<string>;
    exact?: boolean;
    isActive?: (currentPathname: string, linkPathname: string) => boolean;
    preload?: PreloadTrigger;
    style?: CSSProperties | ActiveModifier<CSSProperties>;
}

type ActiveModifier<T> = ({ isActive }: { isActive: boolean }) => T;

type PreloadTrigger = 'hover' | 'click' | 'idle';

A <RouterNavLink> is a special kind of <RouterLink> that knows whether or not it is "active". This is useful when building a navigation menu, such as a breadcrumb or a set of tabs where you'd like to show which of them is currently selected. It also provides useful context for assistive technology like screen readers.

import { RouterNavLink } from '@archibald/core';

<RouterNavLink to="/messages" activeClassName="active">
    Messages
</RouterNavLink>;

className​

The className prop works like a normal className, but you can also pass it a function to customize the classNames applied based on the active state of the link.

<NavLink to="/messages" className={({ isActive }) => (isActive ? 'active' : '')}>
    Messages
</NavLink>

style​

The style prop works like a normal style prop, but you can also pass it a function to customize the styles applied based on the active state of the link.

<NavLink
    to="/messages"
    style={({ isActive }) => ({
        fontWeight: isActive ? 'bold' : '',
        color: isActive ? 'red' : 'black'
    })}
>
    Messages
</NavLink>

exact​

The exact prop changes the matching logic for the active state to fully match to the RouterNavLink's rendered href. If the URL is longer than that, it will no longer be considered active.

<RouterNavLink to="/" exact>
    Home
</RouterNavLink>

In order to mark <RouterNavLink> active current pathname is compared to the one <RouterNavLink> points at. To define active state it uses useIsLinkActive hook.

aria-current​

When a RouterNavLink is active it will automatically apply <a aria-current="page"> to the underlying anchor tag. See aria-current on MDN.

preload​

The preload prop prerenders the linked route ahead of navigation so that, when the user follows the link, its lazy chunk and data are already loaded. It accepts one of three triggers:

ValueWarms the route when…
'hover'the user hovers (or focuses) the link
'click'the user presses down on the link
'idle'the link mounts and the browser is idle
<RouterNavLink to="/wishlist" preload="hover">
    Wishlist
</RouterNavLink>

Preloading is handled by the SuspenseRouter. What it does depends on the app.router.prerender strategy: 'dom' warms the route in a hidden container and then retires it, 'data' warms its data and code chunk only, 'off' does nothing. Omit preload (the default) to disable prerendering for a link.

prefetch​

RouterNavLink also accepts the prefetch prop from RouterLink ('intent' | 'render' | 'none', default 'none'). It warms the target route's data and code chunk ahead of navigation.

This is distinct from preload: under the default 'dom' strategy preload prerenders the route in a hidden container (heavier, DOM-level), while prefetch only warms data and lazy chunks (lighter). Under app.router.prerender: 'data' the two do the same work, differing only in their triggers. For a lazy route, prefetch="intent" is usually the right choice.

<RouterNavLink to="/wishlist" prefetch="intent">
    Wishlist
</RouterNavLink>

reloadDocument​

The reloadDocument property can be used to skip client side routing and let the browser handle the transition normally (as if it were an <a href>).