Date Picker

Use Date Picker for date input.

Basic usage

Basic date picker measured by 'day'.

The measurement is determined by the type attribute. You can enable quick options via shortcuts property. The disabled date is set by disabledDate, which is a function.

---

<template>
  <b-date-picker
    v-model="value"
    type="date"
    placeholder="Pick a day"
    class="w-200px"
  />
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value = ref()
</script>

Other measurements

You can choose week, month, year or multiple dates by extending the standard date picker component.

Week

Month

Year

Dates

---

<template>
  <b-row>
    <b-col :md="6">
      <b-form-item label="Week">
        <b-date-picker v-model="value1" type="week" placeholder="Pick a week" />
      </b-form-item>
    </b-col>
    <b-col :md="6">
      <b-form-item label="Month">
        <b-date-picker
          v-model="value2"
          type="month"
          placeholder="Pick a month"
        />
      </b-form-item>
    </b-col>
    <b-col :md="6">
      <b-form-item label="Year">
        <b-date-picker v-model="value3" type="year" placeholder="Pick a year" />
      </b-form-item>
    </b-col>
    <b-col :md="6">
      <b-form-item label="Dates">
        <b-date-picker v-model="value4" type="dates" placeholder="Pick dates" />
      </b-form-item>
    </b-col>
  </b-row>
</template>

<script setup lang="ts">
import { ref } from 'vue'

const value1 = ref()
const value2 = ref()
const value3 = ref()
const value4 = ref([])
</script>

Date Range

Picking a date range is supported.

When in range mode, the left and right panels are linked by default. If you want the two panels to switch current months independently, you can use the unlink-panels attribute.

Default range

—

Range with quick options

—

---

<template>
  <b-row>
    <b-col>
      <b-form-item label="Default range">
        <b-date-picker
          v-model="value1"
          type="daterange"
          start-placeholder="Start date"
          end-placeholder="End date"
        />
      </b-form-item>
    </b-col>
    <b-col>
      <b-form-item label="Range with quick options">
        <b-date-picker
          v-model="value2"
          type="daterange"
          unlink-panels
          start-placeholder="Start date"
          end-placeholder="End date"
          :shortcuts="shortcuts"
        />
      </b-form-item>
    </b-col>
  </b-row>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value1 = ref('')
const value2 = ref('')

const shortcuts = [
  {
    text: 'Last week',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 7)
      return [start, end]
    },
  },
  {
    text: 'Last month',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 30)
      return [start, end]
    },
  },
  {
    text: 'Last 3 months',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 90)
      return [start, end]
    },
  },
]
</script>

Month Range

Picking a month range is supported.

When in range mode, the left and right panels are linked by default. If you want the two panels to switch current years independently, you can use the unlink-panels attribute.

Default range

—

Range with quick options

—

---

<template>
  <b-row>
    <b-col>
      <b-form-item label="Default range">
        <b-date-picker
          v-model="value1"
          type="monthrange"
          start-placeholder="Start date"
          end-placeholder="End date"
        />
      </b-form-item>
    </b-col>
    <b-col>
      <b-form-item label="Range with quick options">
        <b-date-picker
          v-model="value2"
          type="monthrange"
          unlink-panels
          start-placeholder="Start date"
          end-placeholder="End date"
          :shortcuts="shortcuts"
        />
      </b-form-item>
    </b-col>
  </b-row>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value1 = ref('')
const value2 = ref('')

const shortcuts = [
  {
    text: 'Last week',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 7)
      return [start, end]
    },
  },
  {
    text: 'Last month',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 30)
      return [start, end]
    },
  },
  {
    text: 'Last 3 months',
    value: () => {
      const end = new Date()
      const start = new Date()
      start.setTime(start.getTime() - 3600 * 1000 * 24 * 90)
      return [start, end]
    },
  },
]
</script>

Default Value

If user hasn't picked a date, shows today's calendar by default. You can use default-value to set another date. Its value should be parsable by `new Date().

If type is daterange, default-value sets the left side calendar.

Date

Date Range

—

---

<template>
  <b-row>
    <b-col>
      <b-form-item label="Date">
        <b-date-picker
          v-model="value1"
          type="date"
          placeholder="Pick a date"
          :default-value="new Date(2010, 9, 1)"
        />
      </b-form-item>
    </b-col>
    <b-col>
      <b-form-item label="Date Range">
        <b-date-picker
          v-model="value2"
          type="daterange"
          start-placeholder="Start Date"
          end-placeholder="End Date"
          :default-value="[new Date(2010, 9, 1), new Date(2010, 10, 1)]"
        />
      </b-form-item>
    </b-col>
  </b-row>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value1 = ref('')
const value2 = ref('')
</script>

Date Formats

Use format to control displayed text's format in the input box. Use value-format to control binding value's format.

By default, the component accepts and emits a Date object.

Check the list here of all available formats of Day.js.

WARNING

Pay attention to capitalization

Emits Date object

Value:

Use value-format

Value:

Timestamp

Value:

---

<template>
  <b-row>
    <b-col>
      <b-form-item label="Emits Date object" :help-text="`Value: ${value1}`">
        <b-date-picker
          v-model="value1"
          placeholder="Pick a Date"
          format="YYYY/MM/DD"
        />
      </b-form-item>
    </b-col>
    <b-col>
      <b-form-item label="Use value-format" :help-text="`Value: ${value2}`">
        <b-date-picker
          v-model="value2"
          placeholder="Pick a Date"
          format="YYYY/MM/DD"
          value-format="YYYY-MM-DD"
        />
      </b-form-item>
    </b-col>
    <b-col>
      <b-form-item label="Timestamp" :help-text="`Value: ${value3}`">
        <b-date-picker
          v-model="value3"
          placeholder="Pick a Date"
          format="YYYY/MM/DD"
          value-format="x"
        />
      </b-form-item>
    </b-col>
  </b-row>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value1 = ref('')
const value2 = ref('')
const value3 = ref('')
</script>

Default time

When picking a date range, you can assign the time part for start date and end date.

By default, the time part of start date and end date are both 00:00:00. Setting default-time can change their time respectively. It accepts an array of up to two Date objects. The first string sets the time for the start date, and the second for the end date.

—

Value:

---

<template>
  <b-form-item topless :help-text="`Value: ${value}`" class="w-480px">
    <b-date-picker
      v-model="value"
      type="daterange"
      start-placeholder="Start date"
      end-placeholder="End date"
      :default-time="defaultTime"
    />
  </b-form-item>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value = ref('')
const defaultTime = ref<[Date, Date]>([
  new Date(2000, 1, 1, 0, 0, 0),
  new Date(2000, 2, 1, 23, 59, 59),
])
</script>

Custom content

The content of cell can be customized, in scoped-slot you can get the cell data.

---

<template>
  <b-date-picker
    v-model="value"
    placeholder="Pick a day"
    format="YYYY/MM/DD"
    value-format="YYYY-MM-DD"
    class="w-200px"
  >
    <template #default="cell">
      <div class="b-date-table-cell" :class="{ current: cell.isCurrent }">
        <span class="b-date-table-cell__text">{{ cell.text }}</span>
        <div
          v-if="isHoliday(cell)"
          class="absolute w-1 h-1 rounded bg-teal-3 top-1 right-1"
        />
      </div>
    </template>
  </b-date-picker>
</template>

<script lang="ts" setup>
import { ref } from 'vue'

const value = ref('2021-10-29')
const holidays = [
  '2021-10-01',
  '2021-10-02',
  '2021-10-03',
  '2021-10-04',
  '2021-10-05',
  '2021-10-06',
  '2021-10-07',
]

const isHoliday = ({ dayjs }) => {
  return holidays.includes(dayjs.format('YYYY-MM-DD'))
}
</script>

For data details, please refer:

interface DateCell {
  column: number
  customClass: string
  disabled: boolean
  end: boolean
  inRange: boolean
  row: number
  selected: Dayjs
  isCurrent: boolean
  isSelected: boolean
  start: boolean
  text: number
  timestamp: number
  date: Date
  dayjs: Dayjs
  type: 'normal' | 'today' | 'week' | 'next-month' | 'prev-month'
}

Localization

The default locale of is English, if you need to use other languages, please check Internationalization

Note, date time locale (month name, first day of the week ...) are also configured in localization.

Attributes

Name	Description	Type	Accepted Values	Default
model-value / v-model	binding value, if it is an array, the length should be 2	Date / number / string / Array	—	—
readonly	whether DatePicker is read only	boolean	—	false
disabled	whether DatePicker is disabled	boolean	—	false
size	size of Input	string	large / default / small	default
editable	whether the input is editable	boolean	—	true
clearable	whether to show clear button	boolean	—	true
placeholder	placeholder in non-range mode	string	—	—
start-placeholder	placeholder for the start date in range mode	string	—	—
end-placeholder	placeholder for the end date in range mode	string	—	—
type	type of the picker	string	year / month / date / dates / datetime / week / datetimerange / daterange / monthrange	date
format	format of the displayed value in the input box	string	see date formats	YYYY-MM-DD
popper-class	custom class name for DatePicker's dropdown	string	—	—
range-separator	range separator	string	—	'-'
default-value	optional, default date of the calendar	Date / [Date, Date]	—	—
default-time	optional, the time value to use when selecting date range	Date / [Date, Date]	—	—
value-format	optional, format of binding value. If not specified, the binding value will be a Date object	string	see date formats	—
id	same as id in native input	string / [string, string]	—	—
name	same as name in native input	string	—	—
unlink-panels	unlink two date-panels in range-picker	boolean	—	false
suffix-icon	custom suffix icon component	string | Component	—	Calendar
clear-icon	custom clear icon component	string | Component	—	Close
validate-event	whether to trigger form validation	boolean	—	true
disabled-date	a function determining if a date is disabled with that date as its parameter. Should return a Boolean	function	—	—
shortcuts	an object array to set shortcut options	Array<{ text: string, value: Date | Function }>	—	—
cell-class-name	set custom className	Function (Date)	—	—
teleported	whether date-picker dropdown is teleported to the body	boolean	true / false	true

Events

Name	Description	Parameters
change	triggers when user confirms the value	(val: typeof v-model)
blur	triggers when Input blurs	(e: FocusEvent)
focus	triggers when Input focuses	(e: FocusEvent)
calendar-change	triggers when the calendar selected date is changed. Only for daterange	(val: [Date, Date])
panel-change	triggers when the navigation button click.	(date, mode, view)
visible-change	triggers when the DatePicker's dropdown appears / disappears	(visibility: boolean)

Methods

Method	Description	Parameters
focus	focus the Input component	—
handleOpen	open the DatePicker popper	—
handleClose	close the DatePicker popper	—

Slots

Name	Description
default	custom cell content
range-separator	custom range separator content