NavPlus

A flexible, accessible, and framework-agnostic navigation link component for React.

Table of Contents

• NavPlus
  • Table of Contents
  • Features
  • Installation
  • Quick Start
    • 1. Basic Usage
    • 2. RouterNavLink Wrapper
    • 3. Prefetch on Hover
    • 4. Custom Rendering & Triggers
  • API
    • <NavPlus> Props
      • PrefetchOptions
  • Usage Tips
  • Contributing
  • License

Features

• Active-state detection
  • exact, startsWith, includes, or custom regex (pattern)
  • Override with your own isActiveFunc or customActiveUrl
• Prefetching support
  • Hover-triggered prefetch with configurable delay
  • Works with React Router, TanStack Router, Wouter, or your own custom prefetcher
• Flexible rendering
  • Renders a React Router <Link>, a plain <a>, a <span>, or any custom element via as
  • Fully controllable redirection (redirection), replace vs push (replace), and navigation delay
• External & disabled links
  • isExternal → <a target="_blank" rel="noopener noreferrer">
  • disabled → renders a <span> with aria-disabled
• Styling & class names
  • className, activeClassName, inActiveClassName
  • activeStyle, inactiveStyle
• Dynamic children
  • Render static React nodes or pass a function (isActive) => ReactNode
• Accessibility
  • Custom ARIA attributes via aria prop
  • Automatically applies aria-current="page" and aria-disabled
• Test-friendly
  • data-testid support for easy querying in Jest, React Testing Library, Cypress, etc.
• Lightweight & Tree-shakable
  • Written in TypeScript, no runtime dependencies beyond React

Installation

Using npm:

npm install react-navplus

Using Yarn:

yarn add react-navplus

Using Bun:

bun add react-navplus

Quick Start

1. Basic Usage

import React from 'react';
import { NavPlus } from 'react-navplus';

const Nav = () => (
  <nav>
    <NavPlus to="/home">Home</NavPlus>
    <NavPlus to="/about" matchMode="exact">
      About
    </NavPlus>
    <NavPlus to="https://example.com" isExternal>
      External Site
    </NavPlus>
  </nav>
);

2. RouterNavLink Wrapper

If you’re using React Router v6, you can skip passing in location and navigate by using the built-in wrapper:

import React from 'react';
import { RouterNavLink } from 'react-navplus';

const Nav = () => (
  <nav>
    <RouterNavLink to="/dashboard" activeClassName="active">
      Dashboard
    </RouterNavLink>
  </nav>
);

3. Prefetch on Hover

<RouterNavLink
  to="/products"
  prefetch={{ enabled: true, delay: 150, routerType: 'tanstack-router' }}
>
  Products
</RouterNavLink>

4. Custom Rendering & Triggers

<RouterNavLink
  to="/settings"
  as="button"
  triggerEvent="hover"
  navigationDelay={300}
>
  {(isActive) => (isActive ? <strong>Settings</strong> : <span>Settings</span>)}
</RouterNavLink>

API

<NavPlus> Props

| Prop | Type | Default | Description | | ------------------- | ---------------------------------------------------------- | ------------ | ------------------------------------------------------------------------------------------- | | to | string | — | Required. Target URL or path. | | children | ReactNode | (isActive: boolean) => ReactNode | — | Content inside the link. Can be a React node or a render function that receives isActive. | | location | { pathname: string } | undefined | Current location (e.g. from useLocation()). If omitted, link is never active. | | navigate | (to: string, options?: { replace?: boolean }) => void | undefined | Navigation function (e.g. from useNavigate()). If omitted, behaves like a plain <a>. | | matchMode | 'exact' | 'startsWith' | 'includes' | 'pattern' | 'includes' | How to match location.pathname against to (pattern uses matchPattern). | | matchPattern | RegExp | undefined | Custom regex to match against current pathname (only when matchMode="pattern"). | | customActiveUrl | string | undefined | Use a different URL for active detection instead of to. | | isActiveFunc | (pathname: string, to: string) => boolean | undefined | Fully custom active-detection function. | | prefetch | boolean | PrefetchOptions | false | Enable hover-prefetch. See PrefetchOptions below. | | redirection | boolean | true | If false, renders a <span> and no navigation occurs. | | replace | boolean | false | If true, navigation uses history.replace instead of push. | | navigationDelay | number (ms) | undefined | Delay before performing navigation (useful for animations). | | triggerEvent | 'click' | 'hover' | 'click' | Which event triggers navigation. | | isExternal | boolean | false | Render as external link (<a target="_blank" rel="noopener noreferrer">). | | disabled | boolean | false | Render as a disabled <span> with aria-disabled. | | as | React.ElementType | undefined | Custom element or component to render instead of <Link>/<a>/<span>. | | className | string | '' | Base class(es) applied to the link. | | activeClassName | string | 'active' | Class applied when link is active. | | inActiveClassName | string | '' | Class applied when link is not active. | | activeStyle | React.CSSProperties | undefined | Inline style when active. | | inactiveStyle | React.CSSProperties | undefined | Inline style when inactive. | | id | string | undefined | id attribute on the rendered element. | | aria | React.AriaAttributes | {} | Additional ARIA attributes. | | testId | string | undefined | data-testid for automated tests. | | linkProps | Omit<LinkProps, 'to' | 'replace'> | {} | Extra props to pass down when using React Router’s <Link>. | | routerContext | any | undefined | Pass in your own router context ({ navigate, router }) for custom integrations. |

PrefetchOptions

interface PrefetchOptions {
  enabled?: boolean; // default: true
  delay?: number; // ms, default: 200
  routerType?: 'react-router' | 'tanstack-router' | 'wouter' | 'custom'; // default: 'react-router'
  customPrefetch?: (to: string) => void;
}

Usage Tips

• Custom matching: Use

  matchMode="pattern"
  matchPattern={/^\/blog(\/|$)/}

  for advanced route matching.

• Custom elements: Pass as="button" or your own styled component to match your design system.

• Global context: The optional NavContext in src/context/NavContext.tsx can share navigation state or prefetch logic.

• Standalone hooks: We expose useIsActive and usePrefetch in src/hooks/ if you need the logic outside of the component.

Contributing

1. Fork the repo
2. Create your feature branch (git checkout -b feature/foo)
3. Commit your changes (git commit -am 'Add foo')
4. Push to the branch (git push origin feature/foo)
5. Open a Pull Request

Please run npm test and npm run lint before submitting.

License

MIT © [Your Name or Organization] See LICENSE for details.