@xyz/navigation

A flexible, context-aware navigation module for Nuxt 4 with zero performance overhead and zero boilerplate.


Features

- 🎯 Context-Aware Paths - Dynamic path resolution using templates ({org}, {slug}, {username})
- 🔐 Role-Based Filtering - Show/hide items based on user roles
- 🚩 Feature Flags - Conditional navigation based on enabled features
- ⚡ Zero Performance Overhead - SSR-safe with reactive computed properties
- 🌍 Auto Translation - Automatic i18n integration with zero config
- 🎨 Normalized Structure - Consistent API for all navigation sections
- ✨ Active States - Automatic route matching and active states
- 🔧 Runtime Functions - Use composables directly in config
- 📘 Full TypeScript Support - Complete type safety and inference

Installation

``bash
pnpm add @xyz/navigation


or

npm install @xyz/navigation

or

yarn add @xyz/navigation
`

Quick Start

$3

`typescript
// nuxt.config.ts
export default defineNuxtConfig({
modules: ['@xyz/navigation'] // That's it!
})
`

$3

navigation.config.ts - Everything in one place:

`typescript
export default {
// Module Options (optional, auto-detected)
translationResolver: () => useI18n().t, // Auto-detects $t if using @nuxtjs/i18n

// Navigation Sections
sections: {
// Flat section (auto-normalized)
main: [
{ label: 'nav.dashboard', to: '/app', icon: 'i-lucide-home' },
{ label: 'nav.projects', to: '/projects', icon: 'i-lucide-folder' }
],

// Nested section with header
organization: {
header: (ctx) => ({
title: ctx.activeOrganization?.name ?? 'Personal',
avatar: {
// ✅ Use composables in config - functions execute at runtime!
src: toAbsoluteUrl(ctx.activeOrganization?.logo || ''),
icon: 'i-lucide-building-2'
}
}),
items: [
{ label: 'nav.overview', to: '{org}' },
{ label: 'nav.team', to: '{org}/team', features: ['team'] }
],
children: [
{ label: 'nav.settings', to: '{org}/settings' }
]
}
}
}
`

$3

`vue



`

> Note: Labels are auto-translated if using @nuxtjs/i18n or a custom translationResolver.

> Note: Labels are auto-translated if using @nuxtjs/i18n or a custom translationResolver.

Unified Configuration

navigation.config.ts is your single source of truth for both module options and navigation data.

$3

`typescript
// navigation.config.ts
export default {
// Module Options (build-time, optional)
translationResolver: () => useTranslations().t,
contextProvider: () => ({
user: useAuthUser(),
activeOrganization: useActiveOrg(),
features: useFeatureFlags()
}),
templates: {
workspace: (ctx) => ctx.workspaceSlug || 'default'
},

// Navigation Sections (runtime)
sections: {
main: [...],
organization: {...}
}
}
`

$3

nuxt.config.ts can override individual module options:

`typescript
export default defineNuxtConfig({
navigation: {
translationResolver: () => customResolver() // Overrides navigation.config.ts
}
})
`

Priority: nuxt.config.ts > navigation.config.ts module options > navigation.config.ts sections

Core Concepts

$3

All sections return a consistent structure:

`typescript
{
items?: NavigationMenuItem[] // Main navigation items
header?: SectionHeader // Optional header with title, avatar
children?: NavigationMenuItem[] // Sub-navigation items
footer?: NavigationMenuItem[] // Footer items
}
`

Flat sections (arrays) are auto-wrapped:
`typescript
// Config
sections: {
main: [{ label: 'Dashboard', to: '/app' }]
}

// Result
sections.value.main = {
items: [{ label: 'Dashboard', to: '/app', active: true }],
header: undefined,
children: [],
footer: []
}
`

$3

Config functions execute at runtime, so composables work:

`typescript
export default {
sections: {
organization: {
header: (ctx) => ({
title: ctx.activeOrganization?.name,
avatar: {
// ✅ Use composables directly!
src: toAbsoluteUrl(ctx.activeOrganization?.logo || '')
}
}),
items: [...]
}
}
}
`

$3

Zero config with @nuxtjs/i18n:

`typescript
// navigation.config.ts - use translation keys
export default {
sections: {
main: [
{ label: 'nav.dashboard', to: '/app' }, // Auto-translated!
{ label: 'nav.projects', to: '/projects' }
]
}
}

// Component - translations applied automatically
const { sections } = useNavigation(config)
`

Custom translation resolver:

`typescript
// nuxt.config.ts
export default defineNuxtConfig({
navigation: {
translationResolver: () => {
const { t } = useTranslations()
return t
}
}
})
`

$3

Navigation items include active boolean based on current route:

`typescript
{
label: 'Blog',
to: '/blog',
exact: false, // Active for /blog and /blog/*
active: true // ✅ Auto-computed
}
`

Use in templates:

`vue

`

Template Variables

Built-in template variables for dynamic paths:

| Template | Resolves To | Example |
|----------|-------------|---------|
| {org} | /app (personal) or /app/:slug (organization) | {org}/projects → /app/acme/projects |
| {slug} | Current organization slug | {slug} → acme |
| {username} | Current user's name or email | /u/{username} → /u/john |
| {user.id} | Current user ID | /users/{user.id} → /users/123 |

$3

`typescript
// nuxt.config.ts
export default defineNuxtConfig({
navigation: {
templates: {
workspace: (ctx) => ctx.workspaceSlug || 'default',
tenant: (ctx) => ctx.activeTenant?.id || ''
}
}
})

// Use in config
{ label: 'Workspace', to: '/w/{workspace}/dashboard' }
`

Advanced Features

$3

`typescript
{
label: 'Analytics',
to: '/analytics',
features: ['analytics'] // Only shown if analytics feature enabled
}
`

Provide features via context:

`typescript
const { sections } = useNavigation(config, {
context: {
features: { analytics: true, team: false }
}
})
`

$3

`typescript
{
label: 'Admin Panel',
to: '/admin',
roles: ['admin', 'owner'] // Only for admins/owners
}
`

Configure role hierarchy:

`typescript
// nuxt.config.ts
export default defineNuxtConfig({
navigation: {
config: {
roles: {
hierarchy: ['viewer', 'member', 'admin', 'owner'],
resolver: (user) => user?.role || 'viewer'
}
}
}
})
`

$3

`typescript
{
label: 'Settings',
to: '/settings',
children: [
{ label: 'General', to: '/settings/general' },
{ label: 'Billing', to: '/settings/billing', roles: ['admin'] }
]
}
`

$3

`typescript
{
label: 'Upgrade',
to: '/upgrade',
condition: (ctx) => !ctx.user?.isPremium // Only for free users
}
`

API Reference

$3

Main composable for navigation.

Parameters:
- config: NavigationConfig - Navigation configuration object
- options?: UseNavigationOptions - Optional configuration

Returns:
`typescript
{
sections: ComputedRef>
context: ComputedRef
refresh: () => void
}
`

Options:

`typescript
interface UseNavigationOptions {
// Custom context provider
context?: NavigationContext | (() => NavigationContext)

// Reactive updates (default: true)
reactive?: boolean

// Custom template resolvers
templates?: Record string>

// Override global translation function
translationFn?: (key: string) => string
}
`

$3

`typescript
interface NavigationItemConfig {
label: string // Label (or translation key)
to?: string // Path (supports templates)
icon?: string // Icon name
exact?: boolean // Exact route matching (default: true)

// Filtering
features?: string[] // Required feature flags
roles?: string[] // Required user roles
condition?: (ctx: NavigationContext) => boolean // Custom condition

// Nested navigation
children?: NavigationItemConfig[]

// Custom handlers
onSelect?: (item: NavigationItemConfig) => void

// Divider
divider?: boolean

// Custom metadata
badge?: string | number
[key: string]: any // Additional custom fields
}
`

$3

`typescript
interface SectionHeader {
title?: string
subtitle?: string
avatar?: {
src?: string | null
icon?: string
fallback?: string
}
}
`

$3

All sections return this normalized structure:

`typescript
interface ProcessedSection {
items?: NavigationMenuItem[] // With active states
header?: SectionHeader
children?: NavigationMenuItem[]
footer?: NavigationMenuItem[]
}
`

Complete Example

`typescript
// navigation.config.ts
export default {
sections: {
// App navigation (flat)
app: [
{
label: 'nav.dashboard',
to: '/app',
icon: 'i-lucide-home',
exact: true
},
{
label: 'nav.projects',
to: '/app/projects',
icon: 'i-lucide-folder',
exact: false // Active for /app/projects/*
}
],

// Organization navigation (nested)
organization: {
header: (ctx) => ({
title: ctx.activeOrganization?.name ?? 'Personal',
subtitle: ctx.activeOrganization?.slug,
avatar: {
src: useImageUrl().toAbsoluteUrl(
ctx.activeOrganization?.logo || ''
),
icon: 'i-lucide-building-2',
fallback: ctx.activeOrganization?.name?.charAt(0)
}
}),

items: [
{
label: 'nav.overview',
to: '{org}',
icon: 'i-lucide-layout-dashboard'
},
{
label: 'nav.team',
to: '{org}/team',
icon: 'i-lucide-users',
features: ['team']
},
{
label: 'nav.analytics',
to: '{org}/analytics',
icon: 'i-lucide-bar-chart',
features: ['analytics'],
roles: ['admin', 'owner']
}
],

children: [
{
label: 'nav.settings',
to: '{org}/settings',
icon: 'i-lucide-settings',
children: [
{ label: 'nav.settings.general', to: '{org}/settings/general' },
{ label: 'nav.settings.billing', to: '{org}/settings/billing', roles: ['owner'] }
]
}
],

footer: [
{ label: 'nav.help', to: '/help', icon: 'i-lucide-help-circle' },
{ label: 'nav.docs', to: '/docs', icon: 'i-lucide-book' }
]
},

// Profile navigation
profile: [
{ label: 'nav.profile.account', to: '/profile', icon: 'i-lucide-user' },
{ label: 'nav.profile.preferences', to: '/preferences', icon: 'i-lucide-sliders' },
{ divider: true },
{ label: 'nav.profile.logout', icon: 'i-lucide-log-out', onSelect: () => logout() }
]
}
}
`

Module Configuration

`typescript
// nuxt.config.ts
export default defineNuxtConfig({
navigation: {
// Translation resolver (runtime)
translationResolver: () => {
const { t } = useTranslations()
return t
},

// Custom templates
templates: {
workspace: (ctx) => ctx.workspaceSlug || 'default'
},

// Context provider
contextProvider: (nuxtApp) => ({
user: nuxtApp.$auth?.user,
activeOrganization: nuxtApp.$org?.active,
features: nuxtApp.$features?.all()
}),

// Role configuration
config: {
roles: {
hierarchy: ['viewer', 'member', 'admin', 'owner'],
resolver: (user) => user?.role || 'viewer'
}
}
}
})
`

TypeScript

Full type safety with inference:

`typescript
import type { NavigationConfig, NavigationMenuItem } from '@xyz/navigation'

const config: NavigationConfig = {
sections: {
main: [...] // Fully typed
}
}

const { sections } = useNavigation(config)
sections.value.main.items // NavigationMenuItem[]
`

Migration Guide

$3

All sections now return normalized structure:

`typescript
// v1.0
sections.value.main // NavigationMenuItem[]
sections.value.org // { items, header, children, footer }

// v1.2 (normalized)
sections.value.main.items // NavigationMenuItem[]
sections.value.org.items // NavigationMenuItem[]
``

Both flat and nested sections now have consistent API.

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.