🧭 Angular Breadcrumb Library

A lightweight, animated breadcrumb navigation for Angular applications. Built with standalone components and designed for smooth integration with Angular Router.

📚 Table of Contents

• Features
• For Developers & Contributors
• Installation
• Usage
• Customization
• Icons & Interactive Features
• Event Handling
• SEO Benefits
• API Reference

✨ Features

• 🚀 Modern Architecture - Built with Angular standalone components
• 🔄 Reactive Design - Automatically updates when routes change
• 🎨 Minimalist Look - Clean design with subtle animations
• 🔧 Customizable - Easily modify separators, icons, and styling
• 📱 Responsive - Adapts to different screen sizes
• 🎭 Framework Agnostic Styling - No external CSS dependencies
• 🔍 SEO Friendly - Built-in Schema.org markup for better search visibility
• ♿ Accessible - Follows ARIA best practices for navigation
• 🔄 Broad Compatibility - Works with Angular 14 through 19
• 🖼️ Icon Support - Display custom icons with your breadcrumbs
• 🖱️ Interactive - Custom click handling and event emission

🛠 For Developers & Contributors

Architecture

The breadcrumb library consists of two main parts:

1. BreadcrumbService - A singleton service that:

   • Listens to router navigation events
   • Extracts breadcrumb data from route configurations
   • Provides an observable stream of breadcrumb items

2. BreadcrumbComponent - A standalone component that:

   • Consumes the breadcrumb service
   • Renders the breadcrumb trail with proper accessibility attributes
   • Provides smooth animations and hover effects
   • Includes Schema.org structured data for SEO

Project Structure

Installation

To install the library, run the following command in your Angular project:

npm install @ghp-library/breadcumb

Usage

Importing the Library

The breadcrumb library can be imported in different ways depending on your application setup:

For Standalone Components (Recommended)

import { BreadcrumbComponent } from '@ghp-library/breadcumb';

@Component({
  // ...
  imports: [BreadcrumbComponent]
})
export class YourComponent {}

For Module-based Applications

import { BreadcrumbModule } from '@ghp-library/breadcumb';

@NgModule({
  // other imports ...
  imports: [BreadcrumbModule],
  // ...
})
export class YourModule {}

Using the Breadcrumb Service

Inject BreadcrumbService into your components to use its functionalities:

import { Component, OnInit } from "@angular/core";
import { BreadcrumbService } from "@ghp-library/breadcumb";

@Component({
  selector: "app-example",
  templateUrl: "./example.component.html",
})
export class ExampleComponent implements OnInit {
  constructor(private breadcrumbService: BreadcrumbService) {}

  ngOnInit() {
    // Use breadcrumb service methods here
  }
}

Displaying Breadcrumbs

You can display breadcrumbs in your template using one of these approaches:

Using the Pre-styled Component

<lib-breadcrumb />

This approach uses the library's default styling and animations.

Custom Implementation

For complete control over the design, you can use the breadcrumb service directly:

<nav aria-label="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList">
  <ol class="breadcrumb">
    <li *ngFor="let breadcrumb of breadcrumbService.breadcrumbs$ | async" 
        class="breadcrumb-item"
        [class.active]="breadcrumb.active"
        itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem">
      <a [routerLink]="breadcrumb.url" itemprop="item">
        <span itemprop="name">{{ breadcrumb.label }}</span>
      </a>
      <meta itemprop="position" content="{{ breadcrumb.position }}" />
    </li>
  </ol>
</nav>

This approach allows you to:

• Customize the HTML structure
• Apply your own CSS styles
• Add custom logic and behaviors

🔍 SEO Benefits

Key Schema.org Properties Used

1. itemscope: Indicates that the element contains structured data
2. itemtype: Specifies the type of structured data (BreadcrumbList and ListItem)
3. itemprop="itemListElement": Marks each breadcrumb as an item in the list
4. itemprop="position": The position of the breadcrumb in the sequence
5. itemprop="name": The text label of the breadcrumb
6. itemprop="item": The URL of the page the breadcrumb points to

Benefits for Your Library Users

1. Better SEO: Users of your breadcrumb component automatically get SEO benefits
2. Zero configuration: The schema.org markup is automatically applied
3. Best practices: Follows Google's recommendations for breadcrumb structured data

🎨 Customization

Basic Options

<!-- Basic usage with default separator (/) -->
<ghp-breadcrumb></ghp-breadcrumb>

<!-- With custom separator -->
<ghp-breadcrumb separator="›"></ghp-breadcrumb>

<!-- With base URL for SEO -->
<ghp-breadcrumb baseUrl="https://example.com"></ghp-breadcrumb>

<!-- Limit number of visible items -->
<ghp-breadcrumb [maxItems]="4" ellipsisLabel="..."></ghp-breadcrumb>

<!-- Highlight the last item -->
<ghp-breadcrumb lastItem="ItemName"></ghp-breadcrumb>

<!-- Apply custom color class -->
<ghp-breadcrumb colorClass="custom-color-class"></ghp-breadcrumb>

🖼️ Icons & Interactive Features

Using Icons in Breadcrumbs

You can add icons to your breadcrumbs by including the icon information in your route data:

const routes: Routes = [
  {
    path: 'dashboard',
    component: DashboardComponent,
    data: { 
      breadcrumb: {
        label: 'Dashboard',
        icon: 'fa fa-dashboard' // Using Font Awesome as an example
      }
    }
  }
];

To control icon display:

<!-- Enable or disable icon display -->
<ghp-breadcrumb [showIcons]="true"></ghp-breadcrumb>

Customizing Navigation

You can also disable the default Router navigation and implement custom behavior:

<!-- Disable Router navigation and handle clicks manually -->
<ghp-breadcrumb 
  [disableRouterNavigation]="true"
  (breadcrumbClick)="handleBreadcrumbClick($event)">
</ghp-breadcrumb>

🎮 Event Handling

The breadcrumb component emits events that you can listen to for custom behavior:

Breadcrumb Click Events

<ghp-breadcrumb (breadcrumbClick)="onBreadcrumbClicked($event)"></ghp-breadcrumb>

onBreadcrumbClicked(breadcrumb: Breadcrumb) {
  console.log('Breadcrumb clicked:', breadcrumb);
  // Custom navigation or other logic
}

Breadcrumbs Change Events

<ghp-breadcrumb (breadcrumbsChanged)="onBreadcrumbsChanged($event)"></ghp-breadcrumb>

onBreadcrumbsChanged(breadcrumbs: Breadcrumb[]) {
  console.log('Breadcrumb trail updated:', breadcrumbs);
  // Update UI or analytics based on new breadcrumb path
}

🛠 Advanced Configuration

The breadcrumb component offers extensive configuration options for enhanced functionality and customization.

📊 Component API Reference

BreadcrumbComponent Inputs

| Input | Type | Default | Description | |-------|------|---------|-------------| | separator | string | / | Separator between breadcrumb items | | baseUrl | string | '' | Base URL for schema.org absolute URLs | | maxItems | number \| null | null | Maximum visible breadcrumbs (null = unlimited) | | ellipsisLabel | string | ... | Label for collapsed breadcrumbs | | lastItem | string | '' | Custom label for the last breadcrumb item | | colorClass | string | 'text-primary' | Custom CSS class for breadcrumb items | | showIcons | boolean | true | Whether to display icons in breadcrumb items | | disableRouterNavigation | boolean | false | When true, prevents default router navigation |

BreadcrumbComponent Outputs

| Output | Type | Description | |--------|------|-------------| | breadcrumbClick | EventEmitter<Breadcrumb> | Emits when a breadcrumb item is clicked | | breadcrumbsChanged | EventEmitter<Breadcrumb[]> | Emits when the breadcrumb trail changes |

BreadcrumbService

| Property | Type | Description | |----------|------|-------------| | breadcrumbs$ | Observable<Breadcrumb[]> | Current breadcrumb trail stream |

Breadcrumb Interface

interface Breadcrumb {
  label: string;       // The display text
  url: string;         // The navigation URL
  icon?: string;       // Optional CSS class for icon display
}

BreadcrumbConfig Interface

interface BreadcrumbConfig {
  label: string | ((data: Data) => string);  // Static text or function returning text
  hidden?: boolean;                          // Whether to hide this breadcrumb
  icon?: string;                             // CSS class for icon (e.g., 'fa fa-home')
}

Route Configuration Examples

const routes: Routes = [
  {
    path: '',
    component: HomeComponent,
    data: { breadcrumb: { label: 'Home', icon: 'fa fa-home' } }
  },
  {
    path: 'products',
    component: ProductListComponent,
    data: { breadcrumb: 'Products' },
    children: [
      {
        path: ':id',
        component: ProductDetailComponent,
        // Dynamic label based on route data
        data: { 
          breadcrumb: (data: Data) => `Product ${data['product']?.name || 'Detail'}`,
          // You can include other data needed for the label function
          someKey: 'someValue'
        }
      },
      {
        path: ':id/edit',
        component: ProductEditComponent,
        // Hide this segment from breadcrumbs
        data: { breadcrumb: { label: 'Edit', hidden: true } }
      }
    ]
  }
];