{"id":18142390,"url":"https://github.com/fboeller/ngx-loading-customizer","last_synced_at":"2025-07-13T19:08:04.811Z","repository":{"id":118094257,"uuid":"345397752","full_name":"fboeller/ngx-loading-customizer","owner":"fboeller","description":"Angular Loading Customizer is a library that helps you represent and show data that is loaded from an external source.","archived":false,"fork":false,"pushed_at":"2021-03-08T19:29:39.000Z","size":941,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-22T19:06:36.655Z","etag":null,"topics":["angular","loading"],"latest_commit_sha":null,"homepage":"https://fboeller.github.io/ngx-loading-customizer","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/fboeller.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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,"zenodo":null}},"created_at":"2021-03-07T16:36:53.000Z","updated_at":"2021-03-16T22:09:42.000Z","dependencies_parsed_at":null,"dependency_job_id":"12ebd03d-9abf-466a-b7fb-99d57ac37ffd","html_url":"https://github.com/fboeller/ngx-loading-customizer","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/fboeller/ngx-loading-customizer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fboeller%2Fngx-loading-customizer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fboeller%2Fngx-loading-customizer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fboeller%2Fngx-loading-customizer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fboeller%2Fngx-loading-customizer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fboeller","download_url":"https://codeload.github.com/fboeller/ngx-loading-customizer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fboeller%2Fngx-loading-customizer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265191192,"owners_count":23725278,"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","loading"],"created_at":"2024-11-01T18:06:46.008Z","updated_at":"2025-07-13T19:08:04.798Z","avatar_url":"https://github.com/fboeller.png","language":"TypeScript","readme":"# Angular Loading Customizer\n\n![License](https://img.shields.io/github/license/fboeller/ngx-loading-customizer) ![Build](https://img.shields.io/github/workflow/status/fboeller/ngx-loading-customizer/CI) [![codecov](https://codecov.io/gh/fboeller/ngx-loading-customizer/branch/main/graph/badge.svg?token=QMQFX7H9CP)](https://codecov.io/gh/fboeller/ngx-loading-customizer) ![Version](https://img.shields.io/npm/v/ngx-loading-customizer)\n\nAngular Loading Customizer is a library that helps you represent and show data that needs to be loaded from a backend and can therefore be in a loading state.\n\n- **Loadable type** - The type `Loadable\u003cT\u003e` lets you represent the full state of your loading data with a single object. No more additional booleans passed to your components.\n- **Loadable component** - The component `ld-loadable` shows your loaded data, a loading animation or an error state depending on the state of the loadable object.\n- **Global defaults** - You can define a default custom loading animation and a default custom error state globally per lazy-loaded module. Once you want to refine the individual loading animations per loaded data, you can simply define local loading animations that overrule the default.\n- **Observable and NgRx Compatibility** - Both the loadable type and loadable component integrate well with observables and NgRx. Via the operator `toLoadable` a loadable can be extracted from an observable.\n- **No dependencies** — Besides Angular this library does not have any dependencies.\n\n## Installation\n\n```\nnpm install --save ngx-loading-customizer\n```\n\n## Try it\n\nThis repo includes an example application showcasing the usage of ngx-loading-customizer.\n\nIt is hosted at https://fboeller.github.io/ngx-loading-customizer.\n\nYou can also work with it locally:\n\n```\n$ git clone https://github.com/fboeller/ngx-loading-customizer.git\n$ cd ngx-loading-customizer\n$ npm install\n$ npm start example-app\n```\n\n## Usage\n\n### Construct a loadable\n\nGiven an observable, you can construct a loadable with the operator `toLoadable`.\n\n```typescript\nimport { toLoadable } from \"ngx-loading-customizer\";\nimport { of } from \"rxjs\";\n\nconst loadable$ = of({ id: 42 }).pipe(toLoadable);\n```\n\n### Display a loadable\n\nIf you have an object of type `Loadable\u003cT\u003e`, you can display it with the `ld-loadable` component.\n\nFirst, make sure to import the `LoadingCustomizerModule` in your module.\n\n```typescript\nimport { NgModule } from \"@angular/core\";\nimport { LoadingCustomizerModule } from \"ngx-loading-customizer\";\nimport { CommonModule } from \"@angular/common\";\n\n@NgModule({\n  imports: [LoadingCustomizerModule],\n})\nexport class AppModule {}\n```\n\nDefine a loadable object in your component.\nYou can use `idle`, `loading`, `loaded('value')` and `errored('error')` to construct a loadable.\n\n```typescript\nimport { Component } from \"@angular/core\";\nimport { idle, Loadable } from \"ngx-loading-customizer\";\n\n@Component({\n  selector: \"app-some\",\n  templateUrl: \"./some.component.html\",\n})\nexport class SomeComponent {\n  loadable: Loadable\u003cobject\u003e = idle;\n}\n```\n\nThen, you can display the loadable by passing it as input to the `ld-loadable` component and by defining the template for the `loaded` state.\nWith the pipe `loadedValue` you can extract the loaded value from the loadable.\n\n```html\n\u003cld-loadable [loadable]=\"loadable\"\u003e\n  \u003cp\u003eLoaded\u003c/p\u003e\n  \u003cpre\u003e{{ loadable | loadedValue | json }}\u003c/pre\u003e\n\u003c/ld-loadable\u003e\n```\n\nNote that this inner template is only rendered in the `loaded` state and this example defaults to the standard loading animation and error state.\n\n### Define a custom default loading animation\n\nYou can define a custom default loading animation within your application.\nNote that the way Angular providers work, these defaults are global within your lazy-loaded module.\n\nCreate your custom loading animation component and pass it to the `LoadingCustomizerModule`. Each `ld-loadable` component now defaults to this loading animation component.\n\n```typescript\nimport { NgModule } from \"@angular/core\";\nimport { LoadingCustomizerModule } from \"ngx-loading-customizer\";\nimport { CustomLoadingAnimationComponent } from \"./custom-loading-animation.component\";\n\n@NgModule({\n  declarations: [CustomLoadingAnimationComponent],\n  imports: [\n    LoadingCustomizerModule.forRoot({\n      defaultComponents: {\n        loading: CustomLoadingAnimationComponent,\n      },\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\nNote that you can use the same mechanism to change the default error state.\nHowever, the component you define for that needs to define an input `error` accepting any type.\n\n### Define a custom local loading animation\n\nIn cases where you would like to refine the loading animation for the concrete usage of an `ld-loadable`, you can define and pass a loading template to the component.\n\n```html\n\u003cld-loadable [loadable]=\"loadable\" [templates]=\"{ loading: loading }\"\u003e\n  \u003ch3\u003eLoaded\u003c/h3\u003e\n  \u003cpre\u003e{{ loadable | loadedValue | json }}\u003c/pre\u003e\n\u003c/ld-loadable\u003e\n\u003cng-template #loading\u003e\n  \u003cp\u003eThe answer is currently being computed.\u003c/p\u003e\n\u003c/ng-template\u003e\n```\n\n### Define a custom error state\n\nTo display a custom error state, you can use the same mechanism as for custom loading animation.\nThe template of a custom error state can optionally accept and display the error.\n\n```html\n\u003cld-loadable [loadable]=\"loadable\" [templates]=\"{ error: error }\"\u003e\n  \u003ch3\u003eLoaded\u003c/h3\u003e\n  \u003cpre\u003e{{ loadable | loadedValue | json }}\u003c/pre\u003e\n\u003c/ld-loadable\u003e\n\u003cng-template #error let-error=\"error\"\u003e\n  \u003cp\u003eThere has been an error: {{ error | json }}\u003c/p\u003e\n\u003c/ng-template\u003e\n```\n\n### Change the presentation of the idle state\n\nA loadable is in the idle state before any loading has started.\nIn this state, the `ld-loadable` component does not render anything by default, leading to a white page.\nIn case you would like to show a loading animation immediately, you can change the default behavior.\n\n```typescript\nimport { NgModule } from \"@angular/core\";\nimport { LoadingCustomizerModule } from \"ngx-loading-customizer\";\nimport { LoadableLoadingComponent } from \"ngx-loading-customizer\";\n\n@NgModule({\n  imports: [\n    LoadingCustomizerModule.forRoot({\n      defaultComponents: {\n        idle: LoadableLoadingComponent,\n      },\n    }),\n  ],\n})\nexport class AppModule {}\n```\n\n### Transform a loadable\n\nA loadable is a functional data structure.\nIt defines some utility functions to work with it.\n\nIf you have a loadable and want to change its value once it is loaded, you can use `map`.\n\n```typescript\nimport { map, loaded } from \"ngx-loading-customizer\";\nconst loadable = loaded(5);\nconst result = map((x) =\u003e x + 10, loadable); // loaded(15)\n```\n\nIf you have a loadable and want to map it to another loadable once it is loaded, you can use `flatMap`.\n\n```typescript\nimport { flatMap, loaded } from \"ngx-loading-customizer\";\nconst loadable = loaded(5);\nconst result = flatMap((x) =\u003e loaded(x + 10), loadable); // loaded(15)\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffboeller%2Fngx-loading-customizer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffboeller%2Fngx-loading-customizer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffboeller%2Fngx-loading-customizer/lists"}