Van Count Down

Vant CountDown Component

Used to display the countdown value in real time, and precision supports milliseconds.

When to Invoke

Invoke this skill when:

• User needs to implement countdown timers
• User wants to show time-limited promotions or activities
• User needs to display remaining time with custom format
• User wants to control countdown manually (start, pause, reset)
• User asks about millisecond precision countdown

Features

• Real-time Updates: Automatic countdown with configurable precision
• Custom Format: Flexible time format with multiple placeholders
• Millisecond Support: Support millisecond-level precision
• Manual Control: Start, pause, and reset methods
• Auto Start: Configurable auto-start behavior
• Custom Styling: Full control over countdown display via slots

API Reference

Props

Available Formats

Events

Slots

CurrentTime Structure

Methods

Types

import type {
  CountDownProps,
  CountDownInstance,
  CountDownCurrentTime,
} from 'vant';

Usage Examples

Basic Usage

<template>
  <van-count-down :time="time" />
</template>

<script setup>
import { ref } from 'vue';

const time = ref(30 * 60 * 60 * 1000);
</script>

Custom Format

<template>
  <van-count-down :time="time" format="DD Day, HH:mm:ss" />
</template>

<script setup>
import { ref } from 'vue';

const time = ref(30 * 60 * 60 * 1000);
</script>

Millisecond Precision

<template>
  <van-count-down millisecond :time="time" format="HH:mm:ss:SS" />
</template>

<script setup>
import { ref } from 'vue';

const time = ref(30 * 60 * 60 * 1000);
</script>

Custom Style

<template>
  <van-count-down :time="time">
    <template #default="timeData">
      <span class="block">{{ timeData.hours }}</span>
      <span class="colon">:</span>
      <span class="block">{{ timeData.minutes }}</span>
      <span class="colon">:</span>
      <span class="block">{{ timeData.seconds }}</span>
    </template>
  </van-count-down>
</template>

<style scoped>
.colon {
  display: inline-block;
  margin: 0 4px;
  color: #1989fa;
}

.block {
  display: inline-block;
  width: 22px;
  color: #fff;
  font-size: 12px;
  text-align: center;
  background-color: #1989fa;
}
</style>

Manual Control

<template>
  <van-count-down
    ref="countDown"
    millisecond
    :time="3000"
    :auto-start="false"
    format="ss:SSS"
    @finish="onFinish"
  />
  <van-grid clickable :column-num="3">
    <van-grid-item text="Start" icon="play-circle-o" @click="start" />
    <van-grid-item text="Pause" icon="pause-circle-o" @click="pause" />
    <van-grid-item text="Reset" icon="replay" @click="reset" />
  </van-grid>
</template>

<script setup>
import { ref } from 'vue';
import { showToast } from 'vant';

const countDown = ref(null);

const start = () => {
  countDown.value.start();
};

const pause = () => {
  countDown.value.pause();
};

const reset = () => {
  countDown.value.reset();
};

const => showToast('Finished');
</script>

With Days

<template>
  <van-count-down :time="time">
    <template #default="timeData">
      <span v-if="timeData.days > 0">
        {{ timeData.days }} days 
      </span>
      <span>{{ timeData.hours }}:{{ timeData.minutes }}:{{ timeData.seconds }}</span>
    </template>
  </van-count-down>
</template>

<script setup>
import { ref } from 'vue';

const time = ref(3 * 24 * 60 * 60 * 1000);
</script>

Common Issues

1. Countdown Not Starting

Make sure auto-start is not set to false, or call start() method manually:

<template>
  <van-count-down ref="countDown" :time="time" :auto-start="false" />
  <van-button @click="countDown.start()">Start</van-button>
</template>

2. Format Not Working

Ensure format placeholders are uppercase:

<van-count-down :time="time" format="HH:mm:ss" />

3. Reset Not Working

After reset, you need to call start() to begin countdown again:

<script setup>
const resetAndStart = () => {
  countDown.value.reset();
  countDown.value.start();
};
</script>

Component Interactions

With Promotion Banner

<template>
  <div class="promotion-banner">
    <h3>Flash Sale Ends In:</h3>
    <van-count-down :time="remainingTime" @finish="onSaleEnd">
      <template #default="timeData">
        <span class="time-block">{{ timeData.hours }}</span>
        <span class="separator">:</span>
        <span class="time-block">{{ timeData.minutes }}</span>
        <span class="separator">:</span>
        <span class="time-block">{{ timeData.seconds }}</span>
      </template>
    </van-count-down>
  </div>
</template>

<script setup>
import { ref, onMounted } from 'vue';

const remainingTime = ref(0);

onMounted(() => {
  const endTime = new Date('2024-12-31 23:59:59').getTime();
  remainingTime.value = endTime - Date.now();
});

const => {
  console.log('Sale ended');
};
</script>

With Verification Code

<template>
  <van-field v-model="code" label="Code">
    <template #button>
      <van-button 
        size="small" 
        :disabled="counting"
        @click="sendCode"
      >
        <van-count-down 
          v-if="counting"
          ref="countDown"
          :time="60000"
          :auto-start="false"
          format="ss s"
          @finish="onCountFinish"
        />
        <span v-else>Send Code</span>
      </van-button>
    </template>
  </van-field>
</template>

<script setup>
import { ref } from 'vue';

const code = ref('');
const counting = ref(false);
const countDown = ref(null);

const sendCode = () => {
  counting.value = true;
  countDown.value.start();
};

const => {
  counting.value = false;
};
</script>

Best Practices

1. Use appropriate precision: Only enable millisecond when necessary for performance
2. Provide clear feedback: Show finish event to users when countdown completes
3. Handle edge cases: Consider what happens when time reaches zero
4. Custom styling: Use slots for better visual presentation
5. Accessibility: Ensure countdown is accessible to screen readers