CountDown

17:06

Description

A countdown component that decrements from the given duration every second based on timestamp (in seconds), automatically splitting and showing days / hours / minutes / seconds. separator can be an English colon (colon) or the Chinese units for days / hours / minutes / seconds (zh), and each time unit can be shown or hidden individually with show-days / show-hours / show-minutes / show-seconds; with autoplay false you can control it manually via ref with start / end.

Compatibility

Platform	Support
App	✅ Supported (the root element is a block-level flex, so multiple countdowns need a wrapping container to sit on one line)
H5	✅ Supported
WeChat Mini Program	✅ Supported

Examples

Basic Usage

Separated by colons by default, starts counting down automatically, and displays down to the second.

View source

<template>
    <ux-count-down :timestamp="86399"></ux-count-down>
</template>

Chinese Separator

When separator is set to zh, days/hours/minutes/seconds are separated in Chinese; separator-color customizes the separator color.

View source

<template>
    <ux-count-down :timestamp="86399" separator="zh"></ux-count-down>
    <view class="gap"></view>
    <ux-count-down :timestamp="86399" separator="zh" separator-color="#fa3534"></ux-count-down>
</template>

<style scoped>
.gap {
    height: 20px;
}
</style>

Hide Days

When show-days is false, the days portion is converted into hours.

View source

<template>
    <ux-count-down :timestamp="86400" :show-days="false"></ux-count-down>
</template>

Custom Style

Customize the number style via font-size / color; separator-size controls the separator size.

View source

<template>
    <ux-count-down :timestamp="3600" :font-size="20" color="#2979ff" :separator-size="15"></ux-count-down>
</template>

Number Border

show-border displays a border around the numbers, height sets the number box size, and border-color customizes the border color.

View source

<template>
    <ux-count-down :timestamp="7200" :show-border="true" :height="32" bg-color="#ecf5ff" color="#fb7299"></ux-count-down>
    <view class="gap"></view>
    <ux-count-down :timestamp="7200" :show-border="true" :height="32" border-color="#19be6b" bg-color="#f0f9eb" color="#67c23a"></ux-count-down>
</template>

<style scoped>
.gap {
    height: 20px;
}
</style>

Unit Visibility

Control the visibility of each time unit via show-hours / show-minutes / show-seconds.

View source

<template>
    <ux-count-down :timestamp="59" :show-days="false" :show-hours="false" :show-minutes="false"></ux-count-down>
    <view class="gap"></view>
    <ux-count-down :timestamp="7200" :show-seconds="false"></ux-count-down>
</template>

<style scoped>
.gap {
    height: 20px;
}
</style>

Hide Zero Day

When hide-zero-day is true, the day field is hidden when the day is 0.

View source

<template>
    <ux-count-down :timestamp="3599" :hide-zero-day="false"></ux-count-down>
    <view class="gap"></view>
    <ux-count-down :timestamp="3599" :hide-zero-day="true"></ux-count-down>
</template>

<style scoped>
.gap {
    height: 20px;
}
</style>

Millisecond Refresh

When millisecond is true, the countdown refreshes at millisecond granularity.

View source

<template>
    <ux-count-down :timestamp="5" :millisecond="true"></ux-count-down>
</template>

Manual Control

When autoplay is false, the countdown does not start automatically; call the start / end methods manually.

View source

<template>
    <ux-count-down ref="countDownRef" :timestamp="10" :autoplay="false"></ux-count-down>
    <view class="gap"></view>
    <view class="btn-row">
        <view class="btn" @click="startCountDown"><text class="btn-text">开始</text></view>
        <view class="btn" @click="endCountDown"><text class="btn-text">结束</text></view>
    </view>
</template>

<script setup lang="uts">
const countDownRef = ref<any>();

function startCountDown(): void {
    countDownRef.value?.start();
}

function endCountDown(): void {
    countDownRef.value?.end();
}
</script>

<style scoped>
.gap {
    height: 20px;
}
.btn-row {
    display: flex;
    flex-direction: row;
    flex-wrap: wrap;
    margin-top: 8px;
}
.btn {
    display: flex;
    flex-direction: row;
    align-items: center;
    justify-content: center;
    padding: 4px 12px;
    margin-right: 8px;
    margin-bottom: 8px;
    border-radius: 4px;
    background-color: #ecf5ff;
}
.btn-text {
    font-size: 13px;
    color: #2979ff;
}
</style>

API

Props

Property	Description	Type	Default	Version
customStyle	Custom root element style	string | UTSJSONObject	-	-
customClass	Custom root element style class	string	''	-
timestamp	Countdown time, in seconds	number | string	0	-
autoplay	Whether to start the countdown automatically	boolean	true	-
separator	Separator: colon for an English colon, zh for Chinese units	string	'colon'	-
separatorSize	Font size of the separator, in px	number | string	DEFAULT_SEPARATOR_SIZE	-
separatorColor	Color of the separator	string	''	-
color	Font color	string	''	-
fontSize	Font size, in px	number | string	DEFAULT_FONT_SIZE	-
bgColor	Number background color	string	''	-
height	Number box height (width equals this value), in px	number | string	'auto'	-
showBorder	Whether to show the number box	boolean	false	-
borderColor	Border color	string	''	-
showSeconds	Whether to show seconds	boolean	true	-
showMinutes	Whether to show minutes	boolean	true	-
showHours	Whether to show hours	boolean	true	-
showDays	Whether to show the day part	boolean	true	-
hideZeroDay	Hide the day field when the day part is 0	boolean	false	-
millisecond	Whether to refresh at millisecond granularity	boolean	false	-

Events

Event	Description	Params	Version
end	Countdown finished	-	-
change	Fired once per second; the callback is the current remaining whole seconds	value: number	-

Slots

ux-count-down has no slots.

Notes

1. timestamp is in seconds; changing it resets the countdown and (when autoplay is true and it is greater than 0) restarts it.
2. With autoplay true but timestamp 0 it does not start (the source only auto-starts when timestamp is greater than 0).
3. end() pauses the countdown and emits the end event; the change event fires once per second and passes the remaining whole seconds.
4. With showDays false the day part is folded into hours (the hour count may exceed 24) rather than dropped.
5. With separator colon no colon is shown after the last visible unit; with zh each unit is followed by its Chinese label (including seconds).
6. With hideZeroDay true and a day value of 0, the day field and the separator after it are hidden together.
7. height sets both the width and height of the number box (width equals height) and works together with showBorder.
8. millisecond only changes the refresh granularity (polling about every 30ms internally); the display still only goes down to seconds, and the change event can be used for millisecond-precision scenarios.
9. When the number and separator font sizes are unset they fall back to the global config componentProps['ux-count-down'] and then to the built-in default of 15px.
10. On App the root element is a block-level flex, while on H5 / WeChat Mini Program it is inline-flex; multiple countdowns on App need a wrapping container to sit on one line.