XngBreadcrumb

A lightweight, declarative and configurable breadcrumbs for Angular 6 and beyond https://www.npmjs.com/package/xng-breadcrumb

About

In applications with deep navigation hierarchy, it is essential to have breadcrumb navigation. Breadcrumbs provides links back to each previous page that the user navigated through and shows the current location in an application.

Breadcrumbs are useful when the app has more than two levels of hierarchy. User can easily navigate back to any level.

Demo

Live Demo - An Angular App showing xng-breadcrumb usage. It covers all available options.

Features

• ✅ Quick start with default mapping: Just by adding <breadcrumb></breadcrumb> show breadcrumbs anywhere in the App. Breadcrumbs defualts to route segments even without any configuration.
• ✅ Declarative mapping: Map breadcrumb label for each route, while declaring App routes.
• ✅ Dynamic mapping: Resolve a breadcrumb label dynamically, by using BreadcrumbService.
• ✅ Skip Breadcrumb: Skip specific routes from displaying in breadcrumbs, conditionally.
• ✅ Schematics: Use schematics to add and update the library with ng add xng-breadcrumb and ng update xng-breadcrumb

Getting Started

1. Install xng-breadcrumb via npm or yarn

npm install --save xng-breadcrumb
//------------- OR --------------
yarn add xng-breadcrumb

2. Import BreadcrumbModule in your Application

import {BreadcrumbModule} from 'xng-breadcrumb';
@NgModule({
  ...
  imports: [BreadcrumbModule],
  ...
})
export class AppModule { }

3. Add Breadcrumb selector, whereever you plan to show breadcrumbs

<xng-breadcrumb></xng-breadcrumb>

Alternative: Angular Devkit 6+

If you are using Angular CLI 6+, just use ng add command to update your Angular project with all above steps.

ng add xng-breadcrumb

Usage

Adding breadcrumb label while declaring routes

{
    path: 'dashboard',
    loadChildren: './dashboard/dashboard.module#DashboardModule',
    data: { breadcrumb: 'Home'}
}
{
    path: 'add',
    component: MentorAddComponent,
    data: { breadcrumb: 'New'}
}

Setting breadcrumb label dynamically by route path

// Add a label dynamically using 'set()' from BreadcrumbService
// It takes static path as well as path with params
{
    path: 'mentor',
    component: MentorDetailsComponent,
    children: [
        {
            path: ':id',
            component: MentorEditComponent
        }
    ]

}
breadcrumbService.set('mentor', 'Enabler'); // static path
breadcrumbService.set('mentor/:id', 'Uday Vunnam'); // path with params

Setting breadcrumb label dynamically by breadcrumbAlias

// Add a label dynamically using 'setForAlias()' from BreadcrumbService
{
    path: 'mentor',
    component: MentorDetailsComponent,
    children: [
        {
            path: ':id',
            component: MentorEditComponent
            data: {
                breadcrumbAlias: 'mentorName'
            }
        }
    ]

}
breadcrumbService.setForAlias('mentorName', 'Uday Vunnam');

Hiding a specific route from displaying in breadcrumbs

// Hide a route from displaying in Breadcrumbs using skipBreadcrumb or hide() or hideForAlias()
{
    path: 'edit',
    component: MentorEditComponent,
    data: { skipBreadcrumb: true }
}
breadcrumbService.skip('mentor/:id/edit');
breadcrumbService.skipForAlias('breadcrumbAlias');

// An optional second parameter can be passed as false to make a hidden breadcrumb visible
breadcrumbService.skip('mentor/:id/edit', false);
breadcrumbService.skipForAlias('breadcrumbAlias', false);

Customization

Custom seperator Breadcrumb by default uses '/' as the seperator. To use custom sepertor pass it as input to the component like below.

<xng-breadcrumb seperator=">"></xng-breadcrumb>

Disabling default mapping of route to breadcrumb label To avoid breadcrumb labels showing by default even for routes that don't have breadcrumb configuration set defaultMapping=false.

<xng-breadcrumb seperator=">"></xng-breadcrumb>

Styling breadcrumbs The library uses the least specific selectors possible in order to make it easy to override them. you can override by changing the css for classes .breadcrumb, .current-path, .seperator etc with ::ng-deep

::ng-deep .breadcrumb {
  background-color: bisque;
  border: 1px solid;
}

API

That's it! You are now ready to use breadcrumbs in your App! 🎉

Local Development

If you wish to contribute to this repository, below are the steps for local development.

• Clone the repository git clone https://github.com/udayvunnam/xng-breadcrumb.git
• Run npm install to install the dependencies
• Run npm start to build and watch both library and demo app. This opens app at http://localhost:4200/ automatically.

Build

Run npm run build to build the library and demo app together. The build artifacts will be stored in the dist/ directory.

This step is used by CircleCI to build both library and demo app. After a succesful build, a new semantic version of library is published to npm and demo app is deployed to Netlify.

Tests

Run ng test to execute the unit tests via Karma.

Accessibility

• A <nav> with aria-label="breadcrumb" identifies type of navigation as breadcrumb by screen readers.
• The breadcrumb links are structured using an ordered list <ol>.
• The last <li> element represents current page, so it doesn't have to be clickable.
• Use aria-current=page and class=active for last <li> element.
• Separators between links have aria-hidden=true. This prevents the screen reader announcement of visual separators.

Motivation 🎉🎉🎉

You can create your own library with complete automated setup for build, tests and release. You can check this guide of best practices and implementation details in this blog post