Datepicker

The Datepicker input component allow users to select a date from a customizable calendar, and type the date directly into the input with full internationalization support. The input opens a simple dropdown/modal for selecting a date, and uses the native datepicker for mobile.

Examples

Base

Show code

HTML

<section>
    <o-field grouped>
        <o-field label="Locale">
            <o-select v-model="locale" placeholder="Locale">
                <option :value="undefined"></option>
                <option value="de-DE">de-DE</option>
                <option value="en-CA">en-CA</option>
                <option value="en-GB">en-GB</option>
                <option value="en-US">en-US</option>
                <option value="es-ES">es-ES</option>
                <option value="es-MX">es-MX</option>
                <option value="fr-CA">fr-CA</option>
                <option value="fr-FR">fr-FR</option>
                <option value="it-IT">it-IT</option>
                <option value="ja-JP">ja-JP</option>
                <option value="pt-BR">pt-BR</option>
                <option value="ru-RU">ru-RU</option>
            </o-select>
        </o-field>
        <o-field label="Show week number">
            <o-switch v-model="showWeekNumber" />
        </o-field>
    </o-field>

    <o-field label="Select a date">
        <o-datepicker
            v-model="selected"
            :show-week-number="showWeekNumber"
            :locale="locale"
            placeholder="Click to select..."
            icon="calendar"
            trap-focus />
    </o-field>

    <p><b>Selected:</b> {{ selected }}</p>
</section>

JS

import { ref } from "vue";

const selected = ref(new Date());
const showWeekNumber = ref(false);
const locale = ref(); // Browser locale

Min/Max date

Use the min-date and max-date props to define a limited date range for the user to choose from.

Show code

HTML

<section>
    <o-field label="Select a date">
        <o-datepicker
            placeholder="Click to select..."
            icon="calendar"
            :min-date="minDate"
            :max-date="maxDate" />
    </o-field>
</section>

JS

const today = new Date();
const minDate = new Date(
    today.getFullYear(),
    today.getMonth(),
    today.getDate() - 7,
);
const maxDate = new Date(
    today.getFullYear(),
    today.getMonth(),
    today.getDate() + 7,
);

Range

Let the user select a date range by setting the range prop.

Show code

HTML

<section>
    <o-field label="Select a date">
        <o-datepicker
            v-model="dates"
            placeholder="Click to select..."
            icon="calendar"
            trap-focus
            range />
    </o-field>

    <p><b>Selected:</b> {{ dates }}</p>
</section>

JS

import { ref } from "vue";

const dates = ref<[Date, Date] | []>([]);

Multiple

When the multiple prop is set, the user can select multiple dates at once. Also, the modelValue prop will be an array of date objects instead of a single date object.

Show code

HTML

<section>
    <o-field label="Select a date">
        <o-datepicker
            v-model="dates"
            multiple
            placeholder="Click to select..." />
    </o-field>

    <p><b>Selected:</b> {{ dates }}</p>
</section>

JS

import { ref } from "vue";

const dates = ref<Date[]>([]);

Events

To render the component inline instead of a dropdown/modal use the inline prop.

The calendar can display indicators for events on specific dates by passing a list to the events prop.

Show code

HTML

<section>
    <o-field>
        <o-switch v-model="bars" label="Indicator Bars" />
    </o-field>

    <o-datepicker
        v-model="date"
        inline
        :events="events"
        :indicators="bars ? 'bars' : 'dots'" />
</section>

JS

import { ref } from "vue";

const thisMonth = new Date().getMonth();

const bars = ref(false);
const date = ref(new Date(2020, thisMonth, 1));

const events = [
    { date: new Date(2020, thisMonth, 2) },
    { date: new Date(2020, thisMonth, 6) },
    {
        date: new Date(2020, thisMonth, 6),
        type: "info",
    },
    {
        date: new Date(2020, thisMonth, 8),
        type: "danger",
    },
    {
        date: new Date(2020, thisMonth, 10),
        type: "success",
    },
    {
        date: new Date(2020, thisMonth, 10),
        type: "link",
    },
    { date: new Date(2020, thisMonth, 12) },
    {
        date: new Date(2020, thisMonth, 12),
        type: "warning",
    },
    {
        date: new Date(2020, thisMonth, 16),
        type: "danger",
    },
    { date: new Date(2020, thisMonth, 20) },
    {
        date: new Date(2020, thisMonth, 29),
        type: "success",
    },
    {
        date: new Date(2020, thisMonth, 29),
        type: "warning",
    },
    {
        date: new Date(2020, thisMonth, 29),
        type: "info",
    },
];

Slots

The component can be customized through several slots, e.g. the HTML input can be replaced by a custom trigger to open the dropdown/modal through the trigger slot. The header and footer can be overridden using the header and footer slots.

Show code

HTML

<section>
    <o-field label="Select a date" grouped>
        <o-datepicker
            v-model="selected"
            :first-day-of-week="1"
            placeholder="Click to select...">
            <template #trigger>
                <o-button
                    icon-left="calendar"
                    variant="primary"
                    aria-label="Open Calendar" />
            </template>

            <template #header>
                <o-field grouped>
                    <o-select
                        :model-value="selected?.getMonth()"
                        :options="months"
                        root-class="grow"
                        expanded
                        @update:model-value="selectMonth" />
                    <o-button
                        :label="selected?.getFullYear().toString()"
                        disabled />
                </o-field>
            </template>

            <template #footer>
                <div class="footer-container">
                    <o-button
                        variant="primary"
                        icon-left="calendar"
                        label="Today"
                        @click="selected = new Date()" />
                    <o-button
                        variant="danger"
                        icon-left="times"
                        label="Clear"
                        @click="selected = undefined" />
                </div>
            </template>
        </o-datepicker>

        <o-input v-model="selectedString" readonly expanded />
    </o-field>
</section>

JS

import { computed, ref } from "vue";

const months = [
    { label: "January", value: 0 },
    { label: "February", value: 1 },
    { label: "March", value: 2 },
    { label: "April", value: 3 },
    { label: "May", value: 4 },
    { label: "June", value: 5 },
    { label: "July", value: 6 },
    { label: "August", value: 7 },
    { label: "September", value: 8 },
    { label: "October", value: 9 },
    { label: "November", value: 10 },
    { label: "December", value: 11 },
];

const selected = ref<Date | undefined>(new Date());

const selectedString = computed(() => selected.value?.toDateString() || "");

function selectMonth(month: number | undefined): void {
    if (!month) return;

    const date = selected.value ? new Date(selected.value) : new Date();
    date.setMonth(month);
    selected.value = date;
}

SCSS

.footer-container {
    display: flex;
    justify-content: end;
    margin-top: 0.5rem;
}

.footer-container button {
    margin-left: 0.5rem;
}

.grow {
    flex-grow: 1;
}

Programmatically

The dorpdown/modal can be opened programmatically setting the active prop, which is also two-way bindable.

Show code

HTML

<section>
    <o-field expanded addons>
        <o-datepicker
            v-model:active="active"
            expanded
            placeholder="Select a date" />
        <o-button
            icon-left="calendar"
            variant="primary"
            aria-label="Open Calendar"
            @click="active = !active" />
    </o-field>
</section>

JS

import { ref } from "vue";

const active = ref(false);

Month picker

Instead of picking a full date by setting the type prop to "month", the component will only render a month selector.

Show code

HTML

<section>
    <o-field label="Select a month">
        <o-datepicker
            placeholder="Click to select..."
            icon="calendar"
            type="month" />
    </o-field>
</section>

Datepicker component

An input with a simple dropdown/modal for selecting a date, uses native datepicker for mobile.

<o-datepicker></o-datepicker>

Props

Prop name	Description	Type	Values	Default
active	The active state of the dropdown, use v-model:active to make it two-way binding	boolean	-	false
ariaNextLabel	Accessibility next button aria label	string	-	From config: datepicker: {   ariaNextLabel: "Next Page" }
ariaPreviousLabel	Accessibility previous button aria label	string	-	From config: datepicker: {   ariaNextLabel: "Previous Page" }
ariaSelectMonthLabel	Accessibility month select aria label	string	-	From config: datepicker: {   ariaSelectMonthLabel: "Select Month" }
ariaSelectYearLabel	Accessibility year select aria label	string	-	From config: datepicker: {   ariaSelectYearLabel: "Select Year" }
closeOnClick	Close dropdown on click	boolean	-	From config: datepicker: {   closeOnClick: true }
creator	Date creator function, default is new Date()	(() => Date)	-	From config: datepicker: {   creator: undefined }
customValidity	Custom HTML 5 validation error to set on the form control	string | ((currentValue: Date | [] | Date[] | [Date, Date] | null , state: ValidityState) => string) | undefined	-	""
dayNames	Set custom day names, else use names based on locale	string[]	-	From config: datepicker: {   dayNames: undefined }
desktopModal	Dropdown content is shown into a modal on desktop	boolean	-	From config: datepicker: {   desktopModal: false }
disabled	Same as native disabled	boolean	-	false
events	Events to display on picker	DatepickerEvent[]	-
expanded	Makes input full width when inside a grouped or addon field	boolean	-	false
firstDayOfWeek	Set the first day of a week	number	-	From config: datepicker: {   firstDayOfWeek: 0 }
focusedDate	Set default date to focus on	Date	-
formatter	Custom function to format a date into a string	((date: Date | [] | Date[] | [Date, Date] ) => string) | undefined	-	From config: datepicker: {   formatter: undefined }
icon	Icon to be shown	string	-	From config: datepicker: {   icon: undefined }
iconNext	Icon name for next icon	string	-	From config: datepicker: {   iconNext: "chevron-right" }
iconPack	Icon pack to use	string	mdi, fa, fas and any other custom icon pack	From config: datepicker: {   iconPack: undefined }
iconPrev	Icon name for previous icon	string	-	From config: datepicker: {   iconPrev: "chevron-left" }
iconRight	Icon to be added on the right side	string	-	From config: datepicker: {   iconRight: undefined }
iconRightClickable	Make the icon right clickable	boolean	-	false
indicators	Event indicators for style class definiton	string	-	"dots"
inline	Display datepicker inline	boolean	-	false
locale	Date format locale	string	-	From config: {   locale: undefined }
maxDate	Max date to select	Date	-
minDate	Min date to select	Date	-
mobileBreakpoint	Mobile breakpoint as max-width value	string	-	From config: datepicker: {   mobileBreakpoint: undefined }
mobileModal	Dropdown content is shown into a modal on mobile	boolean	-	From config: datepicker: {   mobileModal: true }
mobileNative	Enable mobile native input if mobile agent	boolean	-	From config: datepicker: {   mobileNative: false }
v-model	The input value state, use v-model to make it two-way binding	[] | [Date, Date] | Date | Date[]	-
monthNames	Set custom month names, else use names based on locale	string[]	-	From config: datepicker: {   monthNames: undefined }
multiple	Same as native, also push new item to v-model instead of replacing	boolean	-
nearbyMonthDays	Show nearby month days	boolean	-	From config: datepicker: {   nearbyMonthDays: true }
nearbySelectableMonthDays	Define if nearby month days can be selected	boolean	-	From config: datepicker: {   nearbySelectableMonthDays: false }
openOnFocus	Open dropdown on focus	boolean	-	From config: datepicker: {   openOnFocus: true }
override	Override existing theme classes completely	boolean	-
parser	Custom function to parse a string into a date	((date: string) => Date | [] | Date[] | [Date, Date] ) | undefined	-	From config: datepicker: {   parser: undefined }
placeholder	Input placeholder	string	-
position	Position of the dropdown relative to the input	"auto" | "bottom-left" | "bottom-right" | "bottom" | "left" | "right" | "top-left" | "top-right" | "top"	auto, top, bottom, left, right, top-right, top-left, bottom-left, bottom-right
range	Enable date range selection	boolean	-
readonly	Same as native input readonly	boolean	-	false
rounded	Makes the input rounded	boolean	-	false
rulesForFirstWeek	Rules for the first week - 1 for the 1st January, 4 for the 4th January	number	-	4
selectableDates	Define a list of dates which can be selected	Date[] | ((date: Date) => boolean)	-
showWeekNumber	Show week numbers	boolean	-	From config: datepicker: {   showWeekNumber: false }
size	Size of the control input	string	small, medium, large	From config: datepicker: {   size: undefined }
teleport	Append the component to another part of the DOM. Set true to append the component to the body. In addition, any CSS selector string or an actual DOM node can be used.	boolean | object | string	-	From config: datepicker: {   teleport: false }
type	Define picker mode	"date" | "month"	date, month	"date"
unselectableDates	Define a list of dates which can not be selected	Date[] | ((date: Date) => boolean)	-
unselectableDaysOfWeek	Define a list of weeks which can not be selected	number[]	-	From config: datepicker: {   unselectableDaysOfWeek: undefined }
useHtml5Validation	Enable HTML 5 native validation	boolean	-	From config: {   useHtml5Validation: true }
weekNumberClickable	Define if week numbers are clickable	boolean	-	From config: datepicker: {   weekNumberClickable: false }
yearsRange	Define the range of years to show	number[]	-	From config: datepicker: {   yearsRange: [-100,10] }

Events

Event name	Properties	Description
focus	event Event - native event	on input focus event
blur	event Event - native event	on input blur event
invalid	event Event - native event	on input invalid event
icon-click	event Event - native event	on icon click event
icon-right-click	event Event - native event	on icon right click event
range-start	value Date - range start date	on range start is selected event
range-end	value Date - range end date	on range end is selected event
update:model-value	value Date | Date[] - updated modelValue prop	modelValue prop two-way binding
update:active	value boolean - updated active prop	active prop two-way binding
change-month	value number - month number	on month change event
change-year	value number - year number	on year change event

Slots

Name	Description	Bindings
trigger	Override the trigger
header	Override the header
body	Override the body
footer	Define an additional footer

Class Inspector

Classes applied to the element:

How does the Class props inspector work?

Class props inspector is useful to see class props you want to use to customize Oruga components and how they change a component. You can click on Inspect button to find the exact element where a specific class prop acts.

In the Class props inspector there are other columns:

Class prop

This column contains the name of the Class prop you want to inspect.
If you find a name with a link ( ▷ classPropName) this refers to a subitem (e.g. Dropdown Item in Dropdown).

Description

This column contains the description of the Class prop you want to inspect.
👉 This icon indicates some warning, e.g. this Class prop is visible only on mobile.

Props

This column contains a list of props that activate the class, e.g. if a class prop contains disabled prop it means that only when the component has disabled prop.

Suffixes

This column contains all the possible suffixes that you'll receive if you use a function to customize your Class prop.

Class prop	Description	Props	Suffixes
rootClass	Class of the root element.
mobileClass	Class of the root element when on mobile. 👉 Switch to mobile view to see it in action!
sizeClass	Class of the root element with size.	size	small medium large
expandedClass	Class of the root element when expanded.	expanded
boxClass	Class of the box container element where you choose the date.
headerClass	Class of the header element inside the box.
prevButtonClass	Class of the prev button element inside the box.
nextButtonClass	Class of the next button element inside the box.
listsClass	Class of the month and year selects container inside the box.
footerClass	Class of the footer element.
tableClass	Class of the dates table element inside the box.
tableHeadClass	Class of dates table header element with days of the week.
tableHeadCellClass	Class of the cell element inside the table header.
tableBodyClass	Class of the table body element inside the box.
tableRowClass	Class of the table row element.
tableCellClass	Class of the table cell element.
tableCellInvisibleClass	Class of the table cell element when nearby month days are hidden.	nearbyMonthDays
tableCellSelectedClass	Class of table cell element when it is selected.
tableCellFirstSelectedClass	Class of the first selected table cell element when in range. 👉 See it in action selecting a date range.	range
tableCellWithinSelectedClass	Class of the table cell elements within the range when the range is selected. 👉 See it in action selecting a date range.	range
tableCellLastSelectedClass	Class of the last selected table cell element during range selection. 👉 See it in action selecting a date range.	range
tableCellFirstHoveredClass	Class of the first hovered table cell element during range selection. 👉 See it in action selecting a date range.	range
tableCellWithinHoveredClass	Class of the table cell element when hovered during range selection. 👉 See it in action selecting a date range	range
tableCellLastHoveredClass	Class of the last table cell element hovered during range selection. 👉 See it in action selecting a date range	range
tableCellTodayClass	Class of the table cell element of the current day.
tableCellSelectableClass	Class of the table cell element when selectable.
tableCellUnselectableClass	Class of the table cell element when unselectable.
tableCellNearbyClass	Class of the table cell element when nearby days (prev/next month) are selectable.	nearbySelectableMonthDays
tableCellEventsClass	Class of the cell element of a row when at least one event is present.
tableEventsClass	Class of the events container element.
tableEventClass	Class of the event element.
tableEventVariantClass	Class of the event element with variant.	events	primary info warning danger
tableEventIndicatorClass	Class of the event element with indicator.	indicators	bars dots *
monthClass	Class of the month table element inside the box when type is `month`.	type
monthTableClass	Class of the table container when type is `month`.
monthCellClass	Class of the table cell element when type is `month`.
monthCellSelectedClass	Class of table cell element when selected when type is `month`.
monthCellFirstSelectedClass	Class of the first selected table cell element when in range when type is `month`. 👉 See it in action selecting a date range	range
monthCellWithinSelectedClass	Class of the table cell elements within the range when the range is selected when type is `month`. 👉 See it in action selecting a date range	range
monthCellLastSelectedClass	Class of the last selected table cell element during range selection when type is `month`. 👉 See it in action selecting a date range	range
monthCellFirstHoveredClass	Class of the first hovered table cell element during range selection when type is `month`. 👉 See it in action selecting a date range	range
monthCellWithinHoveredClass	Class of the table cell element when hovered during range selection when type is `month`. 👉 See it in action selecting a date range	range
monthCellWithinHoveredRangeClass	Class of the table cell element when hovered during range selection and cell is in range when type is `month`. 👉 See it in action selecting a date range	range
monthCellLastHoveredClass	Class of the last table cell element when hovered during range selection when type is `month`. 👉 See it in action selecting a date range	range
monthCellTodayClass	Class of the table cell element of the current day when type is `month`.
monthCellSelectableClass	Class of the table cell element when selectable when type is `month`.
monthCellUnselectableClass	Class of the table cell element when unselectable when type is `month`.
monthCellEventsClass	Class of the events container when type is `month`.
monthEventsClass	Class of the events container element when type is `month`.
monthEventClass	Class of the event element when type is `month`.
monthEventVariantClass	Class of the event element with variant when type is `month`.	events	primary info warning danger
monthEventIndicatorClass	Class of the event element with indicator when type is `month`.	indicators	bars dots *
inputClass	Class to apply on the input element. More details here.
inputClasses	Classes to apply on the internal input component. More details here.
dropdownClass	Class to apply on the dropdown element. More details here.
dropdownClasses	Classes to apply on the internal dropdown component. More details here.
selectClasses	Classes to apply on the internal select component (month and year list). More details here.

Sass variables

Current theme ➜ Oruga

SASS Variable	Default
$datepicker-font-size	var(--#{$prefix}base-font-size)
$datepicker-box-padding	0.5rem 1rem
$datepicker-header-padding	0.5rem 0
$datepicker-header-spacer	0.5rem
$datepicker-header-border-bottom	1px solid var(--#{$prefix}grey-lighter)
$datepicker-footer-padding	0.5rem 0.5rem 0 0.5rem
$datepicker-footer-border-top	1px solid var(--#{$prefix}grey-lighter)
$datepicker-table-head-padding	0 0 0.875rem 0
$datepicker-table-head-margin	0 0 0.875rem 0
$datepicker-table-head-border-bottom	1px solid var(--#{$prefix}grey-lighter)
$datepicker-table-head-item-color	var(--#{$prefix}grey)
$datepicker-table-head-item-font-weight	600
$datepicker-item-today-border	solid 1px rgba(var(--#{$prefix}primary), 0.5)
$datepicker-item-selectable-color	var(--#{$prefix}grey-dark)
$datepicker-item-disabled-color	var(--#{$prefix}grey-light)
$datepicker-item-border-radius	var(--#{$prefix}base-border-radius)
$datepicker-item-padding	0.5rem 0.75rem
$datepicker-item-selected-color	var(--#{$prefix}primary-invert)
$datepicker-item-selected-background-color	var(--#{$prefix}primary)
$datepicker-item-selected-border-radius	0
$datepicker-item-selected-within-background-color	rgb( from $datepicker-item-selected-background-color r g b / 50%)
$datepicker-item-hovered-background-color	var(--#{$prefix}grey)
$datepicker-item-hovered-color	var(--#{$prefix}grey-lighter)
$datepicker-item-hovered-background-color	#f5f5f5
$datepicker-item-hovered-within-background-color	rgb( from $datepicker-item-hovered-background-color r g b / 50%)
$datepicker-item-nearby-color	var(--#{$prefix}grey-light)
$datepicker-events-item-padding	0.3rem 0.75rem 0.75rem
$datepicker-event-background-color	var(--#{$prefix}grey-light)
$datepicker-event-dots-size	0.35em
$datepicker-event-dots-margin	0 0.1em
$datepicker-event-bars-height	0.25em
$datepicker-btn-background-color	transparent
$datepicker-btn-border-color	var(--#{$prefix}grey-lighter)
$datepicker-btn-border-radius	var(--#{$prefix}base-border-radius)
$datepicker-btn-border	1px solid transparent
$datepicker-btn-color	#363636
$datepicker-btn-height	2.25em
$datepicker-btn-hover-border-color	var(--#{$prefix}grey-light)
$datepicker-btn-hover-color	#363636
$datepicker-btn-hover-background-color	transparent
$datepicker-btn-min-width	2.25em
$datepicker-btn-padding	0.5em 0.5em

See ➜ 📄 Full scss file

Current theme ➜ Bulma

SASS Variable	Default
$datepicker-colors	dv.$colors
$datepicker-header-color	css.getVar("grey")
$datepicker-header-spacer	0.5em
$datepicker-today-border	solid 1px rgba(css.getVar("primary"), 0.5)
$datepicker-item-color	css.getVar("grey-dark")
$datepicker-item-disabled-color	css.getVar("grey-light")
$datepicker-item-hover-color	css.getVar("scheme-invert")
$datepicker-item-hover-background-color	css.getVar("background")
$datepicker-item-selected-color	css.getVar("primary-invert")
$datepicker-item-selected-background-color	css.getVar("primary")
$datepicker-event-background-color	css.getVar("grey-light")

See ➜ 📄 Full scss file

Current theme ➜ Bootstrap

SASS Variable	Default
$datepicker-background-color	var(--#{$prefix}body-bg)
$datepicker-pagination-spacer	calc($spacer * 0.5)
$datepicker-section-spacer	calc($spacer * 0.75)
$datepicker-section-border	1px solid var(--#{$prefix}border-color)
$datepicker-cell-padding	0.5rem 0.75rem
$datepicker-cell-font-weight	400
$datepicker-cell-width	calc(#{100%} / 7)
$datepicker-cell-border-width	1px
$datepicker-cell-border-color	transparent
$datepicker-cell-border-radius	var(--#{$prefix}border-radius)
$datepicker-cell-color	var(--#{$prefix}black)
$datepicker-cell-bg	transparent
$datepicker-cell-hovered-color	var(--#{$prefix}secondary-contrast)
$datepicker-cell-hovered-bg	var(--#{$prefix}secondary)
$datepicker-cell-selected-color	var(--#{$prefix}primary-contrast)
$datepicker-cell-selected-bg	var(--#{$prefix}primary)
$datepicker-month-width	20rem
$datepicker-month-cell-spacer	calc($spacer * 0.5)
$datepicker-month-cell-height	2.5rem

See ➜ 📄 Full scss file