Next-NavLink

Next-NavLink is a customizable navigation link component for Next.js applications. I know what you're thinking: "Another NavLink component?" But hear me out... this one’s different. It lets you easily create navigation links with active states, conditional classes, and yes even support for different matching modes to determine the active state, among other features.

Table of Contents

• Installation
• Usage
• Props
• Examples
• Contributing
• License

Installation

npm install next-navlink

Or, if you’re more of a yarn person:

yarn add next-navlink

Or, if you’re feeling adventurous:

bun install next-navlink

Usage

Here's a basic example of how to use the NavLink component in your Next.js project:

import React from "react";
import NavLink from "next-navlink";

const Navbar = () => {
  return (
    <nav>
      <NavLink to="/home" activeClassName="active" className="nav-link">
        Home
      </NavLink>
      <NavLink to="/about" activeClassName="active" className="nav-link">
        About
      </NavLink>
      <NavLink
        to="/contact"
        activeClassName="active"
        className="nav-link"
        redirection={false}
      >
        Contact
      </NavLink>
    </nav>
  );
};

export default Navbar;

Props

The NavLink component accepts the following props:

Prop	Type	Description	Default
children	React.ReactNode or (isActive: boolean) => React.ReactNode	The content to be rendered inside the link. It can be a React node or a function that returns a React node, allowing customization based on the active state.	-
activeClassName	string	The class name to apply when the link is active.	active
inActiveClassName	string	The class name to apply when the link is not active.	''
className	string	Additional class names to apply to the link.	''
to	string	The target path to navigate to when the link is clicked.	-
redirection	boolean	If true, the link redirects to the specified path. If false, it renders a <span> instead, disabling the navigation.	true
id	string	The id attribute to apply to the link element.	-
onClick	() => void	A function to call when the link is clicked.	-
matchMode	'exact' | 'includes' | 'startsWith'	Determines the matching behavior for the active state.	'includes'
replace	boolean	If true, replaces the current history state instead of adding a new URL to the stack.	false
scroll	boolean	If true, scrolls to the top of the page after navigation.	true
prefetch	boolean	If true, prefetches the page in the background when the link is in the viewport.	true
isExternal	boolean	If true, the link will open in a new tab and will be treated as an external link.	false
aria	{ [key: string]: string }	An object of ARIA attributes to apply to the link element.	-
testId	string	A test ID to apply to the link element for testing purposes.	-
disabled	boolean	If true, disables the link, preventing navigation and click events.	false
activeStyle	React.CSSProperties	An object containing inline styles to apply when the link is active.	-
inactiveStyle	React.CSSProperties	An object containing inline styles to apply when the link is inactive.	-
customActiveUrl	string	The link will be considered active when the current pathname matches this URL.	-

Examples

Using replace, scroll, and prefetch

Here’s how you can make the most of these props with NavLink:

<NavLink
  to="/about"
  activeClassName="active"
  className="nav-link"
  replace={true}
  scroll={false}
  prefetch={true}
>
  About Us
</NavLink>

Conditional Rendering

Want to customize the link content based on whether it’s active? Here’s how:

<NavLink to="/profile" className="nav-link">
  {(isActive) => (
    <span>{isActive ? "Your Profile (Active)" : "Your Profile"}</span>
  )}
</NavLink>

You even might want a link to be considered active based on a different URL than the one it actually points to.

Copy code
<NavLink
  to="/profile/edit"
  customActiveUrl="/profile"
  activeClassName="active"
  className="nav-link"
>
  Edit Profile
</NavLink>

Styling Links

You can style active and inactive links easily:

<NavLink
  to="/dashboard"
  activeClassName="text-bold text-primary"
  inActiveClassName="text-muted"
  className="nav-link"
>
  Dashboard
</NavLink>

Disabling Redirection

Need a link that doesn’t actually navigate for some reasons? No problem:

<NavLink to="/settings" redirection={false} className="nav-link">
  Settings
</NavLink>

Using matchMode

Exact Match

Want the link to be active only when the URL exactly matches? Use this:

<NavLink
  to="/log"
  matchMode="exact"
  activeClassName="active"
  className="nav-link"
>
  Log
</NavLink>

Starts With Match

Make the link active for any path that starts with the specified path:

<NavLink
  to="/blog"
  matchMode="startsWith"
  activeClassName="active"
  className="nav-link"
>
  Blog
</NavLink>

Includes Match (Default)

By default, NavLink matches if the path is included as a substring:

<NavLink to="/profile" activeClassName="active" className="nav-link">
  Profile
</NavLink>

Contributing

Contributions are welcome! If you have suggestions, bug reports, or feature requests, feel free to open an issue or submit a pull request.

License