{"id":13497379,"url":"https://github.com/kuuurt13/ng-block-ui","last_synced_at":"2025-03-28T21:32:25.906Z","repository":{"id":17829091,"uuid":"82624825","full_name":"kuuurt13/ng-block-ui","owner":"kuuurt13","description":"Block UI Loader/Spinner for Angular","archived":false,"fork":false,"pushed_at":"2023-12-01T02:47:26.000Z","size":2679,"stargazers_count":144,"open_issues_count":17,"forks_count":24,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-04-14T07:47:58.344Z","etag":null,"topics":["angular","block-ui","blocking","loader","loading","spinner"],"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/kuuurt13.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}},"created_at":"2017-02-21T02:06:51.000Z","updated_at":"2024-03-27T13:51:50.000Z","dependencies_parsed_at":"2024-01-16T09:55:58.279Z","dependency_job_id":"a626a5d1-5910-4489-b0ae-56d6884fcbdb","html_url":"https://github.com/kuuurt13/ng-block-ui","commit_stats":{"total_commits":228,"total_committers":15,"mean_commits":15.2,"dds":0.08333333333333337,"last_synced_commit":"594eae6a2598e052d5f7be1ddeb4764224c58e70"},"previous_names":[],"tags_count":76,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuuurt13%2Fng-block-ui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuuurt13%2Fng-block-ui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuuurt13%2Fng-block-ui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kuuurt13%2Fng-block-ui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kuuurt13","download_url":"https://codeload.github.com/kuuurt13/ng-block-ui/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246105583,"owners_count":20724334,"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","block-ui","blocking","loader","loading","spinner"],"created_at":"2024-07-31T20:00:30.062Z","updated_at":"2025-03-28T21:32:25.355Z","avatar_url":"https://github.com/kuuurt13.png","language":"TypeScript","funding_links":[],"categories":["Uncategorized","Table of contents"],"sub_categories":["Uncategorized","Third Party Components"],"readme":"# NG Block UI\n\nA Block UI implementation for Angular\n\n[![npm](https://img.shields.io/npm/v/ng-block-ui.svg)](https://www.npmjs.com/package/ng-block-ui)\n[![npm](https://img.shields.io/npm/v/ng-block-ui/next)](https://www.npmjs.com/package/ng-block-ui/v/next)\n[![npm](https://img.shields.io/npm/dm/ng-block-ui.svg)](https://www.npmjs.com/package/ng-block-ui)\n[![Build Status](https://travis-ci.org/kuuurt13/ng-block-ui.svg?branch=master)](https://travis-ci.org/kuuurt13/ng-block-ui)\n\n## Installation\n\nAdd to your project via [npm](https://www.npmjs.com/package/ng-block-ui)\n\n```bash\nnpm install ng-block-ui --save\n```\n\nInclude the `BlockUIModule` in your main app module.\n\n```ts\n// All other imports\nimport { BlockUIModule } from 'ng-block-ui';\n\n@NgModule({\n  imports: [\n    BlockUIModule.forRoot()\n  ],\n  ...\n})\nexport class AppModule { }\n```\n\n## Quick Start\n\nWrap your main components in your app root template with a `block-ui` component.\n\nImport the `BlockUI` decorator into your component and declare a property with the decorator.\nThis decorator will auto wire this property to the main Block UI instance of your app.\n\nTo start blocking your app, simply invoke the `start` method.\nThis method also can take a custom message to display while blocking.\nOnce finished call the `stop` method to stop blocking the app.\n\n```ts\nimport { Component } from '@angular/core';\n\n// Import BlockUI decorator \u0026 optional NgBlockUI type\nimport { BlockUI, NgBlockUI } from 'ng-block-ui';\n\n@Component({\n  selector: 'app-root',\n  template: `\n    \u003cblock-ui\u003e\n      \u003c!-- Your app markup here --\u003e\n    \u003c/block-ui\u003e\n  `\n})\nexport class AppComponent {\n  // Decorator wires up blockUI instance\n  @BlockUI() blockUI: NgBlockUI;\n\n  constructor() {\n    this.blockUI.start('Loading...'); // Start blocking\n\n    setTimeout(() =\u003e {\n      this.blockUI.stop(); // Stop blocking\n    }, 2000);\n  }\n```\n\n### Current Release\n\nFor more information and/or migrating to the newest version see [Releases](./RELEASES.md).\n\n## Settings\n\nSettings can be changed on the module level and component/directive level. Also, in some cases settings can be overwritten via the method level.\n\n### Default Message\n\nA default message can be configured to be shown instead of passing a message each time to the `start` method. The default message will be shown any time blocking is activated.\n\n| Setting   | Type     | Description                                    |\n| --------- | -------- | ---------------------------------------------- |\n| `message` | `string` | Custom message to be displayed while blocking. |\n\n#### Module Level\n\n```ts\n@NgModule({\n  imports: [\n    BlockUIModule.forRoot({\n      message: 'Default Message'\n    })\n  ],\n  ...\n})\nexport class AppModule { }\n```\n\n#### Component Level\n\n```html\n\u003cblock-ui message=\"Default Message\"\u003e\n  \u003c!-- Markup here --\u003e\n\u003c/block-ui\u003e\n```\n\n#### Method Level\n\n```ts\n@Component({\n  ...,\n  template: `\n    \u003cblock-ui message=\"Default Message\"\u003e\n      \u003c!-- Your markup here --\u003e\n    \u003c/block-ui\u003e\n  `\n})\nexport class Cmp {\n  @BlockUI() blockUI: NgBlockUI;\n\n  defaultMessage() {\n    this.blockUI.start(); // \"Default Message\" will display\n  }\n\n  customMessage() {\n    this.blockUI.start('Updating...'); // \"Updating...\" will display\n  }\n}\n```\n\n### Delay Start/Stop\n\nWhen blocking with fast service calls the block overlay can flicker for a small amount of time.\nTo prevent this a `delayStart` and a `delayStop` can be configured to prevent this scenario.\n\n| Setting      | Type     | Description                                                       |\n| ------------ | -------- | ----------------------------------------------------------------- |\n| `delayStart` | `number` | Waits given amount of milliseconds before starting to block.      |\n| `delayStop`  | `number` | Waits given amount of milliseconds before stopping current block. |\n\n#### Module Level\n\n```ts\n@NgModule({\n  imports: [\n    BlockUIModule.forRoot({\n      delayStart: 500,\n      delayStop: 500\n    })\n  ],\n  ...\n})\nexport class AppModule { }\n```\n\n#### Component Level\n\n```html\n\u003cblock-ui [delayStart]=\"500\" [delayStop]=\"500\"\u003e\n  \u003c!-- Your app markup here --\u003e\n\u003c/block-ui\u003e\n```\n\n### Custom Template\n\nIf you want to display other markup than the default spinner and message then you can provide a custom template.\nCustom templates can be provided as a `Component` or `TemplateRef`. The template will then be used instead of the default template whenever blocking.\n\n| Setting    | Type                                      | Description                              |\n| ---------- | ----------------------------------------- | ---------------------------------------- |\n| `template` | \u003ccode\u003eComponent \u0026#124; TemplateRef\u003c/code\u003e | Custom template to be used when blocking |\n\n#### Component Custom Template\n\nCreate a component and declare it in your app module.\nThe component also will need to be added to the `entryComponents` property of the module.\n\n_Example Component:_\n\n_Note: When providing a `Component` as a template just add the `{{message}}`\ninterpolation to your template and it will display your default message or the message passed to the `start` method._\n\n```ts\n// Template component\n// Use block-ui-template class to center div if desired\n@Component({\n  template: `\n    \u003cdiv class=\"block-ui-template\"\u003e\n      \u003cimg src=\"logo.png\" /\u003e\n      \u003cp\u003e{{ message }}\u003c/p\u003e\n    \u003c/div\u003e\n  `,\n})\nexport class BlockTemplateCmp {}\n```\n\n##### Module Level\n\n```ts\n@NgModule({\n  imports: [\n    BlockUIModule.forRoot({\n      template: BlockTemplateCmp\n    })\n  ],\n  declarations: [\n    ...,\n    BlockTemplateCmp // Declare template component\n  ],\n  entryComponents: [ BlockTemplateCmp ]\n})\nexport class AppModule { }\n```\n\n##### Component Level\n\n```ts\n@Component({\n  selector: \"app-root\",\n  template: `\n    \u003cblock-ui [template]=\"blockTemplate\"\u003e\n      \u003c!-- Your markup here --\u003e\n    \u003c/block-ui\u003e\n  `,\n})\nexport class AppComponent {\n  // Declare template component\n  blockTemplate: BlockTemplateCmp = BlockTemplateCmp;\n}\n```\n\n#### TemplateRef Custom Template\n\nAdd a `\u003cng-template\u003e` with a template reference variable to the view. Then pass the template reference variable to the `blockUI` component using the `[template]` property.\n\n_Note: TemplateRef templates can only be set on a Component level._\n\n##### Component Level\n\n```ts\n@Component({\n  selector: \"cmp\",\n  template: `\n    \u003cng-template #blockTemplate\u003e\n      \u003cdiv class=\"block-ui-template\"\u003e\n        \u003cimg src=\"logo.png\" /\u003e\n      \u003c/div\u003e\n    \u003c/ng-template\u003e\n\n    \u003cblock-ui [template]=\"blockTemplate\"\u003e\n      \u003c!-- Your app markup here --\u003e\n    \u003c/block-ui\u003e\n  `,\n})\nexport class Cmp {}\n```\n\n## Block UI Directive\n\nSometimes you want to only apply blocking to a certain element in your app.\nThe Block UI directive can be added to an element to apply blocking only to that specific element.\n\nAdd the `*blockUI` structural directive to any element\nand pass it an instance name `*blockUI=\"'contact-list'\"`.\n\nThen in a component create a class property using the Block UI decorator with the instance name `@BlockUI('contact-list')`. This will then take care of wiring up that property to point to that specific instance in your app.\n\n```ts\n@Component({\n  selector: 'app-cmp',\n  template: `\n    \u003cdiv\u003e\n      \u003cdiv *blockUI=\"'contact-list'\"\u003e\n        \u003c!-- List markup --\u003e\n      \u003c/div\u003e\n    \u003c/div\u003e\n  `\n})\nexport class AppComponent {\n  // Pass instance name to decorator\n  @BlockUI('contact-list') blockUIList: NgBlockUI;\n\n  constructor() {\n    this.blockUIList.start('Loading...'); // Start blocking element only\n    this.blockUIList.stop(); // Stop blocking\n  }\n```\n\n### Directive Settings\n\nAngular has a specific syntax for passing properties to structural directives. Properties are passed in `key: value;` pair. To pass settings to a Block UI directive they must be passed as shown below.\n\n```html\n\u003cdiv\n  *blockUI=\"'instance-name'; message: 'Loading'; template: blockTemplate\"\n\u003e\u003c/div\u003e\n```\n\n## NgBlockUI Instance\n\n### NgBlockUI Instance Properties\n\nBelow highlights all the properties that can be found on a BlockUI instance when a class property is decorated with the `@BlockUI()` decorator.\n\n| Property      | Description                                                                                                                          |\n| ------------- | ------------------------------------------------------------------------------------------------------------------------------------ |\n| `name`        | Name of the targeted instance (defaults to main instance).                                                                           |\n| `isActive`    | Indicates if the targeted instance is blocking.                                                                                      |\n| `start`       | Starts blocking for instance, can be passed an optional message.                                                                     |\n| `stop`        | Stops blocking for instance.                                                                                                         |\n| `reset`       | Stops blocking for all targeted instances regardless of the `delayStop` option.                                                      |\n| `resetGlobal` | Stops blocking app wide for all instances regardless of the `delayStop` option.                                                      |\n| `update`      | Updates current instances blocking message with the passed message.                                                                  |\n| `unsubscribe` | Unsubscribe an instance so it no longer can be blocked. All BlockUI components/directives unsubscribe by default during `onDestroy`. |\n\n### NgBlockUI Instance Settings\n\nBelow are all the settings that can be passed as a second argument to the `@BlockUI()` decorator (`@BlockUI(\u003cname\u003e, \u003csettings\u003e)`).\n\n| Property          | Description                                                                                                                      |\n| ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |\n| `scopeToInstance` | When set to `true` a unique `name` will be given to the blockUI instance which will \"scope\" it to the parent component instance. |\n\n## BlockUIService\n\nIn some cases you may want to have more control over all the instances in you app.\nInstead of declaring separate instances with the `@BlockUI()` decorator you can use the `BlockUIService`. This service allows you to easily target multiple instance across your app.\n\n| Method        | Parameters                                                 | Description                                                                              |\n| ------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------------------- |\n| `isActive`    | \u003ccode\u003etarget: string \u0026#124; string[]\u003c/code\u003e                | Indicates if the targeted instance(s) is blocking.                                       |\n| `start`       | \u003ccode\u003etarget: string \u0026#124; string[], message?: any\u003c/code\u003e | Starts blocking for a single instance or multiple instances by passing instance name(s). |\n| `stop`        | \u003ccode\u003etarget: string \u0026#124; string[]\u003c/code\u003e                | Stops blocking for a single instance or multiple instances by passing instance name(s).  |\n| `update`      | \u003ccode\u003etarget: string \u0026#124; string[], message: any\u003c/code\u003e  | Updates message for a single instance or multiple instances by passing instance name(s). |\n| `reset`       | \u003ccode\u003etarget: string \u0026#124; string[]\u003c/code\u003e                | Resets blocking for a single instance or multiple instances by passing instance name(s). |\n| `resetGlobal` | \u003ccode\u003eN/A\u003c/code\u003e                                           | Resets blocking app wide for all instances.                                              |\n| `unsubscribe` | \u003ccode\u003etarget: string \u0026#124; string[]\u003c/code\u003e                | Unsubscribes a single instance or multiple instances by passing instance name(s).        |\n\n## Other Modules\n\n### [Http Module](docs/http-module.md) - Automatically block during http requests\n\n### [Router Module](docs/router-module.md) - Prevent route changes while blocking\n\n## Guides\n\n### [SystemJS Config](docs/systemjs-config.md)\n\n## Examples\n\n### BlockUI Component - [Stackblitz](https://stackblitz.com/github/kuuurt13/ng-block-ui/tree/master/examples/default)\n\n### BlockUI Component Default Message - [Stackblitz](https://stackblitz.com/github/kuuurt13/ng-block-ui/tree/master/examples/default-message)\n\n### BlockUI Directive - [Stackblitz](https://stackblitz.com/github/kuuurt13/ng-block-ui/tree/master/examples/directive)\n\n### BlockUI Custom Spinner Styles - [Stackblitz](https://stackblitz.com/github/kuuurt13/ng-block-ui/tree/master/examples/custom-spinner-styles)\n\n### BlockUI Custom Template - [Stackblitz](https://stackblitz.com/github/kuuurt13/ng-block-ui/tree/master/examples/custom-template)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuuurt13%2Fng-block-ui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkuuurt13%2Fng-block-ui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkuuurt13%2Fng-block-ui/lists"}