JavaScript Countdown, is it that simple?
Tags: stencil, javascript
Published: 2019-06-25 14:39:07

---
title: JavaScript Countdown, is it that simple?
published: true
tags: Stencil, Javascript
canonical_url: https://yon.fun/simple-and-powerful-countdown-in-js/
---

![JavaScript Countdown, is it that simple?](https://images.unsplash.com/photo-1523350703530-161b46e28e24?ixlib=rb-1.2.1&q=80&fm=jpg&crop=entropy&cs=tinysrgb&w=1080&fit=max&ixid=eyJhcHBfaWQiOjExNzczfQ)

Sometimes writing a simple **countdown timer** is not so simple as it looks. You must play with “new Date” almost as an expert, and not every time you will have the preferred result. Fortunately, there are plenty of countdown plugins for JavaScript on the npm registry, and now I want to show you one of them.

I believe the future of javascript is within **Web Components** so each plugin which is created nowadays should support the standards of Web Components. These being said, I have chosen this cool [countdown time plugin](https://www.webcomponents.org/element/@wanoo21/countdown-time), and yes, it’s made by me.

Before showing some great examples, I’m going to explain to you more specifically the installing methods and what properties and methods does he have. So let’s dive into it.

## Install Countdown into your project

There are 2 simple ways:

1. Through script tag in the head section - this is the best and easy way! Please be aware that the current version in <mark>1.2.0</mark>, you should include the latest version at this time.

```js
<script src='https://unpkg.com/@wanoo21/countdown-time@1.2.0/dist/countdown-time.js'></script>
```
2. Through npm package - This solution is best for actual frameworks, like **Vue, Angular or React** and not only, you can use it with **Vanilla JS** as well.

  - Run `npm install @wanoo21/countdown-time`
  - Import it `import “@wanoo21/countdown-time”`

Then include `<countdown-time></countdown-time>` element anywhere in your template, JSX, HTML, etc to show a countdown timer. Of course, you must add some properties in order to start it, about them we are talking in the next section.

P.S. It supports **TypeScript** , Thanks [StencilJS](https://stenciljs.com/) for such a good opportunity!

## Countdown Properties [Attributes]

It has five custom properties, let’s see what they are and what they represent:

1. `[autostart]` - Whether start or not when the countdown is ready, if not, you must start it manually, default is `false`.

2. `[datetime]` - DateTime to countdown, must be a valid date represented by **string** or **number** , ex: `Date.now()`, default is `Date.now()`.

3. `[add]` - Add more time to current DateTime separated by spaces, ex: add="1h 30m" - this will add 1 hour and 30 minutes to `datetime` time, by default this attribute is empty.

{% codepen https://codepen.io/wanoo21/pen/RzZRWE/ default-tab=html,result %}

4. `[format]` - Use this attribute to change the showing format, ex: “{m}min. and {s}sec.”, default is “{h}:{m}:{s}”. These placeholders are available:
  1. {w} - number of weeks.
  2. {d} - number of days.
  3. {h} - number of hours.
  4. {m} - number of minutes.
  5. {s} - number of seconds.

{% codepen https://codepen.io/wanoo21/pen/orexOE/ default-tab=html,result %}

5. `[utc]` - Using this attribute you will convert the `datetime` time to UTC format, default is `false`.

{% codepen https://codepen.io/wanoo21/pen/QXMEdN/ default-tab=html,result %}

## Countdown Methods

- `getCountDownTime() => Promise<ITimeObject>` - Get a Promise of `ITimeObject` which has `{ weeks: string; days: string; hours: string; minutes: string; seconds: string; }` properties.
- `restart() => Promise<void>` - Restart countdown.
- `setAsExpired() => Promise<void>` - Set as expired, this action will stop and call `expire` custom event.
- `start() => Promise<void>` - Start countdown, `autostart` attribute is doing the same action.
- `stop() => Promise<void>` - Stop countdown, this action will stop countdown, but won’t call `expired` custom event.

## Countdown Events [CustomEvents]

There are two custom events, `expire` and `ready`:
- `expire` - Is emitted when the countdown expires.
- `ready` - Is emitted when the countdown is ready to start.  
Both of them return `CustomEvent<void>`. See some examples:

{% codepen https://codepen.io/wanoo21/pen/OejRyb/ default-tab=js,result %}

## Available 'Slots'

There is an option to hide or show some content based on the current countdown’s state. Add any content inside `<countdown-time></countdown-time>` and add the following attributes:

- `[show-on-expired]` - Show this element only when the countdown expired.
- `[hide-on-expired]` - Show this element only when the countdown is running and hide it when it is expired.

{% codepen https://codepen.io/wanoo21/pen/WqEoxL/ default-tab=html,result %}

## Conclusion

Not bad, huh? With some simple steps, you can have a plain and powerful countdown timer in your site. Try to play with it and tell me what you think, is it compatible with your ideas?