NgxLoadingMask

Angular 5+ simple loading-mask ui component. DEMO

Todos

• [x] global config
• [x] customizable loading snippet comp
  • [x] with global config
  • [x] with templateDef
• [x] mask container directive
• [x] events observable
• [x] ember layout support
• [x] httpClient interceptor integrate
• [x] docs
• [x] unit-test cases

Install

npm install ngx-loading-mask --save

Note: this lib depends on @angular/cdk/portal, make sure you have installed it.

then just import LoadingMaskModule to AppModule's imports array

imports: [
  ...,
  LoadingMaskModule.forRoot(config)
]

Config

• snippet(SnippetConfig): loading snippet config object
  • imgUrl(string): loading snippet uri, default: null
  • size(number): snippet size(in px), default: 144
• mask(MaskConfig): loading mask config object
  • bgColor(string): loading mask background color, default: rgba(255, 255, 255, .7)
• clsMapping(ClsMapping): class suffix
  • snip(string): loading snippet class suffix, default: ngx-loading-snip
  • mask(string): loading mask class suffix, default: ngx-loading-mask
• debug(boolean): toggle debug mode, default: false

Basic Usage

global loading mask

just declare [ngxLoadingMask] into your app container element or body

<div class="container" ngxLoadingMask>
    ...
</div>

local loading mask

similar to global one, just declare the group name to [ngxLoadingMask] like

<div class="wrapper" [ngxLoadingMask]="'foo'">
    ...
</div>

toggle mask

just use LoadingMaskService to toggle loading mask

// to show mask
this.service.showGroup(groupName)

// to hide mask 
this.toggleDone(groupName)

if groupName is undefined, the default value of it was global loading mask group name, for sake of toggling local mask, you need assign local group name to it, like foo or something else.

Advance Usage

In above section, the code style was imperative. If you want more declarative, we can use Angular httpClient interceptor feature.

Note: Until now, Angular httpClient api all have string type constraint, that means cannot patch custom metadata param into options, this library used custom-header instead.

use Angular httpClient service

with origin httpClient service, it is easy to patch headers

http
  .post('/api/somthing/', body, {
    headers: new HttpHeaders().set('X-Loading-Mask', 'foo'),
  })
  .subscribe();

the loading mask metadata is bind to X-Loading-Mask key of the headers. The key has been exported as constant(LOADING_MASK_HEADER) of the module entry.

use custom service extends httpClient

above code is relly ugly due to we must set HttpHeader manually but we only take care which loading mask should be toggle on during request process. The code could be more declarative by extending default httpClient service class and providing other custom api on it, something like

export class HttpService extends HttpClient {
  ...

  withLoadingMask(groupName: string = DEFAULT_MASK_GROUP): HttpService {
    return this.addInterceptor({
      intercept(req, next) {
        req = req.clone({
          setHeaders: { [LOADING_MASK_HEADER]: groupName },
        })
        return next.handle(req)
      }
    })
  }

  ...
}

then you can use it as

http.withLoadingMask('foo')
  .post('/api/somthing/', body)
  .subscribe();

see whole example in HERE

API

[ngxLoadingMask]

• ngxLoadingMask(string): loading mask group name, if null, use default global loading mask gorup name instead.

mask

mask template var, could assign custom loading spin template with it, for example:

<div ngxLoadingMask>
  <ng-template #mask *ngIf="isCustom">
    <h1>
      {{customMessage}}...(global)
    </h1>
  </ng-template>
</div> 

the ng-template override the default loading spin template, see more in DEMO site.

LoadingMaskService

subscribe(groupName?: string): Observable

get the loading mask events Observable corresponding to groupName, if groupName is undefined, will listen to all events

showGroup(groupName: string = DEFAULT_MASK_GROUP)

emit pending event of loading mask corresponding to groupName

hideGroup(groupName: string = DEFAULT_MASK_GROUP)

emit done event of loading mask corresponding to groupName

hideGroupError(groupName: string = DEFAULT_MASK_GROUP, error: any)

emit error event of loading mask corresponding to groupName, but throw error

isDefaultGroup(groupName: string): boolean

if a loading mask group is global default group

isDoneGroup(group: LoadingMaskGroup): boolean

if a loading mask group is in done status

getGroup(groupName: string, safe = false): LoadingMaskGroup

get group instance of groupName, if don't existed and safe = true, set new group instance with groupName and return it

setGroup(groupName: string, replace = false): LoadingMaskGroup

set group instance of groupName, if replace = false, will return exited group instance with corresponding groupName, otherwise, will replace current group instance with new one

register(groupName: string = DEFAULT_MASK_GROUP, replace = false): LoadingMaskGroup

register loading mask group instance

unregister(groupName: string)

unregister loading mask group instance