Skip to content

Latest commit

 

History

History
210 lines (159 loc) · 9.43 KB

README.md

File metadata and controls

210 lines (159 loc) · 9.43 KB
Raw

NgxGhosts

Table of Contents:

Live Demo

Installation

First you need to install the npm module:

npm install ngx-ghosts or yarn install ngx-ghosts

Import the NgxGhostsModule in modules where you want to use ghosts like this:

@NgModule({
    exports: [
        CommonModule,
        NgxGhostsModule
    ]
})
export class AppModule { }

Load the ngx-ghosts theme by adding it to the angular.json like this:

...
"build": {
  "options": {
    "styles": [
        "./node_modules/ngx-ghosts/theme.scss",
        "projects/ngx-ghosts-app/src/styles.scss"
      ]
  }
}

Or by importing the theme into your global styles like this:

@import '../../../node_modules/ngx-ghosts/theme.scss';

Now you are ready to add the first ghosts to your application.

Components

Ghost Box Directive

You can add a ghost to any element with the GhostBox directive. If height and width are not defined the ghost with fill the surrounding element.

<div class="panel">
  <ng-container *ghostBox="loading">
    <div>some content</div>
  </ng-container>
</div>

Parameters:

Name Description Type Default
ghostBox Toggle between ghost and content boolean false
height Height of the ghost number
width Width of the ghost number
ghostClass Custom class which is added to the ghost element string
state Emits the current state of the loader GhostImageState

Ghost Image

You can add a ghost to your imagesWith GhostImageWrapper component. To leverage image loading capabilities of ngx-ghosts you have to wrap your image element with GhostImageWrapper component, add GhostImage directive to the image element and define a ghost with GhostImageLoader directive. The image will be loaded as soon as the element enters the visible screen.

<ghost-image-wrapper>
  <img ghostImage [src]="..." [srcset]="..." />
  <ghost ghostImageLoader [height]="256" [width]="256"></ghost>
</ghost-image-wrapper>

Ghost Text Directive

You can add a ghost to a single line of text, or parts of a text line with the GhostText directive. In the example below the "title" requested from a server and a server is shown while the request is pending.

<div class="title-text">
  <span *ghostText="loading; length: 23">{{title}}</span>
</div>

Parameters:

Name Description Type Default
ghostText Toggle between ghost and content boolean false
length Length of the ghost number or "fill" "fill"
ghostClass Custom class which is added to the ghost element string

Ghost Text Block Directive

You can add a ghost to a multiline text with the GhostTextBlock directive.

<div class="description-text">
  <span *ghostTextBlock="loading; lines: [34, 50]">{{description}}</span>
</div>

Parameters:

Name Description Type Default
ghostTextBlock Toggle between ghost and content boolean false
lines Amount and length of lines. When only amount of lines is specified all lines will expand to fill number or array of number or "fill" []
ghostClass Custom class which is added to the ghost element string

Ghost

For special use cases where the other directives and components don't work you can us the basic Ghost component.

<ghost>My special content</ghost>

Parameters:

Name Description Type Default
fillHorizontal Use available horizontal space boolean false
fillVertical Use available vertical space boolean false
height Height of the ghost number
width Width of the ghost number
ghostClass Custom class which is added to the ghost element string
textGhost True if the ghosts represents a text element boolean

Customization

Custom Configuration

One way to customize ngx-ghosts is by providing a custom configuration like this:

import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';
import { NgxGhostsModule } from 'ngx-ghosts';


@NgModule({
    imports: [
        BrowserModule,
        NgxGhostsModule.forRoot({
          animationStrategy: 'EqualStartAndEnd'
        })
    ],
    bootstrap: [AppComponent]
})
export class AppModule { }

The configuration supports following properties:

Name Description Type Default
animationStrategy Decide how the animation of your ghosts should behave. You can choose from the following variants:
  • EqualStartAndEnd - All animations start and end at the same time, speed depends on the ghosts length
  • EqualStartAndSpeed - All animations start at the same time and have the same speed
  • OneAnimation - This looks like there would be only one ghost moving across the whole page
  • None - No animation is shown at all
 GhostAnimationStrategy "OneAnimation"
imageLoader.transitionDuration Define the duration of the transition between the ghost and the loaded image in milliseconds. number 500

Custom theme

There are a whole range of variables that are used to style the ghosts, any variable can be overwritten by providing a custom theme. The Following properties are supported for the theme:

Name Description Default
ghost-base-color Background color of ghosts #e3e4e4
ghost-glow-color Color of the ghost's glow effect #f5f5f5
ghost-glow-intensity Intensity of the glow effect (0 to 1) 0.3
ghost-glow-width Width of the glow effect 50%
ghost-glow-animation-duration Duration of the ghost animation 2000ms
ghost-glow-animation-function Animation funtion of the ghost animation linear
ghost-font-top-spacing Represents the top gap of the font 0.15em
ghost-font-bottom-spacing Represents the bottom gap of the font 0.2em

A custom theme can be created like this:

@import '../../../node_modules/ngx-ghosts/theme.scss';

.dark-theme {
  @include ngx-ghosts-theme(
    (
      ghost-base-color: #000,
      ghost-glow-color: #313639
    )
  );
}