ng-hub-ui-breadcrumbs

A flexible and reusable breadcrumb component for Angular applications that automatically generates breadcrumbs entirely based on your routing configuration.

🧩 Library Family ng-hub-ui

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

• ng-hub-ui-accordion
• ng-hub-ui-avatar
• ng-hub-ui-board
• ng-hub-ui-breadcrumbs
• ng-hub-ui-calendar
• ng-hub-ui-modal
• ng-hub-ui-paginable
• ng-hub-ui-portal
• ng-hub-ui-stepper
• ng-hub-ui-utils

Table of Contents

• Features
• Installation
• Usage
• Examples
• API Reference
• Styling
• Support & License

Features

• Automatic Breadcrumb Generation: Automatically builds breadcrumbs from your Angular Routes configuration.
• Dynamic Labels: Supports dynamic labels via functions or string interpolation using resolved data.
• Custom Templates: Full control over how each breadcrumb item is rendered using directives.
• RTL Support: Built-in support for Right-to-Left languages.
• Lazy Loading Compatible: Works seamlessly with lazy-loaded modules.

Installation

npm install ng-hub-ui-breadcrumbs

Usage

1. Import the Component

You can import the HubBreadcrumbComponent directly in your standalone component or module.

import { HubBreadcrumbComponent } from 'ng-hub-ui-breadcrumbs';

@Component({
	// ...
	imports: [HubBreadcrumbComponent]
})
export class AppComponent {}

2. Add to Template

Place the component in your application's main layout or wherever you want breadcrumbs to appear.

<hub-breadcrumb></hub-breadcrumb>

3. Configure Routes

The most critical part is adding data: { breadcrumb: '...' } to your routes.

```typescript
const routes: Routes = [
	{
		path: '',
		data: { breadcrumb: 'Home' } // Standard static label
	},
	{
		path: 'products',
		data: { breadcrumb: 'Products' },
		children: [
			// ... child routes
		]
	}
];

4. Working with Lazy Loading

For lazy-loaded modules, configure the parent route with breadcrumb data:

// app-routing.module.ts
const routes: Routes = [
	{
		path: 'admin',
		data: { breadcrumb: 'Administration' },
		loadChildren: () => import('./admin/admin.module').then((m) => m.AdminModule)
	}
];

// admin-routing.module.ts
const adminRoutes: Routes = [
	{
		path: 'users',
		data: { breadcrumb: 'Users' }
	}
];

This will generate breadcrumbs like: Home > Administration > Users

Examples

Dynamic Labels with Functions

You can use a function to generate the breadcrumb label dynamically based on route data.

const routes: Routes = [
	{
		path: 'dashboard',
		resolve: { userInfo: UserResolver },
		data: {
			breadcrumb: (data: any) => `User: ${data.userInfo.name}` // Function creates label from resolved data
		}
	}
];

Dynamic Labels with Interpolation

Alternatively, you can use string interpolation {key} if your data is under a resolvedData property.

const routes: Routes = [
	{
		path: 'product/:id',
		resolve: {
			resolvedData: ProductResolver // Must be named 'resolvedData' for interpolation
		},
		data: {
			breadcrumb: 'Product: {name}' // Replaces {name} with resolvedData.name
		}
	}
];

Custom Icons

You can attach arbitrary data (like icons) to your route config and use it in a custom template.

// Route Configuration
{
  path: 'settings',
  data: {
    breadcrumb: 'Settings',
    icon: 'fa fa-cog' // Custom data property
  }
}

<!-- Custom Template Implementation -->
<hub-breadcrumb>
	<ng-template hubBreadcrumbItem let-item let-isLast="isLast">
		<!-- 'item.data' contains the entire route data object -->
		@if (item.data.icon) {
		<i [class]="item.data.icon"></i>
		}
		<a [routerLink]="item.url">{{ item.label }}</a>
	</ng-template>
</hub-breadcrumbs>

Custom Template & Separators

Fully customize the structure, including separators/dividers.

<hub-breadcrumb>
	<ng-template hubBreadcrumbItem let-item let-isLast="isLast">
		<span class="my-breadcrumb-item">
			<a [routerLink]="item.url">{{ item.label }}</a>
		</span>
		<!-- Custom Separator -->
		@if (!isLast) {
		<span class="separator"> / </span>
		}
	</ng-template>
</hub-breadcrumbs>

API Reference

HubBreadcrumbComponent

The main container component. It doesn't have any inputs as it reads directly from the Router.

| Selector | Exported As | | ----------------- | ---------------- | | hub-breadcrumb | hubBreadcrumb |

HubBreadcrumbItemDirective

A structural directive used to define a custom template for breadcrumb items.

| Selector | Context Type | | --------------------- | --------------------------- | | [hubBreadcrumbItem] | BreadcrumbTemplateContext |

Interfaces

BreadcrumbItem

| Property | Type | Description | | -------- | -------- | ------------------------------------------------------- | | label | string | The resolved text to display for the breadcrumb. | | url | string | The full URL path to navigate to. | | data | any | The original route data object (useful for icons, etc). |

BreadcrumbTemplateContext

| Property | Type | Description | | ----------- | ---------------- | ------------------------------------------------------------- | | $implicit | BreadcrumbItem | The current breadcrumb item object. | | isLast | boolean | True if this item is the last one in the list (current page). |

Styling

ng-hub-ui-breadcrumbs is fully style-configurable through CSS custom properties.

For a complete and up-to-date token catalog, see CSS Variables Reference.

Quick customization example (framework-agnostic)

.hub-breadcrumb__list {
	--hub-breadcrumb-bg: #f8f9fa;
	--hub-breadcrumb-divider: '→';
	--hub-breadcrumb-link-color: #0d6efd;
	--hub-breadcrumb-item-active-color: #6c757d;
}

Bootstrap integration (optional)

.hub-breadcrumb__list {
	--hub-breadcrumb-bg: var(--bs-light);
	--hub-breadcrumb-link-color: var(--bs-primary);
	--hub-breadcrumb-link-hover-color: var(--bs-primary-text-emphasis);
	--hub-breadcrumb-item-active-color: var(--bs-secondary-color);
}

Contributing

We appreciate your interest in contributing to Hub Breadcrumb! Here's how you can help:

Development Setup

1. Clone the repository

   git clone https://github.com/carlos-morcillo/ng-hub-ui-breadcrumbs.git
   cd ng-hub-ui-breadcrumbs

2. Install dependencies

   npm install

3. Start the development server

   npm start

Testing

Run the test suite:

# Unit tests
npm run test

# E2E tests
npm run e2e

# Test coverage
npm run test:coverage

Commit Guidelines

We follow Conventional Commits:

• feat: New features
• fix: Bug fixes
• docs: Documentation changes
• style: Code style changes (formatting, etc)
• refactor: Code refactors
• test: Adding or updating tests
• chore: Maintenance tasks

Example:

git commit -m "feat: add custom divider support"

Support & License

If you find this project helpful and would like to support its development, you can buy me a coffee:

Your support is greatly appreciated and helps maintain and improve this project!

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

Made with ❤️ by [Carlos Morcillo Fernández]