DatePicker

Basic Usage

<script setup>
import { DatePicker } from '@8ctavio/vergil/components'
import { useModel } from '@8ctavio/vergil'
const date = useModel(null, { shallow: true })
const dates = useModel([])
</script>

<template>
    <!-- Single Selection -->
    <DatePicker v-model="date" placeholder="Select Date"/>
    <!-- Multiple Selection -->
    <DatePicker v-model="dates" placeholder="Select Dates"/>
</template>

<style scoped>
.date-picker {
    width: 200px;
}
</style>

Props

All Calendar props are available for DatePicker.

Date format

format: Intl.DateTimeFormatOptions | ((date: Date) => string)

As an object, the format prop conforms to the Intl.DateTimeFormat constructor's options object. The locales used by Intl.DateTimeFormat are obtained from the Calendar's locale prop.

As a function, the format prop itself is used to format dates. It receives as a single argument a Date object and should return a string — the formatted string of the received date.

<script setup>
const formatOptions = {
    year: 'numeric',
    month: '2-digit',
    day: '2-digit',
}
</script>

<template>
    <DatePicker locale="es-MX" :format="formatOptions"/>
</template>

Default date format

The format prop's default value is configurable through the datePicker.format or datePicker.formatOptions configuration options (datePicker.format precedes datePicker.formatOptions).

The datePicker.format should be a function, which is used to directly format dates. The function receives as a single argument a Date object and should return a string — the formatted string of the received date.

datePicker: {
    format: date => { /* ... */ }
}

The datePicker.formatOptions may be either an object that conforms to Intl.DateTimeFormat constructor's options object, or a function that returns such object. As a function, a boolean argument is received that indicates whether time selection is enabled.

datePicker: {
    formatOptions: { /* ... */ }
    // or
    formatOptions: timeEnabled => ({ /* ... */ })
}

Placeholder

placeholder: string

<DatePicker placeholder="Select Date"/>

Placeholder fallback

placeholder-fallback: (n: number) => string

When multiple date selection is enabled, a string with the comma-separated, selected dates' formatted strings is displayed in the DatePicker's main button. If that string overflows its container, a fallback placeholder is obtained from the placeholder-fallback function and displayed instead.

The placeholder-fallback function receives as its only argument the number of selected dates.

<DatePicker
    :value="[]"
    :placeholder-fallback="n => {
        return `Selected ${n} date${n > 1 ? 's':''}`
    }"
    placeholder="Select Dates"
/>

The following function is used as the default placeholder-fallback value.

n => `${n} Dates Selected`

Side button's icons

icon-calendar: string = 'calendar_month'

icon-clear: string = 'event_busy'

<DatePicker icon-calendar="calendar_add_on" icon-clear="close"/>

Clear button

btn-clear: Record<string, unknown>

The btn-clear prop receives an object representing the props of the clear button's underlying Btn component.

The Btn's disabled prop is bound to the DatePicker's. That is, if the DatePicker is disabled, the clear button will also get disabled regardless of btnClear.disabled.

Additionally, a position prop can be passed through btn-clear to indicate the clear button's position with respect to the DatePicker's main button. The position prop possible values are 'after' and 'before', and its default value can be configured through the sideButtonPosition configuration option.

Finally, the Btn prop used to display the DatePicker's icons changes with position. If position === 'before', the iconRight prop is reserved for the DatePicker's icons. Otherwise, the icon prop is used.

<script setup>
const btnClearProps = {
    position: 'before',
    variant: 'solid',
    iconLeft: 'rocket_launch',
    iconRight: 'rocket_launch', // ignored
}
</script>

<template>
    <DatePicker :btn-clear="btnClearProps"/>
</template>

Float label

float-label: boolean

<DatePicker label="Select date" float-label/>

NOTE

float-label only works if the placeholder and description props are unset.

Underline

underline: boolean

Fill

fill: boolean

Theme

theme: theme = 'brand'

Size

size: ('xs' | 'sm' | 'md' | 'lg' | 'xl') = 'md'

Radius

radius: ('none' | 'sm' | 'md' | 'lg' | 'full') = 'md'

Spacing

spacing: ('compact' | 'expanded') = ''

Disabled

disabled: boolean

Elements

element	tag	description
root	<div.calendar>	Calendar's root div container.
dates	<div.calendar-dates>	Calendar's date button elements' wrapper

Anatomy

<div.form-field.date-picker/>

<div.form-field-label-wrapper/>

<label.form-field-label/>

<span.form-field-hint/>

<p.form-field-details.form-field-description/>

<div.date-picker-wrapper/>

<Btn.btn.date-picker-select/>

<p.date-picker-placeholder/>

<span/>

<template #aside/>

<label/>

<Btn.btn.date-picker-clear/>

<p.form-field-details.form-field-help/>

<Teleport#popover-portal/>

<div.popover-wrapper/>

<div.popover.date-picker-popover/>

<Calendar/>

API Reference

Props

prop	type	default
value	Date | null | string | number | Date[] | string[] | number[]	null
format	Intl.DateTimeFormatOptions | (date: Date) => string
placeholder	string
placeholderFallback	(n: number) => string
iconCalendar	string	'calendar_month'
iconClear	string	'event_busy'
btnClear	Record<string, unknown>
underline	boolean
fill	boolean
disabled	boolean
label	string
hint	string
description	string
help	string
showErrros	boolean
floatLabel	boolean
descendant	boolean
theme	'brand' | 'user' | 'ok' | 'info' | 'warn' | 'danger' | 'neutral'	'brand'
size	'xs' | 'sm' | 'md' | 'lg' | 'xl'	'md'
radius	'none' | 'sm' | 'md' | 'lg' | 'full'	'md'
spacing	'' | 'compact' | 'extended'	''
validator	Function
eagerValidation	boolean
elements	object

Configuration options

DatePicker's configuration options allow to overwrite some DatePicker props' default values and may be overwritten under the datePicker root-level configuration option.

datePicker.<option>	type	default	global
format	object | (date: Date) => string
formatOptions	object | (timeEnabled: boolean) => object
placeholderFallback	(n: number) => string	n => `${n} Dates Selected`
sideButtonPosition	'before' | 'after'	'after'
underline	boolean
fill	boolean
theme	theme		✅
size	size		✅
radius	radius		✅
spacing	spacing		✅