JavaScript Countdown, is it that simple?

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, 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 1.2.0, you should include the latest version at this time.

<script src='https://unpkg.com/@wanoo21/countdown-time@1.2.0/dist/countdown-time.js'></script>

1. 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 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.

1. [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.

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

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:

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.

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?