@smithalan2/vue-countdown

Vue Countdown

A simple countdown timer component for Vue 3 written using the composition API.

Demo https://smithalan92.github.io/vue-countdown/

Installation

Install with npm

npm i --save @smithalan2/vue-countdown

Props

Name	Type	Required	Default	Notes
startDateTime	Date	no	new Date() on each tick	Passing a start date time will result in only 1 calc being made.
endDateTime	Date	yes	n/a	----
startImmediately	Boolean	false	true	If passed as false, you need to call run on the component ref.
tickDelay	Number	no	1000	ms to run each recalculation.

Events

Name	Args	Notes
start	None	Emitted the first time a countdown starts
finished	None	Emitted when the countdown has reached the end time
cancelled	None	Emitted when the countdown has been cancelled
tick	Countdown	The newely calculated countdown values

Slot props

If the component is passed a default slot. The slot will recieve a prop with Countdown data

Exposed Properties

The component instance exposes a number of properties that can be used if required.

Name	Notes
run	A function to manually start the countdown.
cancel	A function to cancel the countdown
countdown	The actual reactive countdown data

Countdown Data

The countdown data is a reactive object. It is passed as a slot prop and also given as a param to the tick event.

The countdown prop contains the values for the countown, as well as formatted text that can be used for display. The countdown data object is structured as follows

{
  remainingSeconds: { value: Number, text: String },
  remainingMinutes: { value: Number, text: String },
  remainingHours: { value: Number, text: String },
  remainingDays: { value: Number, text: String },
  remainingWeeks: { value: Number, text: String },
  remainingMonths: { value: Number, text: String },
  remainingYears: { value: Number, text: String },
}

Sample key values may are

remainingYears: { value: 0, text: '0 years' },
remainingDays: { value: 1, text: '1 day' },
remainingSeconds: { value: 54, text: '54 seconds' },

Sample Usage

vue-countdown can be used in 2 ways. You can either use slots to render out the countdown, or provide no slot and listen to the tick event to get countdown updates and do whatever you need to.

With slots

<vue-countdown
  :end-date-time="endDateTime">
  <template
    v-slot:default="{ countdown }">
    {{ countdown }}
  </template>
</vue-countdown>

With event

<vue-countdown
  :end-date-time="endDateTime"
  @tick="onTick">
...
onTick(countdown) {
  ...
}

License

See License.md