A Comprehensive Guide to Using ngx-countdown in Angular

In Angular applications, displaying timers or countdowns can be essential for various use cases such as events, limited-time offers, tasks with deadlines, and more. The ngx-countdown library provides a flexible and customizable solution for integrating countdown timers in Angular projects. In this blog, we will explore how to install, configure, and use ngx-countdown, along with examples of customization to fit your needs.

1. Introduction to ngx-countdown

ngx-countdown is an Angular library that allows you to easily integrate countdown timers into your Angular applications. It supports various customization options like format, styling, and event handling, making it suitable for a wide range of scenarios.

Key Features:

• Highly customizable UI
• Event-based handling of countdown lifecycle
• Support for dynamic start times and real-time updates
• Ability to format the display output

<a name="installation"></a>2. Installing ngx-countdown

First, you need to install the ngx-countdown package in your Angular project. Open your terminal and run the following command:

npm install ngx-countdown --save

After the installation, you need to import the CountdownModule in your application module:

// app.module.ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { AppComponent } from './app.component';
import { CountdownModule } from 'ngx-countdown';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, CountdownModule],
  providers: [],
  bootstrap: [AppComponent],
})
export class AppModule {}

3. Basic Usage

Once the module is set up, you can use the <countdown> component in your templates to display a countdown timer. The most basic implementation looks like this:

<!-- app.component.html -->
<countdown [config]="{ leftTime: 3600 }"></countdown>

In this example, the countdown starts from 3600 seconds (1 hour). The config object allows you to set the initial time, format, and other configurations.

4. Customization Options

ngx-countdown provides several customization options that let you style and format the timer according to your needs. Below are some of the common options you can pass through the config object:

• leftTime: The starting time of the countdown (in seconds).
• format: Customize the display format (e.g., "HH:mm:ss").
• demand: If set to true, the countdown won't start until you call it explicitly.
• notify: Specifies intervals (in seconds) at which you want to be notified about the remaining time.

<countdown 
  [config]="{ leftTime: 7200, format: 'HH:mm:ss', notify: [60, 10] }">
</countdown>

This countdown starts from 2 hours (leftTime: 7200) and displays the time in an HH:mm:ss format. Notifications are triggered at 60 seconds and 10 seconds before the end.

5. Handling Countdown Events

You can respond to specific events in the countdown lifecycle using event bindings like start, notify, finished, etc. For example, let's say you want to display a message when the countdown finishes:

<countdown [config]="{ leftTime: 120 }" (finished)="onCountdownFinish()"></countdown>

In your component, you would handle the finished event as follows:

// app.component.ts
import { Component } from '@angular/core';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  onCountdownFinish() {
    alert('Countdown finished!');
  }
}

You can also handle other events like start and notify:

<countdown 
  [config]="{ leftTime: 300, notify: [60, 30] }" 
  (start)="onStart()"
  (notify)="onNotify($event)"
  (finished)="onFinished()">
</countdown>

// app.component.ts
 onStart() { 
      console.log('Countdown started!');
   } 

onNotify(event: any) { 
       console.log('Time remaining:', event.left);
 }

 onFinished() { 
      console.log('Countdown finished.'); 
}

6. Custom Countdown Format

You can fully customize the countdown format to display labels such as 'days', 'hours', or any other text that fits your design.

For example, if you want to show 'days' below the numbers, you can use custom HTML alongside the countdown:

<div class="countdown-container">
  <div class="countdown-item">
    <span>{{ days }}</span>
    <p>Days</p>
  </div>
  <div class="countdown-item">
    <span>{{ hours }}</span>
    <p>Hours</p>
  </div>
  <div class="countdown-item">
    <span>{{ minutes }}</span>
    <p>Minutes</p>
  </div>
  <div class="countdown-item">
    <span>{{ seconds }}</span>
    <p>Seconds</p>
  </div>
</div>

In your component, you can calculate and display the remaining time dynamically:

import { CountdownComponent, CountdownConfig } from 'ngx-countdown';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
})
export class AppComponent {
  config: CountdownConfig = { leftTime: 3600 };
  days: number;
  hours: number;
  minutes: number;
  seconds: number;

  handleEvent(event: CountdownEvent) {
    const timeLeft = event.left / 1000; // Convert milliseconds to seconds
    this.days = Math.floor(timeLeft / (24 * 3600));
    this.hours = Math.floor((timeLeft % (24 * 3600)) / 3600);
    this.minutes = Math.floor((timeLeft % 3600) / 60);
    this.seconds = Math.floor(timeLeft % 60);
  }
}