Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dirkluijk/ngx-breadcrumpy
Awesome breadcrumbs for Angular
https://github.com/dirkluijk/ngx-breadcrumpy
Last synced: about 1 month ago
JSON representation
Awesome breadcrumbs for Angular
- Host: GitHub
- URL: https://github.com/dirkluijk/ngx-breadcrumpy
- Owner: dirkluijk
- Created: 2019-09-03T15:11:31.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-01-05T14:33:54.000Z (11 months ago)
- Last Synced: 2024-08-10T06:51:21.912Z (4 months ago)
- Language: TypeScript
- Homepage: https://stackblitz.com/edit/breadcrumpy
- Size: 2.26 MB
- Stars: 5
- Watchers: 1
- Forks: 1
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
- awesome-angular - ngx-breadcrumpy - An awesome library to easily add breadcrumbs to your Angular application. (Table of contents / Third Party Components)
- fucking-awesome-angular - ngx-breadcrumpy - An awesome library to easily add breadcrumbs to your Angular application. (Table of contents / Third Party Components)
README
# Breadcrumpy 🍞
> Awesome breadcrumbs for Angular!
[](https://www.npmjs.com/package/ngx-breadcrumpy)
[](https://www.npmjs.com/package/ngx-breadcrumpy)
[](https://github.com/dirkluijk/ngx-breadcrumpy/actions/workflows/main.yml)
[](#contributors-)
## Overview
### What? 🤔
An awesome library to easily add breadcrumbs to your Angular application.
* Simply add breadcrumb labels to your Angular routing
* It supports asynchronous (reactive) breadcrumbs
* Flexible configuration. However you like to roll!
* ~~Angular Material and PrimeNG examples included~~ (on roadmap)
### Why? 🤷♂️
Existing breadcrumb libraries do not seem to support async (reactive) breadcrumbs.
Also, this library provides many different configuration options.
## Installation 🌩
##### npm
```
npm install ngx-breadcrumpy
```
##### yarn
```
yarn add ngx-breadcrumpy
```
## Usage 🕹
### Basic example
Just add a `breadcrumb` data property to your routes.
```typescript
export const ROUTES: Routes = [
{
path: 'about',
component: AboutComponent,
data: { breadcrumb: 'About' }
},
{
path: 'products',
data: { breadcrumb: 'Products' }
}
];
```
#### a) Use the default breadcrumb component:
Now, import the `BreadcrumbsModule` and add the included breadcrumb component to your template:
```html
```
#### b) Or implement your own:
Alternatively, implement your own breadcrumb component using the `BREADCRUMBS` injection token:
```typescript
import { Component, Inject } from '@angular/core';
import { Observable } from 'rxjs';
import { Breadcrumb, BREADCRUMBS } from 'ngx-breadcrumpy';
@Component({
selector: 'app-breadcrumb',
template: `
{{ b.label }} /
`
})
export class BreadcrumbComponent {
constructor(@Inject(BREADCRUMBS) public breadcrumbs$: Observable) {}
}
```
A breadcrumb contains the following properties:
````typescript
export interface Breadcrumb {
/**
* Label of the breadcrumb.
*/
label: string;
/**
* Icon of the breadcrumb.
*/
icon?: string;
/**
* Url to the breadcrumb (if not loading), if not using RouterLink.
*/
url?: string;
/**
* Url segments to the breadcrumb (if not loading), useful for RouterLink.
*/
urlSegments?: any[];
/**
* True if the breadcrumb is being loaded.
*/
loading?: boolean;
}
````
### Advanced configuration
Instead of static breadcrumbs, you may want to make your breadcrumb labels more dynamic. There are several ways to do this!
The breadcrumb configuration can be of many types:
* `string` (label)
* `BreadcrumbLiteral` (object with `label` and optionally an `icon`)
* `Observable`
* `(route: ActivatedRouteSnapshot) => string`
* `(route: ActivatedRouteSnapshot) => BreadcrumbLiteral`
* `(route: ActivatedRouteSnapshot) => Observable`
* `Type`
Of course you can also make combinations. Please find some examples below.
#### 1. Using functions
A function which returns a `string`, `BreadcrumbLiteral` or `Observable`.
```typescript
export const ROUTES: Routes = [
{
path: 'product/:id',
data: {
breadcrumb: (route: ActivatedRouteSnapshot) => `Product ${route.paramMap.get('id')}`
}
}
];
```
#### 2. Using a BreadcrumbResolver
You can also use a special `BreadcrumbResolver` service to benefit from dependency injection.
The `resolve` method should return either a `string`, `BreadcrumbLiteral` or `Observable`.
Asynchronous observables will not block the routing process, but make the breadcrumb appear when resolved.
```typescript
export const ROUTES: Routes = [
{
path: 'product/:id',
data: { breadcrumb: YourBreadcrumbResolver }
}
];
@Injectable({ providedIn: 'root' })
class YourBreadcrumbResolver implements BreadcrumbResolver {
public resolve(route: ActivatedRouteSnapshot): Observable {
// just some example of an async breadcrumb label...
return of(`Product ${route.paramMap.get('id')}`).pipe(delay(300));
}
}
```
#### 3. Using Resolve guards
If you want to stick with resolve guards from `@angular/router`, you can.
They will will dynamically add the `breadcrumb` property to your route.
```typescript
export const ROUTES: Routes = [
{
path: 'product/:id',
resolve: { breadcrumb: YourResolveGuard }
}
];
@Injectable({ providedIn: 'root' })
class YourResolveGuard implements Resolve {
/* ... */
}
```
NOTE: keep in mind that the resolve guards from Angular Router are blocking! To get around this, use the
previously mentioned `BreadcrumbResolver`. You can also make your guard return
an `Observable>`. Breadcrumpy will automatically support this.
### Using a different route property
Just provide a `BREADCRUMB_KEY` token in your root module to change the default `breadcrumb` property name.
```typescript
import { BREADCRUMB_KEY } from 'ngx-breadcrumpy';
@NgModule({
providers: [
{
provide: BREADCRUMB_KEY,
useValue: 'yourBreadcrumb'
}
]
})
class AppModule {}
```
### Using translations (i18n)
Just implement your [own breadcrumb component](#b-or-implement-your-own) and use translation pipes for your breadcrumb labels.
## Contributors ✨
Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
