udayvunnam / Xng Breadcrumb
Programming Languages
Projects that are alternatives of or similar to Xng Breadcrumb
xng-breadcrumb
A lightweight, declarative and configurable breadcrumbs solution for Angular 6 and beyond. https://www.npmjs.com/package/xng-breadcrumb
About
- In applications with deep navigation hierarchy, it is essential to have breadcrumbs.
- Breadcrumbs easily allow going back to states higher up in the hierarchy.
Demo
Live Demo - A demo app showcasing xng-breadcrumb
usage in an Angular app. Navigate through different links to see breadcrumbs behavior.
Features
-
✅ Zero configuration: Just add
<xng-breadcrumb></xng-breadcrumb>
anywhere in the app. Breadcrumb labels will be auto-generated by analyzing Angular Route configuration in your App. -
✅ Custom labels: each route can have a custom label defined via Angular Route Config. The labels will be picked automatically while forming breadcrumbs
-
✅ Update labels dynamically: Change breadcrumbs dynamically using
BreadcrumbService.set()
. You can either use route path or breadcrumb alias to change breadcrumb for a route. -
✅ Skip breadcrumb: Skip specific routes from displaying in breadcrumbs, conditionally.
-
✅ Disable breadcrumb: Disable specific routes so that navigation is disbaled to intermediate routes.
-
✅ Customization: Customize breadcrumb template to show icons as label prefix, use pipes on text, add i18n, etc.
-
✅ Styling: Separator and Styles can be customized with ease.
-
✅ QueryParams and Fragment: Preserves QueryParams and Fragemnet while navigating via breadcrumbs
Quickstart
- Install via npm or yarn
npm install --save xng-breadcrumb
//------------- OR --------------
yarn add xng-breadcrumb
- Import 'BreadcrumbModule' in your Application
import {BreadcrumbModule} from 'xng-breadcrumb';
@NgModule({
...
imports: [BreadcrumbModule],
...
})
export class AppModule { }
- Add 'xng-breadcrumb' selector, wherever you plan to show breadcrumbs
<xng-breadcrumb></xng-breadcrumb>
- (Optional) Use BreadcrumbService, if you want to change breadcrumbs behavior(visibility, label, etc) dynamically.
import { BreadcrumbService } from 'xng-breadcrumb';
constructor(private breadcrumbService: BreadcrumbService) {}
// Code examples with BreadcrumbService are given below, under Usage section
🎉🎉 That's it. You should see auto-generated breadcrumbs appearing for each route.
Note: XngBreadcrumb has a peer dependency on @angular/router
. Include RouterModule
in App imports, if you haven't already.
Setup Guide
Provide breadcrumb labels via In App Route Config
- define 'breadcrumb' within the data property of route.
- a 'breadcrumb' can be defined as a string OR object OR function.
- Use breadcrumb as a string if you are just providing breadcrumb text
- Use breadcrumb as an object if you are providing additional properties like 'alias', 'skip', 'info', 'disable'. In you define breadcrumb as an object, label property denotes breadcrumb text.
- Use breadcrumb as a function if you want to alter the auto-generated label as needed.
breadcrumb as a string
{
path: 'dashboard',
loadChildren: './dashboard/dashboard.module#DashboardModule',
data: { breadcrumb: 'Home' }
},
{
path: 'add',
component: MentorAddComponent,
data: { breadcrumb: 'New' }
}
breadcrumb as an object
{
path: 'dashboard',
loadChildren: './dashboard/dashboard.module#DashboardModule',
data: {
breadcrumb: {
label: 'Home',
info: { myData: { icon: 'home', iconType: 'material' } }
}
}
},
{
path: 'add',
component: MentorAddComponent,
data: { breadcrumb: { skip: true, alias: 'mentorAdd' } }
}
breadcrumb as a function
{
path: '/orders',
children: [{
':id',
data: {
breadcrumb: (resolvedId: string) => `Viewing ${resolvedId} now`
}
}]
}
Update breadcrumb label dynamically
- Breadcrumb label can be updated dynamically using route path or alias
- For simple routes, route path is enough. Ex:
breadcrumbService.set(<route path> , <breadcrumb label>)
- For long deep routes, you can use alias instead.
- Create an alias for a route in route config. Prefix alias with '@' while using the set() method. Ex:
breadcrumbService.set(@<alias> , <breadcrumb label>)
using route path to update labels dynamically
{
path: 'mentors',
component: MentorListComponent,
children: [
{
path: ':id',
component: MentorDetailsComponent
}
]
}
// routepath can contain path params similar to how you define in routes
breadcrumbService.set('mentors', 'Mentor View'); // path for MentorListComponent
breadcrumbService.set('mentor/:id', 'Uday Vunnam'); // path for MentorDetailsComponent contains param (:id)
using alias to update labels dynamically
{
path: 'mentors',
component: MentorListComponent,
children: [
{
path: ':id',
component: MentorDetailsComponent
data: {
breadcrumb: {
alias: 'mentorName'
}
}
}
]
}
breadcrumbService.set('@mentorName', 'Uday Vunnam');
Advanced Patterns
If you looking for customizing breadcrumb in different ways, refer to this guide
API
Detailed API for Breadcrumb Component and Breadcrumb Service
Accessibility
Accessibility is the firstclass concern for this library and is implemented with best practices
Angular version compatibility
xng-breadcrumb works will all versions of Angular. See the compatibility guide
Local Development Guide
If you wish to contribute to this library, refer to the local development guide
Become a Sponsor!
❤️Contributors ✨
Thanks goes to these wonderful people (emoji key):
Uday Vunnam 💻 📖 🚧 |
anthonythiry 💻 |
dedrazer 💻 |
Danny Feliz 📖 |
This project follows the all-contributors specification. Contributions of any kind welcome!