ng-hub-ui-nav

Español | English

A flexible, accessible, and highly customizable navigation component for Angular 21+. It supports horizontal menus, vertical sidebars, mobile collapse modes, stacked drill-down panels, projected start/end slots, and scroll-spy integration.

[!IMPORTANT] Version 21.1.1 targets Angular 21 and follows the signal-first architecture used across ng-hub-ui.

Documentation and Live Examples

This package is part of Hub UI, a collection of Angular component libraries for standalone apps.

• Docs: https://hubui.dev/nav/overview/
• Live examples: https://hubui.dev/nav/examples/
• Hub UI: https://hubui.dev/

🧩 Library Family ng-hub-ui

This library is part of the ng-hub-ui ecosystem:

• ng-hub-ui-accordion (deprecated — use ng-hub-ui-panels)
• ng-hub-ui-action-sheet
• ng-hub-ui-avatar
• ng-hub-ui-board
• ng-hub-ui-breadcrumbs
• ng-hub-ui-calendar
• ng-hub-ui-dropdown
• ng-hub-ui-ds
• ng-hub-ui-forms
• ng-hub-ui-history
• ng-hub-ui-milestones
• ng-hub-ui-modal
• ng-hub-ui-nav ← You are here
• ng-hub-ui-paginable
• ng-hub-ui-panels
• ng-hub-ui-portal
• ng-hub-ui-skeleton
• ng-hub-ui-sortable
• ng-hub-ui-stepper
• ng-hub-ui-utils

Table of Contents

• Features
• Installation
• Quick Start
• Examples
• API Reference
• Styling
• Changelog
• Contribution
• Support
• Contributors
• License

Features

• Horizontal and vertical navigation layouts.
• Responsive collapse modes: offcanvas, dropdown, and fullscreen.
• Vertical child expansion modes: accordion, flyout, and panel.
• Stacked panel drill-down navigation with configurable visible panel count.
• Projected hubNavStart and hubNavEnd slots.
• Custom item rendering with hubNavItemTemplate.
• Router-aware active states with fragment and query param support.
• Scroll-spy helpers for documentation pages and one-page layouts.
• Sticky vertical navigation support.
• Tooltip on truncated labels — long item labels are clipped with an ellipsis (the standard sidebar behaviour) and reveal their full text on hover, automatically and only when truncated (via ng-hub-ui-utils' [hubOverflowTooltip]). The tooltip is agnostic — it defaults to the hub-ui tooltip but is swappable with provideHubTooltip(...). Requires ng-hub-ui-utils >= 22.6.0 and the tooltip styles (@use 'ng-hub-ui-utils/styles/tooltip';). Tip: control the sidebar width with --hub-nav-panel-width.
• Semantic variant accent system (primary / success / danger / warning / info, plus any custom accent) recolouring the hover/active affordances — mirrors <hub-panels>.
• Full CSS variable theming via --hub-nav-* tokens.

Installation

npm install ng-hub-ui-nav

Quick Start

import { Component } from '@angular/core';
import { HubNavComponent, HubNavItem } from 'ng-hub-ui-nav';

@Component({
	standalone: true,
	imports: [HubNavComponent],
	template: `
		<hub-nav
			[items]="items"
			[config]="{
				orientation: 'horizontal',
				dropdownTrigger: 'click'
			}"
		/>
	`
})
export class ExampleComponent {
	readonly items: HubNavItem[] = [
		{ id: 'home', label: 'Home', type: 'link', route: '/' },
		{
			id: 'components',
			label: 'Components',
			type: 'dropdown',
			children: [
				{ id: 'accordion', label: 'Accordion', type: 'link', route: '/accordion' },
				{ id: 'calendar', label: 'Calendar', type: 'link', route: '/calendar' }
			]
		}
	];
}

Examples

Vertical Sidebar with Panels

<hub-nav
	[items]="items"
	[config]="{
		orientation: 'vertical',
		verticalExpandMode: 'panel',
		panelMaxVisible: 2,
		panelWidth: '18rem',
		position: 'sticky',
		stickyTop: '1rem'
	}"
/>

Start and End Slots

<hub-nav [items]="items" [config]="{ orientation: 'horizontal' }">
	<ng-template hubNavStart let-collapsed="collapsed">
		<strong>My App</strong>
	</ng-template>

	<ng-template hubNavEnd>
		<button type="button">Profile</button>
	</ng-template>
</hub-nav>

Scroll Spy

<section
	hubNavScrollSpy
	(activeSectionChange)="activeSection = $event"
>
	<section id="overview" hubNavScrollSpySection>...</section>
	<section id="api" hubNavScrollSpySection>...</section>
</section>

API Reference

HubNavComponent

Inputs

| Input | Type | Default | Description | |---|---|---|---| | items | HubNavItem[] | required | Navigation tree to render. | | config | Partial<HubNavConfig> | {} | Per-instance config merged with global defaults. | | navClass | string | '' | Additional class applied to the internal <nav>. | | itemTemplate | TemplateRef<unknown> \| null | null | Optional custom item template. | | autoOpenFromRoute | boolean | false | Opens matching dropdowns/panels from the current route. | | variant | 'primary' \| 'success' \| 'danger' \| 'warning' \| 'info' \| string | 'primary' | Semantic accent for the hover/active affordances. Built-in values render with the design-system tints; any custom string resolves through --hub-sys-color-<variant>. |

Outputs

| Output | Type | Description | |---|---|---| | itemClick | OutputEmitterRef<HubNavItem> | Emitted when a link item is activated. | | dropdownOpen | OutputEmitterRef<HubNavItem> | Emitted when a dropdown opens. | | dropdownClose | OutputEmitterRef<HubNavItem> | Emitted when a dropdown closes. | | mobileToggle | OutputEmitterRef<boolean> | Emitted when the responsive mobile panel opens or closes. | | panelChange | OutputEmitterRef<HubNavPanelEvent> | Emitted when a panel opens, closes, drills down, or drills back. |

HubNavConfig

interface HubNavConfig {
	orientation: 'horizontal' | 'vertical';
	verticalExpandMode: 'accordion' | 'flyout' | 'panel';
	dropdownTrigger: 'hover' | 'click' | 'both';
	position: 'static' | 'sticky' | 'fixed';
	stickyTop: string;
	collapseMode: 'offcanvas' | 'dropdown' | 'fullscreen';
	collapseBreakpoint: number;
	offcanvasPosition: 'start' | 'end' | 'top' | 'bottom';
	ariaLabel: string;
	panelMaxVisible: number;
	sidebarSide: 'left' | 'right';
	panelWidth: string;
}

HubNavItem

interface HubNavItem {
	id: string;
	label: string;
	type: 'link' | 'dropdown' | 'header' | 'separator' | 'custom';
	icon?: string;
	route?: string | string[];
	queryParams?: Record<string, string>;
	fragment?: string;
	routerLinkActiveOptions?: { exact: boolean };
	children?: HubNavItem[];
	badge?: string;
	badgeClass?: string;
	disabled?: boolean;
	cssClass?: string;
	data?: unknown;
	expandMode?: 'accordion' | 'flyout' | 'panel';
}

Directives

• hubNavStart: projects content into the start slot.
• hubNavEnd: projects content into the end slot.
• hubNavItemTemplate: overrides item rendering.
• hubNavScrollSpy: tracks visible sections in a scroll container.
• hubNavScrollSpySection: marks a section as spy-trackable.

Styling

The component exposes a complete set of --hub-nav-* tokens. See the full reference in:

• CSS Variables Reference

Recolour the whole nav from a single accent

The hover/active affordances and the nav surface all derive from one accent hook. Set it (or use the variant input) to re-theme the entire nav:

.my-sidebar {
	--hub-nav-panel-width: 18rem;
	/* Single recolour hook — the tinted active background, accent text, hover
	   tint, indicator bar, and surface wash all follow this one accent. */
	--hub-nav-accent: var(--hub-sys-color-success);
	--hub-nav-dropdown-shadow: 0 0.75rem 1.5rem rgba(0, 0, 0, 0.16);
}

Restore the legacy solid-fill look

The default active item is now a soft accent tint + accent text. To restore the previous solid accent fill + white text (the pre-22.1.0 look), override these tokens explicitly:

.my-sidebar {
	--hub-nav-item-active-bg: #0d6efd;
	--hub-nav-item-active-color: #ffffff;
	--hub-nav-item-hover-bg: rgba(0, 0, 0, 0.04);
	--hub-nav-bg: #ffffff;
}

Changelog

See the full release history in CHANGELOG.md.

If you are upgrading across versions, also review BREAKING_CHANGES.md.

Contribution

Issues, discussions, and pull requests are welcome.

If you want to contribute:

1. Fork the repository.
2. Create a feature branch.
3. Keep API changes documented in the README and changelog.
4. Open a pull request with a clear description of the change.

Support

If this library helps your projects, you can support its maintenance here:

• Buy Me a Coffee

Contributors

Created and maintained by Carlos Morcillo.

License

This project is licensed under the MIT License. See the LICENSE file for details.