@publikit/navigationrail

Desktop vertical navigation rail component with scroll management, drag-and-drop customization, and overflow handling.

Features

• Fully Customizable - Config-based architecture with optional adapters
• Scroll Management - Automatic scroll position persistence
• Pinned Items - Pin favorite items to always show
• Drag & Drop - Reorder items via drag and drop (using @dnd-kit)
• Overflow Handling - "More Items" popover for overflow
• Accessible - ARIA roles and labels on rail and nav
• Type-Safe - Full TypeScript support
• Lightweight - Uses @publikit/base for shared components

Installation

npm install @publikit/navigationrail

Peer Dependencies

npm install react react-dom lucide-react tailwindcss @publikit/base
npm install @dnd-kit/core @dnd-kit/sortable @dnd-kit/utilities

The customization popover uses @dnd-kit for drag-and-drop reordering; install these peers in your app.

Quick Start

import { NavigationRail } from '@publikit/navigationrail';

const config = {
  items: navigationItems,
  visibleItems: visibleItems,
  pinnedItems: pinnedItems,
  allItemsForCustomization: allItems,
  onReorder: handleReorder,
  onToggleVisibility: handleToggleVisibility,
  onTogglePinned: handleTogglePinned,
  onReset: handleReset,
  getItemBadge: (item) => item.badge,
};

<NavigationRail config={config} />

With Routing Adapter

import { NavLink, useMatch } from 'react-router-dom';

<NavigationRail
  config={config}
  adapters={{ routing: { Link: NavLink, useMatch } }}
/>

With i18n Labels

import { useTranslation } from 'react-i18next';

function MyNavigationRail() {
  const { t } = useTranslation('navigation');

  return (
    <NavigationRail
      config={config}
      labels={{
        customization: {
          title: t('customize.title'),
          description: t('customize.description'),
          reset: t('customize.reset'),
        },
      }}
    />
  );
}

With Footer

<NavigationRail config={config} footer={<WorkspaceSwitcher variant="desktop" />} />

API Reference

NavigationRailProps

| Prop | Type | Description | |------|------|-------------| | config | NavigationRailConfig | Navigation configuration | | adapters | { routing?: RoutingAdapter } | Optional routing adapter | | scrollPositionKey | string | Storage key for scroll position | | maxDisplayedItems | number | Max displayed items (default: 5) | | labels | { customization?: CustomizationLabels } | Labels for customization popover | | footer | ReactNode | Optional footer content | | className | string | Custom className |

Hooks

import { useScrollableContainer, SCROLL_AMOUNT, SCROLL_CHECK_DELAY } from '@publikit/navigationrail';

License

MIT