vant/src/datetime-picker/README.md

DatetimePicker

Intro

Used to select time, support date and time dimensions, usually used with the Popup component.

Install

Register component globally via app.use, refer to Component Registration for more registration ways.

import { createApp } from 'vue';
import { DatetimePicker } from 'vant';

const app = createApp();
app.use(DatetimePicker);

Usage

Choose Date

<van-datetime-picker
  v-model="currentDate"
  type="date"
  title="Choose Date"
  :min-date="minDate"
  :max-date="maxDate"
/>

import { ref } from 'vue';

export default {
  setup() {
    const currentDate = ref(new Date(2021, 0, 17));
    return {
      minDate: new Date(2020, 0, 1),
      maxDate: new Date(2025, 10, 1),
      currentDate,
    };
  },
};

Choose Year-Month

<van-datetime-picker
  v-model="currentDate"
  type="year-month"
  title="Choose Year-Month"
  :min-date="minDate"
  :max-date="maxDate"
  :formatter="formatter"
/>

import { ref } from 'vue';

export default {
  setup() {
    const currentDate = ref(new Date());

    const formatter = (type, val) => {
      if (type === 'year') {
        return `${val} Year`;
      }
      if (type === 'month') {
        return `${val} Month`;
      }
      return val;
    };

    return {
      minDate: new Date(2020, 0, 1),
      maxDate: new Date(2025, 10, 1),
      formatter,
      currentDate,
    };
  },
};

Choose Month-Day

<van-datetime-picker
  v-model="currentDate"
  type="month-day"
  title="Choose Month-Day"
  :min-date="minDate"
  :max-date="maxDate"
  :formatter="formatter"
/>

import { ref } from 'vue';

export default {
  setup() {
    const currentDate = ref(new Date());

    const formatter = (type, val) => {
      if (type === 'month') {
        return `${val} Month`;
      }
      if (type === 'day') {
        return `${val} Day`;
      }
      return val;
    };

    return {
      minDate: new Date(2020, 0, 1),
      maxDate: new Date(2025, 10, 1),
      formatter,
      currentDate,
    };
  },
};

Choose Time

<van-datetime-picker
  v-model="currentTime"
  type="time"
  title="Choose Time"
  :min-hour="10"
  :max-hour="20"
/>

import { ref } from 'vue';

export default {
  setup() {
    const currentTime = ref('12:00');
    return { currentTime };
  },
};

Choose DateTime

<van-datetime-picker
  v-model="currentDate"
  type="datetime"
  title="Choose DateTime"
  :min-date="minDate"
  :max-date="maxDate"
/>

import { ref } from 'vue';

export default {
  setup() {
    const currentDate = ref(new Date());
    return {
      minDate: new Date(2020, 0, 1),
      maxDate: new Date(2025, 10, 1),
      currentDate,
    };
  },
};

Choose DateHour

<van-datetime-picker
  v-model="currentDate"
  type="datehour"
  title="Choose DateTime"
  :min-date="minDate"
  :max-date="maxDate"
/>

import { ref } from 'vue';

export default {
  setup() {
    const currentDate = ref(new Date());
    return {
      minDate: new Date(2020, 0, 1),
      maxDate: new Date(2025, 10, 1),
      currentDate,
    };
  },
};

Option Filter

<van-datetime-picker
  v-model="currentTime"
  type="time"
  title="Option Filter"
  :filter="filter"
/>

import { ref } from 'vue';

export default {
  setup() {
    const currentTime = ref('12:00');

    const filter = (type, options) => {
      if (type === 'minute') {
        return options.filter((option) => Number(option) % 5 === 0);
      }
      return options;
    };

    return {
      filter,
      currentTime,
    };
  },
};

Columns Order

<van-datetime-picker
  v-model="currentDate"
  type="date"
  title="Columns Order"
  :columns-order="['month', 'day', 'year']"
  :formatter="formatter"
/>

import { ref } from 'vue';

export default {
  setup() {
    const currentDate = ref(new Date());

    const formatter = (type, val) => {
      if (type === 'year') {
        return val + ' Year';
      }
      if (type === 'month') {
        return val + ' Month';
      }
      if (type === 'day') {
        return val + ' Day';
      }
      return val;
    };

    return {
      formatter,
      currentDate,
    };
  },
};

API

Props

Attribute	Description	Type	Default
type	Can be set to date time year-month month-day datehour	string	datetime
title	Toolbar title	string	''
confirm-button-text	Text of confirm button	string	Confirm
cancel-button-text	Text of cancel button	string	Cancel
show-toolbar	Whether to show toolbar	boolean	true
loading	Whether to show loading prompt	boolean	false
readonly	Whether to be readonly	boolean	false
filter	Option filter	(type: string, values: string[]) => string[]	-
formatter	Option text formatter	(type: string, value: string) => string	-
columns-order	Array for ordering columns, where item can be set to year, month, day, hour and minute	string[]	-
item-height	Option height, supports px vw vh rem unit, default px	number | string	44
visible-item-count	Count of visible columns	number | string	6
swipe-duration	Duration of the momentum animation，unit ms	number | string	1000

DatePicker Props

Following props are supported when the type is date or datetime

Attribute	Description	Type	Default
min-date	Min date	Date	Ten years ago on January 1
max-date	Max date	Date	Ten years later on December 31

TimePicker Props

Following props are supported when the type is time

Attribute	Description	Type	Default
min-hour	Min hour for time type	number | string	0
max-hour	Max hour for time type	number | string	23
min-minute	Max minute for time type	number | string	0
max-minute	Max minute for time type	number | string	59

Events

Event	Description	Arguments
change	Emitted when value changed	value: current value
confirm	Emitted when the confirm button is clicked	value: current value
cancel	Emitted when the cancel button is clicked	-

Slots

Name	Description	SlotProps
default	Custom toolbar content	-
title	Custom title	-
confirm	Custom confirm button text	-
cancel	Custom cancel button text	-
option	Custom option content	option: string | object
columns-top	Custom content above columns	-
columns-bottom	Custom content below columns	-

Methods

Use ref to get DatetimePicker instance and call instance methods.

Name	Description	Attribute	Return value
getPicker	get Picker instance	-	-

Types

Get the type definition of the DatetimePicker instance through DatetimePickerInstance.

import { ref } from 'vue';
import type { DatetimePickerInstance } from 'vant';

const datetimePickerRef = ref<DatetimePickerInstance>();

datetimePickerRef.value?.getPicker();