{"id":23854758,"url":"https://github.com/Service-Soft/ngx-material-navigation","last_synced_at":"2025-09-08T01:32:21.520Z","repository":{"id":48462849,"uuid":"516914529","full_name":"Service-Soft/ngx-material-navigation","owner":"Service-Soft","description":"Builds material navigation elements like a combined navbar and sidenav or footers based on the supplied configuration data. Will automatically move elements from the navbar to the sidenav at the provided breakpoints.","archived":false,"fork":false,"pushed_at":"2024-11-22T01:25:32.000Z","size":1965,"stargazers_count":2,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"dev","last_synced_at":"2024-11-22T02:24:16.882Z","etag":null,"topics":["angular","angular-material","footer","navbar","navigation"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Service-Soft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-07-22T23:50:41.000Z","updated_at":"2024-11-22T01:25:36.000Z","dependencies_parsed_at":"2024-05-28T18:06:47.568Z","dependency_job_id":"a5820953-b455-4e9d-8df9-3c16818594fb","html_url":"https://github.com/Service-Soft/ngx-material-navigation","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/Service-Soft%2Fngx-material-navigation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Service-Soft%2Fngx-material-navigation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Service-Soft%2Fngx-material-navigation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Service-Soft%2Fngx-material-navigation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Service-Soft","download_url":"https://codeload.github.com/Service-Soft/ngx-material-navigation/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232271882,"owners_count":18497768,"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":["angular","angular-material","footer","navbar","navigation"],"created_at":"2025-01-03T00:01:36.936Z","updated_at":"2025-01-03T00:03:17.334Z","avatar_url":"https://github.com/Service-Soft.png","language":"TypeScript","funding_links":[],"categories":["Third Party Components"],"sub_categories":["UI Libraries built on Material"],"readme":"# NgxMaterialNavigation\n\nBuilds material navigation elements like a combined navbar and sidenav or footers based on the supplied configuration data. Will automatically move elements from the navbar to the sidenav at the provided breakpoints.\n\nSupports nested menus and brings functionality which allow you to extract angular routes from an Configuration if you want to define the routes directly there.\n\n# Table of Contents\n- [NgxMaterialNavigation](#ngxmaterialnavigation)\n- [Table of Contents](#table-of-contents)\n- [Requirements](#requirements)\n- [Basic Usage](#basic-usage)\n  - [Define your configuration](#define-your-configuration)\n  - [Extract the angular routes](#extract-the-angular-routes)\n  - [Use the elements](#use-the-elements)\n  - [Actions and conditions](#actions-and-conditions)\n  - [Dynamic Anchors](#dynamic-anchors)\n- [Custom Components](#custom-components)\n  - [Create the custom component](#create-the-custom-component)\n  - [Use it in your routes](#use-it-in-your-routes)\n- [NavRoute](#navroute)\n- [NgxMatNavigationNotFoundComponent](#ngxmatnavigationnotfoundcomponent)\n# Requirements\nThis package relies on the [angular material library](https://material.angular.io/guide/getting-started) to render its components.\n\n# Basic Usage\n## Define your configuration\n```typescript\nimport { NavbarRow, NavRoute } from 'ngx-material-navigation';\n\n/**\n * The configuration consists of multiple NavbarRows.\n * This is needed if you want to have a toolbar with multiple rows.\n * \n * In most cases you probably only define one NavbarRow in this array.\n * \n * You can also provide a generic type for any angular routes in the elements.\n * This is helpful if you want to have type safety when using the routes data property.\n * Or when you want to enforce that a title/path etc. is required on every route.\n*/\nexport const navbarRows: NavbarRow\u003cNavRoute\u003e[] = [\n    {\n        elements: [\n            {\n                type: NavElementTypes.IMAGE_WITH_INTERNAL_LINK,\n                url: 'https://www.my-great-website.de/my-great-picture.png',\n                link: {\n                    route: 'home',\n                },\n                collapse: 'never'\n            },\n            {\n                type: NavElementTypes.TITLE_WITH_INTERNAL_LINK,\n                title: 'Showcase Project',\n                link: {\n                    route: 'home'\n                },\n                collapse: 'sm'\n            },\n            {\n                type: NavElementTypes.INTERNAL_LINK,\n                name: 'Home',\n                route: { // This can also just be a string.\n                    title: 'Home',\n                    path: 'home',\n                    loadChildren: () =\u003e import('./components/home/home.module').then(m =\u003e m.HomeModule)\n                },\n                collapse: 'md'\n            },\n            {\n                type: NavElementTypes.MENU,\n                name: 'Menu',\n                elements: [\n                    {\n                        type: NavElementTypes.INTERNAL_LINK,\n                        name: 'menu item #1',\n                        route: 'menu-item/1'\n                    },\n                    {\n                        type: NavElementTypes.INTERNAL_LINK,\n                        name: 'menu item #2',\n                        route: 'menu-item/2'\n                    }\n                ],\n                position: 'center',\n                collapse: 'md'\n            },\n            {\n                type: NavElementTypes.BUTTON,\n                name: 'Reload the page',\n                action: () =\u003e location.reload(),\n                position: 'right',\n                collapse: 'sm'\n            }\n        ]\n    }\n];\n```\n## Extract the angular routes\n\u003e :warning: Optional:\n\u003e \u003cbr\u003e\n\u003e You only need this if you want to define your angular routes inside the NavbarRows.\n\u003e \n```typescript\n// Define any additional routes that are not defined in the NavbarRows.\nconst extraRoute: NavRoute = {\n    title: '404 Page not found',\n    path: '**',\n    component: NgxMatNavigationNotFoundComponent,\n    data: { // this is type safe\n        pageNotFoundConfig: {\n            homeRoute: '/home'\n        }\n    }\n};\n// Extract the angular routes from the given configuration. This can be used in the app.routing.module.ts\nexport const routes: NavRoute[] = NavUtilities.getAngularRoutes\u003cNavRoute\u003e(navbarRows, [extraRoute]);\n```\n## Use the elements\nIn app.component.html:\n```html\n\u003cngx-mat-navigation-navbar [minHeight]=\"70\" [minSidenavWidth]=\"'30%'\" [minHeightOtherElements]=\"70\" [navbarRows]=\"navbarRows\"\u003e\n    \u003c!-- The content of your app needs to be put inside the navbar --\u003e\n    \u003crouter-outlet\u003e\u003c/router-outlet\u003e\n\u003c/ngx-mat-navigation-navbar\u003e\n\n\u003capp-footer [minHeight]=\"70\"\u003e\u003c/app-footer\u003e\n```\nPlease note that all of your content needs to be put inside the navbar. This is needed to put it inside the mat-sidenav-content.\n\nThe minHeight and minHeightOtherElements is needed internally to set the min-height of the content accordingly.\n\n## Actions and conditions\nIn your navigation data you can define actions that are executed when a button is clicked.\nYou can also define a condition function which defines whether or not the navigation element should be visible:\n```typescript\n...\n{\n    type: 'button',\n    name: 'Reload the page',\n    action: () =\u003e location.reload(),\n    condition: conditionWithInjection,\n    position: 'right',\n    collapse: 'sm'\n}\n...\n```\nWhen the above button is clicked the current window gets reloaded. For the isUserLoggedIn-function this is a bit more tricky, as normally injections only work inside an angular context. We work around this by using the [EnvironmentInjector](https://angular.io/api/core/EnvironmentInjector), however \u003cb\u003eTHIS REQUIRES YOU TO DEFINE ANY CONDITION AS AN EXTRA FUNCTION\u003c/b\u003e (at least if you want to use injections).\n```typescript\n// This will work:\n...\n{\n    type: 'button',\n    name: 'Reload the page',\n    action: () =\u003e location.reload(),\n    condition: conditionWithInjection,\n    position: 'right',\n    collapse: 'sm'\n}\n...\n\nfunction conditionWithInjection(): boolean {\n    const router = inject(Router);\n    console.log(router.url);\n    return true;\n}\n```\n```typescript\n// This wont work:\n...\n{\n    type: 'button',\n    name: 'Reload the page',\n    action: () =\u003e inject(Router).url.length \u003e 10,\n    condition: conditionWithInjection,\n    position: 'right',\n    collapse: 'sm'\n}\n...\n```\n## Dynamic Anchors\nThis library supports adding anchors (different sections the user can scroll to) dynamically to the navbar.\n\nFirst, define anchor elements in your routes configuration:\n\n```typescript\n{\n    type: NavElementTypes.INTERNAL_LINK,\n    name: 'Scrolling',\n    route: {\n        title: 'Scrolling',\n        path: 'scrolling',\n        loadComponent: () =\u003e import('./components/scrolling/scrolling.component').then(m =\u003e m.ScrollingComponent),\n        data: {\n            anchors: [\n                {\n                    name: 'Bottom',\n                    fragment: 'bottom',\n                    icon: 'fas fa-home'\n                },\n                {\n                    name: 'Middle',\n                    fragment: 'middle'\n                }\n            ]\n        }\n    },\n    collapse: 'md'\n}\n```\nOn the scrolling component there need to be elements with the ids \"bottom\" and \"middle\".\n\nThen configure your routing options:\n\n```typescript\nconst routerOptions: ExtraOptions = {\n    scrollPositionRestoration: 'enabled',\n    onSameUrlNavigation: 'reload',\n    anchorScrolling: 'enabled'\n};\n\n@NgModule({\n    imports: [RouterModule.forRoot(routes, routerOptions)],\n    exports: [RouterModule]\n})\nexport class AppRoutingModule { }\n```\n\nIf you want to enable smooth scrolling you can add\n`html { scroll-behavior: smooth; }` to your styles.scss.\n\n\u003e :warning: No anchor toolbar is shown:\n\n The NgxMatNavigationService handles getting the anchor toolbar from the route configuration by subscribing to `router.events`.\n \n Usually the navbar is used in your app.component.html, which means the service gets initialized and everything should work out of the box. But it could be possible that route navigation happens without the service being initialized.\n \n In that case you need to add the following to your app.module.ts provider array:\n\n ```typescript\n {\n    provide: APP_INITIALIZER,\n    useFactory: () =\u003e {\n        return () =\u003e {};\n    },\n    deps: [NgxMatNavigationService],\n    multi: true\n}\n ```\n\n# Custom Components\nYou have the option to easily add custom components if the provided components don't fully cover your requirements.\n\n## Create the custom component\nThe only restriction for the component is that it needs to extends `NgxMatNavigationBaseNavElementComponent`:\n```typescript\nimport { NavElementTypes, NgxMatNavigationBaseNavElementComponent } from 'ngx-material-navigation';\n\n@Component({\n    selector: 'app-custom',\n    templateUrl: './custom.component.html',\n    styleUrls: ['./custom.component.scss']\n})\nexport class CustomComponent extends NgxMatNavigationBaseNavElementComponent\u003cNavElementTypes.CUSTOM\u003e {}\n```\n\n## Use it in your routes\n```typescript\nimport { NavElementTypes } from 'ngx-material-navigation';\n\n...\n{\n    type: NavElementTypes.CUSTOM,\n    component: CustomComponent\n},\n...\n```\n\n# NavRoute\n```typescript\n/**\n * An opinionated model of the Angular Route.\n * This makes the title and path attributes required.\n * It also adds the option to use a generic for the route data.\n */\nexport interface NavRoute\u003cDataType extends Data = DefaultNavRouteDataType\u003e extends Route {\n    title: string | Type\u003cResolve\u003cstring\u003e\u003e | ResolveFn\u003cstring\u003e,\n    path: string,\n    data?: DataType\n}\n\n/**\n * The default data type for a nav route.\n * Will be used if no generic is provided.\n */\nexport interface DefaultNavRouteDataType extends Data {\n    /**\n     * The configuration for the 404 page not found component.\n     */\n    pageNotFoundConfig?: PageNotFoundConfig\n}\n```\n# NgxMatNavigationNotFoundComponent\nThis is a simple 404-Error Page that can be used in your routing:\n```typescript\nimport { PageNotFoundConfig, NavRoute, NgxMatNavigationNotFoundComponent } from 'ngx-material-navigation';\n\nconst pageNotFoundConfig: PageNotFoundConfig = {\n    title?: string,\n    message?: string,\n    buttonLabel?: string,\n    homeRoute?: string\n}\n\nconst pageNotFoundRoute: NavRoute = {\n    title: '404 Page not found',\n    path: '**',\n    component: NgxMatNavigationNotFoundComponent,\n    data: {\n        // this is optional for overriding the default values. When using NavRoute this is also type safe.\n        pageNotFoundConfig: pageNotFoundConfig\n    }\n};\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FService-Soft%2Fngx-material-navigation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FService-Soft%2Fngx-material-navigation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FService-Soft%2Fngx-material-navigation/lists"}