MazDatePicker

A powerful and flexible date picker component with support for single dates, date ranges, time selection, and extensive customization options

Before use it, you should install the MazUi plugin in your project, follow instructions in Getting Started

TIP

This component can be translated globally using the MazUi plugin.

Table of Contents

• Basic Usage
• Date Formats
• Date Selection
• Time Selection
• Range Selection
• Internationalization
• Validation & Constraints
• Types
• Props
• Events
• Slots

Basic Usage

The simplest way to use MazDatePicker:

Select a date

<template>
  <MazDatePicker
    v-model="date"
    label="Select a date"
    placeholder="Choose your date"
    format="YYYY-MM-DD"
  />
</template>

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

const date = ref()
</script>

Date Formats

Understanding date formats is crucial for using MazDatePicker effectively. The component uses two different format concepts:

1. Data Format (format prop)

This controls how dates are stored and transmitted in your v-model. Default is 'YYYY-MM-DD'.

2. Display Format (input-date-format prop)

This controls how dates appear in the input field using Intl.DateTimeFormatOptions.

ISO Format (YYYY-MM-DD)

US Format (MM/DD/YYYY)

European Format (DD-MM-YYYY)

<template>
  <!-- ISO Format (recommended) -->
  <MazDatePicker
    v-model="date1"
    label="ISO Format (YYYY-MM-DD)"
    format="YYYY-MM-DD"
    :input-date-format="{ dateStyle: 'medium' }"
  />

  <!-- US Format -->
  <MazDatePicker
    v-model="date2"
    label="US Format (MM/DD/YYYY)"
    format="MM/DD/YYYY"
    :input-date-format="{ dateStyle: 'short' }"
  />

  <!-- European Format -->
  <MazDatePicker
    v-model="date3"
    label="European Format (DD-MM-YYYY)"
    format="DD-MM-YYYY"
    :input-date-format="{ dateStyle: 'medium' }"
  />
</template>

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

const date1 = ref('2024-03-15')        // ISO format
const date2 = ref('03/15/2024')        // US format
const date3 = ref('15-03-2024')        // European format
</script>

Custom Display Transformation

Use inputDateTransformer to completely customize how dates appear in the input:

Custom Display Format

<template>
  <MazDatePicker
    v-model="date"
    label="Custom Display Format"
    :input-date-transformer="transformDate"
  />
</template>

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

const date = ref()

const transformDate = ({ value }) => {
  return value ? `📅 ${dayjs(value).format('dddd, MMMM Do YYYY')}` : ''
}
</script>

Date Selection

Standard Date Picker

Select Date

<template>
  <MazDatePicker
    v-model="date"
    label="Select Date"
    color="primary"
    auto-close
  />
</template>

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

const date = ref()
</script>

Inline Date Picker

Perfect for dashboards or when you want the calendar always visible:

-

-

SunMonTueWedThuFriSat

<template>
  <MazDatePicker
    v-model="date"
    inline
    color="secondary"
  />
</template>

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

const date = ref()
</script>

Double Calendar

Show two months at once for better date selection:

Double Calendar

<template>
  <MazDatePicker
    v-model="date"
    label="Double Calendar"
    double
    color="success"
  />
</template>

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

const date = ref()
</script>

Time Selection

Date + Time (24h format)

Date & Time (24h)

<template>
  <MazDatePicker
    v-model="dateTime"
    label="Date & Time (24h)"
    format="YYYY-MM-DD HH:mm"
    time
    color="info"
  />
</template>

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

const dateTime = ref()
</script>

Date + Time (12h format)

Date & Time (12h)

<template>
  <MazDatePicker
    v-model="dateTime"
    label="Date & Time (12h)"
    format="YYYY-MM-DD hh:mm a"
    time
    color="warning"
  />
</template>

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

const dateTime = ref()
</script>

Time Only Selection

Time Only (24h)

Time Only (12h)

<template>
  <!-- 24h format -->
  <MazDatePicker
    v-model="time24"
    label="Time Only (24h)"
    format="HH:mm"
    only-time
    color="accent"
  />

  <!-- 12h format -->
  <MazDatePicker
    v-model="time12"
    label="Time Only (12h)"
    format="hh:mm a"
    only-time
    color="destructive"
  />
</template>

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

const time24 = ref('14:30')
const time12 = ref('02:30 pm')
</script>

Custom Minute Intervals

5min intervals

15min intervals

30min intervals

<template>
  <MazDatePicker
    v-model="time1"
    label="5min intervals"
    format="HH:mm"
    :minute-interval="5"
    only-time
  />

  <MazDatePicker
    v-model="time2"
    label="15min intervals"
    format="HH:mm"
    :minute-interval="15"
    only-time
  />

  <MazDatePicker
    v-model="time3"
    label="30min intervals"
    format="HH:mm"
    :minute-interval="30"
    only-time
  />
</template>

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

const time1 = ref()
const time2 = ref()
const time3 = ref()
</script>

Range Selection

For selecting date ranges, pass an object with start and end properties:

Select Date Range

<template>
  <MazDatePicker
    v-model="range"
    label="Select Date Range"
    range
    double
    auto-close
    color="primary"
  />
</template>

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

const range = ref({
  start: undefined,
  end: undefined
})
</script>

Range with Shortcuts

Provide predefined shortcuts for common date ranges:

Range with Shortcuts

<template>
  <MazDatePicker
    v-model="range"
    label="Range with Shortcuts"
    range
    double
    :shortcuts="shortcuts"
    color="secondary"
  />
</template>

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

const range = ref({
  start: undefined,
  end: undefined
})

const shortcuts = [
  {
    label: 'Today',
    identifier: 'today',
    value: {
      start: dayjs().format('YYYY-MM-DD'),
      end: dayjs().format('YYYY-MM-DD')
    }
  },
  {
    label: 'Last 7 days',
    identifier: 'last7days',
    value: {
      start: dayjs().subtract(6, 'day').format('YYYY-MM-DD'),
      end: dayjs().format('YYYY-MM-DD')
    }
  },
  {
    label: 'This month',
    identifier: 'thisMonth',
    value: {
      start: dayjs().startOf('month').format('YYYY-MM-DD'),
      end: dayjs().endOf('month').format('YYYY-MM-DD')
    }
  }
]
</script>

Property shortcuts

Model

interface MazDatePickerShortcut {
  identifier: string // should be uniq
  label: string
  value: {
    start: string
    end: string
  }
}

type MazDatePickerShortcuts = MazDatePickerShortcut[]

Example

import type { MazDatePickerShortcut } from 'maz-ui/components'

const shortcuts: MazDatePickerShortcut[] = [{
  label: 'Next month',
  identifier: 'nextMonth',
  value: {
    start: dayjs().add(1, 'month').set('date', 1).format('YYYY-MM-DD'),
    end: dayjs()
      .add(1, 'month')
      .set('date', dayjs().add(1, 'month').daysInMonth())
      .format('YYYY-MM-DD'),
  },
}]

View default shortcuts

const shortcuts = [
  {
    label: 'Last 7 days',
    identifier: 'last7Days',
    value: {
      start: dayjs().subtract(6, 'day').format('YYYY-MM-DD'),
      end: dayjs().format('YYYY-MM-DD'),
    },
  },
  {
    label: 'Last 30 days',
    identifier: 'last30Days',
    value: {
      start: dayjs().subtract(29, 'day').format('YYYY-MM-DD'),
      end: dayjs().format('YYYY-MM-DD'),
    },
  },
  {
    label: 'This week',
    identifier: 'thisWeek',
    value: {
      start: dayjs().startOf('week').format('YYYY-MM-DD'),
      end: dayjs().endOf('week').format('YYYY-MM-DD'),
    },
  },
  {
    label: 'Last week',
    identifier: 'lastWeek',
    value: {
      start: dayjs()
        .subtract(1, 'week')
        .startOf('week')
        .format('YYYY-MM-DD'),
      end: dayjs().subtract(1, 'week').endOf('week').format('YYYY-MM-DD'),
    },
  },
  {
    label: 'This month',
    identifier: 'thisMonth',
    value: {
      start: dayjs().set('date', 1).format('YYYY-MM-DD'),
      end: dayjs()
        .set('date', dayjs().daysInMonth())
        .format('YYYY-MM-DD'),
    },
  },
  {
    label: 'This year',
    identifier: 'thisYear',
    value: {
      start: dayjs().startOf('year').format('YYYY-MM-DD'),
      end: dayjs().endOf('year').format('YYYY-MM-DD'),
    },
  },
  {
    label: 'Last year',
    identifier: 'lastYear',
    value: {
      start: dayjs()
        .subtract(1, 'year')
        .startOf('year')
        .format('YYYY-MM-DD'),
      end: dayjs().subtract(1, 'year').endOf('year').format('YYYY-MM-DD'),
    },
  },
]

Validation & Constraints

Min/Max Dates

Limited Date Range

Min: 2026-01-22 | Max: 2026-02-11

<template>
  <MazDatePicker
    v-model="date"
    label="Limited Date Range"
    :min-date="minDate"
    :max-date="maxDate"
    color="info"
  />
</template>

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

const date = ref()
const minDate = dayjs().subtract(30, 'day').format('YYYY-MM-DD')
const maxDate = dayjs().add(30, 'day').format('YYYY-MM-DD')
</script>

Property min-max-auto

Disable min-max auto check to not change the value when it is out of range

Not auto date range

<template>
  <MazDatePicker
    v-model="date"
    label="Not auto date range"
    :min-date="minDate"
    :max-date="maxDate"
    :min-max-auto="false"
  />
</template>

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

const date = ref()
const minDate = dayjs().subtract(30, 'day').format('YYYY-MM-DD')
const maxDate = dayjs().add(30, 'day').format('YYYY-MM-DD')
</script>

Disabled Days & Dates

Weekends Disabled

Holidays Disabled

<template>
  <!-- Disable weekends -->
  <MazDatePicker
    v-model="date1"
    label="Weekends Disabled"
    :disabled-weekly="[0, 6]"
    color="warning"
  />

  <!-- Disable specific dates -->
  <MazDatePicker
    v-model="date2"
    label="Holidays Disabled"
    :disabled-dates="holidays"
    color="destructive"
  />
</template>

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

const date1 = ref()
const date2 = ref()

// 0 = Sunday, 6 = Saturday
const weekends = [0, 6]

// Specific holiday dates
const holidays = [
  dayjs().subtract(2, 'day').format('YYYY-MM-DD'),
  dayjs().subtract(1, 'day').format('YYYY-MM-DD'),
  dayjs().format('YYYY-MM-DD'),
  dayjs().add(1, 'day').format('YYYY-MM-DD'),
  dayjs().add(2, 'day').format('YYYY-MM-DD'),
  dayjs().add(3, 'day').format('YYYY-MM-DD'),
  dayjs().add(4, 'day').format('YYYY-MM-DD'),
]
</script>

Disabled Hours

Disabled Hours

Disabled Hours

<template>
  <MazDatePicker
    v-model="dateTime"
    format="YYYY-MM-DD hh:mm a"
    time
    label="Disabled Hours"
    :disabled-hours="disabledHours"
    color="info"
  />

  <MazDatePicker
    v-model="time"
    format="HH:mm"
    only-time
    label="Disabled Hours"
    :disabled-hours="disabledHours"
    color="info"
  />
</template>

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

const date = ref()
const time = ref()

const disabledHours = [0, 1, 2, 11, 22, 23]
</script>

Internationalization

MazDatePicker supports full internationalization. By default, it uses the locale from the MazUiTranslations plugin, but you can override it:

French Locale

German Locale

Japanese Locale

Arabic Locale

<template>
  <!-- French -->
  <MazDatePicker
    v-model="frenchDate"
    label="French Locale"
    locale="fr-FR"
    :first-day-of-week="1"
    color="primary"
  />

  <!-- German -->
  <MazDatePicker
    v-model="germanDate"
    label="German Locale"
    locale="de-DE"
    :first-day-of-week="1"
    color="secondary"
  />

  <!-- Japanese -->
  <MazDatePicker
    v-model="japaneseDate"
    label="Japanese Locale"
    locale="ja-JP"
    color="accent"
  />

  <!-- Arabic -->
  <MazDatePicker
    v-model="arabicDate"
    label="Arabic Locale"
    locale="ar-SA"
    :first-day-of-week="6"
    color="warning"
  />
</template>

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

const frenchDate = ref()
const germanDate = ref()
const japaneseDate = ref()
const arabicDate = ref()
</script>

Types

// Value types
type MazDatePickerValue = string | undefined | MazDatePickerPartialRangeValue

interface MazDatePickerRangeValue {
  start: string
  end: string
}

type MazDatePickerPartialRangeValue = Partial<MazDatePickerRangeValue>

// Shortcut type
interface MazDatePickerShortcut {
  identifier: string
  label: string
  value: {
    start: string
    end: string
  }
}

Tips

TIP

This component use MazInput, so it inherits all his props

Props

Name	Description	Type	Required	Default	Possible values
id	The unique identifier of the component	string	No	undefined	-
style	The inline style object for the component	HTMLAttributes['style']	No	undefined	-
class	The CSS class(es) to apply to the component	HTMLAttributes['class']	No	undefined	-
input-props	The props to apply to the input component	MazInputProps	No	undefined	-
model-value	The value of the date picker component If an object is provided, the picker will be a range picker	MazDatePickerValue	No	undefined	-
format	The format pattern for date display and parsing Example: 'YYYY-MM-DD', 'DD/MM/YYYY', 'YYYY-MM-DD HH:mm'	string	No	'YYYY-MM-DD'	-
open	v-model:open Controls whether the picker window is open	boolean	No	false	-
label	The label text displayed above the input field	string	No	undefined	-
placeholder	The placeholder text shown when no value is selected	string	No	undefined	-
input-date-format	The Intl.DateTimeFormatOptions for styling the input date display	Intl.DateTimeFormatOptions	No	() => ({ dateStyle: 'medium', timeStyle: 'short' })	-
input-date-transformer	Custom function to transform the formatted date display	Function	No	undefined	-
locale	The locale string for date formatting and localization Example: 'en-US', 'fr-FR', 'de-DE'	string	No	undefined	-
hide-header	Controls whether the calendar header is hidden	boolean	No	false	-
disabled	Controls whether the component is disabled	boolean	No	false	-
first-day-of-week	The first day of the week in the calendar Example: 0 (Sunday), 1 (Monday), 6 (Saturday)	0 | 1 | 2 | 3 | 4 | 5 | 6	No	0	0, 1, 2, 3, 4, 5, 6
auto-close	Controls whether the picker closes automatically after date selection	boolean	No	false	-
custom-element-selector	CSS selector for a custom element that triggers the picker Example: '#my-button', '.trigger-class'	string	No	undefined	-
double	Controls whether the picker displays two months side by side	boolean	No	false	-
inline	Controls whether the picker is displayed inline without input field	boolean	No	false	-
color	The color theme of the component	MazColor	No	'primary'	primary, secondary, success, destructive, warning, info, accent, contrast
picker-position	The position where the picker popover should appear	MazPopoverProps['position']	No	'auto'	top, bottom, left, right, top-end, bottom-end, left-end, right-end, top-start, bottom-start, left-start, right-start
picker-prefer-position	The preferred position of the picker popover	MazPopoverProps['preferPosition']	No	'bottom-start'	top, bottom, left, right, top-end, bottom-end, left-end, right-end, top-start, bottom-start, left-start, right-start
picker-fallback-position	The fallback position of the picker popover	MazPopoverProps['fallbackPosition']	No	'top-start'	top, bottom, left, right, top-end, bottom-end, left-end, right-end, top-start, bottom-start, left-start, right-start
time	Controls whether the picker includes a time selector	boolean	No	false	-
only-time	Controls whether the picker shows only time selection (no date)	boolean	No	false	-
minute-interval	The interval in minutes for the time picker minute selection	number	No	5	1, 5, 10, 15, 30
use-browser-locale	Controls whether to automatically detect and use the browser's locale	boolean	No	true	-
fetch-local	Controls whether to fetch locale data dynamically	boolean	No	true	-
shortcuts	Array of predefined date range shortcuts or false to disable	MazDatePickerShortcut[] | false	No	true	-
shortcut	The identifier of the currently selected shortcut	MazDatePickerShortcut['identifier']	No	undefined	-
min-date	The minimum selectable date in ISO format Example: '2023-01-01'	string	No	undefined	-
max-date	The maximum selectable date in ISO format Example: '2024-12-31'	string	No	undefined	-
min-max-auto	When minDate or maxDate are provided, if the current date is not between minDate and maxDate, the current date will be set to the minDate or maxDate	boolean	No	true	-
disabled-weekly	Array of weekday numbers to disable (0 = Sunday, 6 = Saturday) Example: [0, 6] to disable weekends	number[]	No	() => []	-
disabled-dates	Array of specific dates to disable in ISO format Example: ['2023-12-25', '2024-01-01']	string[]	No	() => []	-
disabled-hours	Array of hour numbers to disable in the time picker (0-23) Example: [0, 1, 2, 22, 23] to disable night hours	number[]	No	() => []	-
block	Controls whether the input displays in full width	boolean	No	false	-
range	Controls whether the picker operates in range selection mode	boolean	No	false	-
transition	The transition name of the popover	MazPopoverProps['transition']	No	'scale-fade'	-

Events

Event name	Properties	Description
update:model-value	value MazDatePickerValue | undefined - The new selected value	Emitted when the picker value changes
close		Emitted when the picker closes

Slots

Name	Description	Bindings
trigger	Replace the default input with your own element	is-open boolean - Current open state of the popover close function - Function to close the popover open function - Function to open the popover toggle function - Function to toggle the popover