@navojs/react-router

React Router integration for Navo — declarative navigation and permission-based routing.

Installation

npm install @navojs/react-router react-router

Quick Start

1. Define your navigation structure

import { createNavo } from '@navojs/react-router'

const navo = createNavo([
  { id: 'dashboard', label: 'Dashboard', path: '/dashboard' },
  {
    id: 'users',
    label: 'Users',
    path: '/users',
    children: [
      { id: 'user-list', label: 'User List', path: 'list' },
      { id: 'user-detail', label: 'User Detail', path: ':id', affiliated: true },
    ],
  },
  { id: 'settings', label: 'Settings', path: '/settings' },
])

2. Wrap your app with NavoProvider

import { NavoProvider } from '@navojs/react-router'
import { BrowserRouter } from 'react-router'

function App() {
  return (
    <BrowserRouter>
      <NavoProvider navo={navo}>
        <AppRoutes />
      </NavoProvider>
    </BrowserRouter>
  )
}

3. Generate routes from your navo structure

import { generateRoutes } from '@navojs/react-router'
import { useRoutes } from 'react-router'

function AppRoutes() {
  const routes = generateRoutes(navo)
  return useRoutes(routes)
}

Permission Control

import { useCanAccess } from '@navojs/react-router'

function PermissionGate() {
  const onCanAccess = useCanAccess()

  useEffect(() => {
    // Provide your access control logic
    onCanAccess((node) => {
      return userPermissions.includes(node.id)
    })
  }, [])

  return null
}

Hooks

useCanAccess()

Returns the onCanAccess callback for setting up permission checks.

useCanAccessPage()

Returns a boolean indicating whether the current page is authorized. Use this for route guards.

const canAccess = useCanAccessPage()
if (!canAccess) return <UnauthorizedPage />

useMatchedNodes()

Returns the currently active navigation nodes and their IDs — useful for highlighting menus and breadcrumbs.

const { matchedNodes, matchedIds } = useMatchedNodes()
// matchedIds: ['dashboard', 'users', 'user-list']
// matchedNodes: corresponding NavoNode objects

useNavo()

Returns utility functions for working with the navigation tree:

const { nodes, getNodeById, getPathById, hasCanAccess } = useNavo()

// Get all authorized nodes
nodes.forEach(node => console.log(node.label))

// Check access
if (hasCanAccess('settings')) { /* ... */ }

// Get path by id
const path = getPathById('user-list') // '/users/list'

Route Guard (403 / Unauthorized)

Navo controls menu visibility via authenticat, but routes generated by generateRoutes always include all pages. To block unauthorized URL access, use useCanAccessPage:

import { useCanAccessPage } from '@navojs/react-router'
import { Outlet } from 'react-router'

function Layout() {
  const canAccess = useCanAccessPage()

  return (
    <div>
      <Sidebar />
      <main>
        {canAccess ? <Outlet /> : <UnauthorizedPage />}
      </main>
    </div>
  )
}

Design note: Navo intentionally does not ship a built-in 403 component. It provides the primitives (useCanAccessPage, hasCanAccess, useMatchedNodes) and leaves the UI decision to you.

Route Escape Hatch

You can pass native React Router route properties through the route field:

createNavo([
  {
    id: 'home',
    path: '/',
    route: {
      loader: () => fetchData(),
      caseSensitive: true,
      errorElement: <ErrorPage />,
    },
  },
])

API

generateRoutes(navo)

Converts a Navo instance into an array of React Router RouteObjects with automatic index redirects.

NavoProvider

React context provider that holds the Navo instance and authentication state.

NavoRedirect

Internal component that handles automatic redirection to the resolved path (e.g., redirecting /users to /users/list).

License

MIT