{"id":17605569,"url":"https://github.com/code-workers-io/ngx-breadcrumb","last_synced_at":"2025-03-09T03:31:36.342Z","repository":{"id":64869485,"uuid":"568161967","full_name":"code-workers-io/ngx-breadcrumb","owner":"code-workers-io","description":"A highly customizable and flexible breadcrumb component for Angular","archived":false,"fork":false,"pushed_at":"2023-06-23T10:51:22.000Z","size":1600,"stargazers_count":2,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-02-26T09:41:42.391Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://green-meadow-01c14fc03.2.azurestaticapps.net/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/code-workers-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-11-19T16:38:38.000Z","updated_at":"2024-10-21T23:39:31.000Z","dependencies_parsed_at":"2023-01-31T14:45:28.661Z","dependency_job_id":null,"html_url":"https://github.com/code-workers-io/ngx-breadcrumb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-workers-io%2Fngx-breadcrumb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-workers-io%2Fngx-breadcrumb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-workers-io%2Fngx-breadcrumb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/code-workers-io%2Fngx-breadcrumb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/code-workers-io","download_url":"https://codeload.github.com/code-workers-io/ngx-breadcrumb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242180903,"owners_count":20085261,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-22T15:01:15.206Z","updated_at":"2025-03-09T03:31:36.333Z","avatar_url":"https://github.com/code-workers-io.png","language":"TypeScript","funding_links":[],"categories":["Table of contents"],"sub_categories":["Third Party Components"],"readme":"# ngx-breadcrumb\n\n- ✅ Easy styling of default breadcrumb via CSS custom properties\n- ✅ Customize breadcrumb separator via string or custom template\n- ✅ Customize breadcrumb via template\n- ✅ Focus on DX\n\n## Installation\n\n```bash\nnpm install --save @code-workers.io/ngx-breadcrumb\n```\n\n## Demo\nA live demo is available at [go to demo](https://green-meadow-01c14fc03.2.azurestaticapps.net/)\n## Usage\n\n### Import the `NgxBreadcrumbModule` module into your AppModule\n\n\u003e You must import the `NgxBreadcrumbModule` into lazy-loaded modules, too.\n\u003e Otherwise, no breadcrumbs will be rendered for the sub-routes of the\n\u003e lazy-loaded module.\n\n```typescript\n// app.module.ts\n\nimport { NgxBreadcrumbModule } from '@code-workers.io/ngx-breadcrumb';\n\n@NgModule({\n  imports: [NgxBreadcrumbModule],\n})\nexport class AppModule {}\n```\n\n### Provide Breadcrumbs\n\n#### Setup breadcrumb data in your route configuration\n\n```typescript\n// app-routing.module.ts\n\nconst routes: Routes = [{ path: 'example', data: { breadcrumb: 'Example' } }];\n\n@NgModule({\n  imports: [RouterModule.forRoot(routes)],\n  exports: [RouterModule],\n})\nexport class AppRoutingModule {}\n```\n\n#### Implement the `BreadcrumbProvider` interface (Optional)\n\n\u003e Some components need a dynamic breadcrumb label, e.g. editor components.\n\u003e Such components may implement the `BreadcrumbProvider` interface and offer\n\u003e dynamic breadcrumb data to the `BreadcrumbService`.\n\n```typescript\n// my-editor.component.ts\n\n@Component(...)\nexport class MyEditorComponent implements BreadcrumbProvider {\n    getBreadcrumb(): BreadcrumbData {\n      return {\n        label: ..., // this could be a string or an observable, e.g. from ReactiveForm controls\n        link: ... // this could be `false` to disable linking or a external url (or a different route...)\n      };\n    }\n}\n```\n\n### Provide root breadcrumb(s)\n\nRoot breadcrumb(s) are breadcrumbs which are rendered in front of the breadcrumbs dervived from the route. This\ncan e.g. be a \"home\"-breadcrumb.\n\nYou can provide root breadcrumbs either programmatically or by configuration.\n\n#### Programmatically\n\n```typescript\n// app.component.ts\n// ...\nconstructor(private breadcrumbProviderService: NgxBreadcrumbProviderService) {\n  this.breadcrumbProviderService.setRootBreadcrumbs([\n    { label: 'Home', link: '/' }\n  ]);\n}\n```\n\n#### Configuration\n\n```typescript\n// app.module.ts\n@NgModule({\n  imports: [\n    NgxBreadcrumbModule.withConfig({\n      stickyRoot: [new Breadcrumb('Home', '/'), new Breadcrumb('Home1', '/')],\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\n#### Provide a root breadcrumb component\n\nYou can provide a root breadcrumb component which will be rendered in front of the breadcrumbs dervived from the route.\n\nSimply configure it in your `app.module.ts`:\n\n```typescript\nNgxBreadcrumbModule.withConfig({\n  stickyRootComponent: {\n    component: RootBreadcrumbComponent,\n    data: {\n      label: 'Home',\n      link: '/'\n    }\n  }\n})\n\n// component\n@Component({\n  selector: 'root-breadcrumb',\n  template: `\n    \u003csvg\n      (click)=\"onClick()\"\n      cursor=\"pointer\"\n      xmlns=\"http://www.w3.org/2000/svg\"\n      height=\"24\"\n      width=\"24\"\n    \u003e\n      \u003cpath\n        d=\"M6 19h3v-6h6v6h3v-9l-6-4.5L6 10Zm-2 2V9l8-6 8 6v12h-7v-6h-2v6Zm8-8.75Z\"\n      /\u003e\n    \u003c/svg\u003e\n  `,\n  styles: [\n    `\n      :host {\n        display: grid;\n        place-items: center;\n        width: 24px;\n        height: 24px;\n        border: 1px solid #e2e8f0;\n        border-radius: 100%;\n        background-color: #e2e8f0;\n        padding: 8px;\n      }\n    `,\n  ]\n})\nexport class RootBreadcrumbComponent implements StickyBreadcrumbComponent {\n  click: EventEmitter\u003cvoid\u003e = new EventEmitter\u003cvoid\u003e()\n\n  constructor(private router: Router) {}\n\n  getBreadcrumb(): BreadcrumbData {\n    return {\n      label: 'Home',\n      link: '/',\n    };\n  }\n\n  onClick() {\n    this.click.emit(void 0)\n  }\n}\n```\n\nNote: you need to implement the `StickyBreadcrumbComponent`-interface so that it will work properly.\n\n### Additional info on Route setup\n\nFor static breadcrumb configuration, you have to provide the required data with the route setup.\nTherefore add a `breadcrumb` segment to the Route's `data` attribute.\n\nThe `breadcrumb` attribute may be\n\n- a boolean value (if data.breadcrumb === false, no breadcrumb will be generated for that route)\n- a string value (string will be taken for breadcrumb label)\n- a `BreadcrumbData` object\n\nWhen providing a `BreadcrumbData` object, you may use the `BreadcrumbData.link` attribute\nto either suppress linking of the breadcrumb (text-only) or to specify a deviating url.\n\nFor dynamic breadcrumb configuration, your routed components may implement the `BreadcrumbProvider`\ninterface in order to provide breadcrumb data which overrides the route configuration.\n\n```typescript\nconst routes: Routes = [\n  // Routed component does NOT implement the BreadcrumbProvider interface:\n\n  // don't generate a breadcrumb for this route (as there's no label to display)\n  { path: 'example', component: ExampleComponent },\n  {\n    path: 'example',\n    component: ExampleComponent,\n    data: { breadcrumb: true },\n  },\n\n  // don't generate a breadcrumb for this route (as it has been disabled explicitly)\n  {\n    path: 'example',\n    component: ExampleComponent,\n    data: { breadcrumb: false },\n  },\n\n  // generate a regular breadcrumb with label \"Example\"\n  {\n    path: 'example',\n    component: ExampleComponent,\n    data: { breadcrumb: 'Example' },\n  },\n  {\n    path: 'example',\n    component: ExampleComponent,\n    data: { breadcrumb: { label: 'Example' } },\n  },\n  {\n    path: 'example',\n    component: ExampleComponent,\n    data: { breadcrumb: { label: 'Example', link: true } },\n  },\n\n  // generate a label-only breadcrumb with label \"Example\"\n  {\n    path: 'example',\n    component: ExampleComponent,\n    data: { breadcrumb: { label: 'Example', link: false } },\n  },\n\n  // generate a breadcrumb with label \"Example\" linking to an external url\n  {\n    path: 'example',\n    component: ExampleComponent,\n    data: { breadcrumb: { label: 'Example', link: 'http://example.com' } },\n  },\n\n  // Routed component DOES implement the BreadcrumbProvider interface\n\n  // generate a breadcrumb with data provided by the component\n  { path: 'example', component: ExampleBreadcrumbProviderComponent },\n  {\n    path: 'example',\n    component: ExampleBreadcrumbProviderComponent,\n    data: { breadcrumb: true },\n  },\n\n  // don't generate a breadcrumb for this route (as it has been disabled explicitly)\n  {\n    path: 'example',\n    component: ExampleBreadcrumbProviderComponent,\n    data: { breadcrumb: false },\n  },\n\n  // generate a breadcrumb; merge the 'label' attribute from route data and component data\n  // breadcrumb data from component has precedence over breadcrumb data from route\n  {\n    path: 'example',\n    component: ExampleBreadcrumbProviderComponent,\n    data: { breadcrumb: 'Example' },\n  },\n  {\n    path: 'example',\n    component: ExampleBreadcrumbProviderComponent,\n    data: { breadcrumb: { label: 'Example' } },\n  },\n  {\n    path: 'example',\n    component: ExampleBreadcrumbProviderComponent,\n    data: { breadcrumb: { label: 'Example', link: true | false } },\n  },\n];\n```\n\n### Futher configuration\n\nThe NgxBreadcrumbModule`accepts the`NgxBreadcrumbConfig` configuration-object:\n\n- `breadcrumbCount.fixedLead`: number of visible leading breadcrumbs. Default: 1.\n- `breadcrumbCount.fixedTail`: number of visible trailing breadcrumbs. Default: 2.\n\nWith this configuration you can control the number of breadcrumbs which are rendered. Breadcrumbs in\nbetween are just rendered as dots.\n\n# Customization\n\nThere are two ways to for customization: via `ng-template` and/or via CSS custom properties\n\n### Customization via `ng-template`\n\n#### Breadcrumb customization\n\n```html\n\u003cngx-breadcrumbs [breadcrumbTemplate]=\"bc\"\u003e\u003c/ngx-breadcrumbs\u003e\n\n\u003cng-template #bc let-last=\"last\" let-crumb\u003e {{crumb.label}} \u003c/ng-template\u003e\n```\n\n#### Breadcrumb separator customization\n\n```html\n\u003cngx-breadcrumbs [separatorTemplate]=\"sep\"\u003e\u003c/ngx-breadcrumbs\u003e\n\n\u003cng-template #sep\u003e // \u003c/ng-template\u003e\n```\n\n## Customization via CSS custom properties\n\nAvailable CSS custom properties:\n\nThe `breadcrumb-container`\n\n- `--ngx-breadcrumb-container-padding`: padding of the breadcrumb container. Default: `0.5rem`.\n- `--ngx-breadcrumb-container-margin`: the margin of the breadcrumb container.\n- `--ngx-breadcrumb-container-bg-color`: the background color of the breadcrumb container.\n- `--ngx-breadcrumb-gap-between`: gap between breadcrumbs. Default: `0.5rem`.\n- `--ngx-breadcrumb-container-width`: the width of the breadcrumb container. Default: `fit-content`.\n- The `breadcrumb` itself:\n- `--ngx-breadcrumb-padding`: padding of the breadcrumb. Default: `0.5rem`.\n- `--ngx-breadcrumb-margin`: the margin of the breadcrumb.\n- `--ngx-breadcrumb-bg-color`: the background color of the breadcrumb.\n- `--ngx-breadcrumb-border`: the border of the breadcrumb. Default: `none`.\n- `--ngx-breadcrumb-border-radius`: the border-radius of the breadcrumb. Default: `0`.\n- `--ngx-breadcrumb-link-decoration`: the text-decoration of the breadcrumb link. Default: `none`.\n\nThe separator container:\n\n- `--ngx-separator-container-height`: the height of the separator container. Default: `100%`.\n- `--ngx-separator-container-width`: the width of the separator container. Default: `auto`.\n- `--ngx-separator-container-padding`: the padding of the separator container. Default: `0`.\n- `--ngx-separator-container-margin`: the margin of the separator container. Default: `0`.\n- `--ngx-separator-container-bg-color`: the background color of the separator container. Default: `inherit`.\n\nThe separator-icon between breadcrumbs:\n\n- `--ngx-separator-icon-color`: the color of the separator icon. Default: `black`.\n- `--ngx-separator-icon-height`: the height of the separator icon. Default: `24px`.\n- `--ngx-separator-icon-width`: the width of the separator icon. Default: `24px`.\n\nSee Demo for examples.\n\n## Translate Breadcrumbs\n\nTo translate the breadcrums you only need to provide the `NGX_TRANSLATION_ADAPTER` token with an\nimplementation of the `NgxBreadcrumbTranslationAdapter`-interface. You can choose any translation\nlibrary of your choice.\n\n```typescript\nimport { TranslateService } from '@ngx-translate/core';\n@Injectable({\n  providedIn: 'root',\n})\nexport class MyTranslationAdapter implements NgxBreadcrumbTranslationAdapter {\n  constructor(private translateService: TranslateService) {}\n\n  translate(key: string): string {\n    return this.translateService.instant(key);\n  }\n}\n\n// app.module.ts\n\n\n@NgModule({\n  providers: [{provide: NGX_TRANSLATION_ADAPTER, useExisting: MyTranslationAdapter }],\n})\nexport class AppModule {}\n```\n\n## Compatibility\n\nThe versions align with the Angular versions. This means version 13.x.x of this library is compatible with Angular 13.x.x. or greater.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-workers-io%2Fngx-breadcrumb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcode-workers-io%2Fngx-breadcrumb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcode-workers-io%2Fngx-breadcrumb/lists"}