If the calendar needs a field, take the ready CdsDateInput — it assembles the very same thing out of a field, a menu and this calendar, adding manual input and time. For picking the time alone there is CdsTimePicker.

Anatomy

The calendar consists of an optional header with the summary of the choice, the month and year navigation, the grid of days and the actions zone. The header is turned on by header, the "Today" button — by today-btn, and the actions are added into the default slot.

Storybook

Variations

Value and format

The chosen date arrives in v-model as a string in the mask format — DD.MM.YYYY by default. A repeated click on the selected day clears the selection; no-unset forbids such a reset, and hide-sibling-month hides the days of the neighboring months.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDatePicker v-model="value" />

    <span class="text-200 text-content-secondary">Значение: {{ value ?? '—' }}</span>
  </div>
</template>

Header

header turns on the header with the summary of the choice: the title shows the date or the number of the chosen days, the description — the year. The texts are replaced by the title and description props or by the slots of the same name. today-btn adds a button that brings you back to the current day.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" header today-btn />
  </div>
</template>

A date range

range switches the calendar to picking a period: the first click fixes the start (the range-start event), the second one — the end (range-end), and the value arrives as a { from, to } object. Together with multiple several periods can be picked.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<{ from: string; to: string } | string | null>(null);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDatePicker v-model="value" range header />

    <span class="text-200 text-content-secondary">Значение: {{ value ? JSON.stringify(value) : '—' }}</span>
  </div>
</template>

Several dates

multiple allows marking individual dates — the model becomes an array of strings.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string[]>([]);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsDatePicker v-model="value" multiple header />

    <span class="text-200 text-content-secondary">Значение: {{ JSON.stringify(value) }}</span>
  </div>
</template>

Events

events marks dates with dots: it accepts an array of dates in the YYYY/MM/DD format or a predicate function. The color of a dot is set by events-color — as a string or as a function of the date, when there are several types of events.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
const now = new Date();
const ym = `${now.getFullYear()}/${String(now.getMonth() + 1).padStart(2, '0')}`;
const events = [`${ym}/05`, `${ym}/12`, `${ym}/20`];
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" :events="events" events-color="success" />
  </div>
</template>

Available dates

allowed-dates limits the choice: an array of dates or a function that receives a YYYY/MM/DD date and returns whether it can be picked. The rest of the days are turned off.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
// Разрешаем выбирать только будни.
const allowedDates = (date: string) => {
  const [y, m, d] = date.split('/').map(Number);
  const day = new Date(y, m - 1, d).getDay();
  return day !== 0 && day !== 6;
};
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" :allowed-dates="allowedDates" />
  </div>
</template>

Navigation bounds

min-year-month and max-year-month (the YYYY/MM format) do not let you go beyond the range — the arrows at the bound are turned off. Watch the moves between months through the navigation event.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
const year = new Date().getFullYear();
const min = `${year}/01`;
const max = `${year}/12`;
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" :min-year-month="min" :max-year-month="max" />
  </div>
</template>

Starting view

view opens the calendar right at the list of months (Months) or years (Years) — handy for dates far from the current one. default-year-month sets the starting month when the model is empty.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" view="Months" />
  </div>
</template>

Localization

locale accepts a locale name (ru | en) or your own object of translations; without the prop the locale of the application is used. first-day-of-week sets the first day of the week — for en it is usually Sunday.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const value = ref<string | null>(null);
</script>

<template>
  <div class="w-fit m-auto">
    <CdsDatePicker v-model="value" locale="en" :first-day-of-week="0" header />
  </div>
</template>

States

disabled turns the calendar off and dims it, readonly keeps the usual look but blocks both the selection and the navigation.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const now = new Date();
const value = ref(`15.${String(now.getMonth() + 1).padStart(2, '0')}.${now.getFullYear()}`);
</script>

<template>
  <div class="flex flex-wrap justify-center gap-2">
    <div class="w-fit">
      <CdsDatePicker v-model="value" disabled header />
    </div>

    <div class="w-fit">
      <CdsDatePicker v-model="value" readonly header />
    </div>
  </div>
</template>

Guidelines

Storybook

Scenarios

A field with a date

Most often the calendar lives not on the page but in a menu next to a text field. CdsDateInput exists for that — it is already assembled out of a field, a menu and the calendar, it parses the manual input and accepts all the calendar props directly. Build the control yourself only if you need a non-standard scheme: out of CdsTextInput, a CdsMenu with activator="parent" and the calendar — that way all the props and slots of the field and the menu stay available to you. In that case add the input mask yourself: we recommend the lightweight (2.5 KB) Maska library.

Sandbox Storybook

<script setup lang="ts">
import { CdsDatePicker, CdsMenu, CdsTextInput } from '@central-design-system/components';
import { vMaska } from 'maska/vue';
import { ref } from 'vue';

const date = ref('22.02.2022');
</script>

<template>
  <div class="w-[250px] m-auto">
    <CdsTextInput
      v-model="date"
      v-maska="'##.##.####'"
      label="Дата"
      placeholder="Выберите дату"
      append-inner-icon="calendar"
    >
      <CdsMenu activator="parent" :close-on-content-click="false">
        <CdsDatePicker v-model="date" />
      </CdsMenu>
    </CdsTextInput>
  </div>
</template>

A reporting period

The default slot adds actions under the calendar. Here the chosen range is a draft: it gets into the report only after the "Apply" button, while "Reset" returns the calendar to its initial state.

Sandbox Storybook

<script setup lang="ts">
import { CdsButton, CdsCard, CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

type TRange = { from: string; to: string };

const draft = ref<TRange | string | null>(null);
const period = ref<string | null>(null);

function apply() {
  if (!draft.value) {
    period.value = null;
  } else if (typeof draft.value === 'string') {
    period.value = draft.value;
  } else {
    period.value = `${draft.value.from} — ${draft.value.to}`;
  }
}

function reset() {
  draft.value = null;
  period.value = null;
}
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCard class="w-fit">
      <CdsDatePicker v-model="draft" range header>
        <div class="flex justify-end gap-2">
          <CdsButton variant="soft" color="neutral" size="sm" text="Сбросить" @click="reset" />
          <CdsButton size="sm" text="Принять" @click="apply" />
        </div>
      </CdsDatePicker>
    </CdsCard>

    <span class="text-200 text-content-secondary">Период отчёта: {{ period ?? 'не выбран' }}</span>
  </div>
</template>

A delivery date

The restrictions work together: allowed-dates leaves only the weekdays, and min-year-month and max-year-month do not let you go beyond the nearest two months — the unavailable options do not even have to be explained.

Sandbox Storybook

<script setup lang="ts">
import { CdsCard, CdsDatePicker } from '@central-design-system/components';
import { ref } from 'vue';

const date = ref<string | null>(null);

const pad = (value: number) => String(value).padStart(2, '0');

// Доставка доступна по будням в ближайшие два месяца.
const now = new Date();
const firstDay = new Date(now.getFullYear(), now.getMonth(), now.getDate());
const lastDay = new Date(now.getFullYear(), now.getMonth() + 2, 0);

const min = `${firstDay.getFullYear()}/${pad(firstDay.getMonth() + 1)}`;
const max = `${lastDay.getFullYear()}/${pad(lastDay.getMonth() + 1)}`;

const allowedDates = (hash: string) => {
  const [year, month, day] = hash.split('/').map(Number);
  const candidate = new Date(year, month - 1, day);
  const weekday = candidate.getDay();

  return weekday !== 0 && weekday !== 6 && candidate >= firstDay && candidate <= lastDay;
};
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCard class="w-fit">
      <CdsDatePicker v-model="date" :allowed-dates="allowedDates" :min-year-month="min" :max-year-month="max" />
    </CdsCard>

    <span class="text-200 text-content-secondary">
      {{ date ? `Привезём ${date} с 10:00 до 18:00` : 'Выберите дату доставки' }}
    </span>
  </div>
</template>

Date and time

The calendar does not pick the time — put a CdsTimePicker next to it with a shared model and the same DD.MM.YYYY HH:mm mask: every component changes its own part of the string. In a field the very same thing is turned on by a single prop — with-time on CdsDateInput.

Sandbox Storybook

<script setup lang="ts">
import { CdsCard, CdsDatePicker, CdsDivider, CdsTimePicker } from '@central-design-system/components';
import { ref } from 'vue';

const now = new Date();
const dateTime = ref(`15.${String(now.getMonth() + 1).padStart(2, '0')}.${now.getFullYear()} 12:35`);
</script>

<template>
  <div class="flex flex-col items-center gap-2">
    <CdsCard class="flex w-fit flex-col">
      <CdsDatePicker v-model="dateTime" mask="DD.MM.YYYY HH:mm" header today-btn />
      <CdsDivider />
      <CdsTimePicker v-model="dateTime" mask="DD.MM.YYYY HH:mm" />
    </CdsCard>

    <span class="text-200 text-content-secondary">Значение: {{ dateTime }}</span>
  </div>
</template>

API

Props

Name	Type	Default	Description
allowedDates	TCalendarAllowedDates | undefined	—	Array of dates available in the calendar. When a function is used, it receives the date in the YYYY/MM/DD format and must return true or false.
defaultYearMonth	string | undefined	—	Displayed year/month in the YYYY/MM format. The current year/month by default when v-model is not set.
description	string | undefined	—	Description of the calendar. Shown in the calendar header.
disabled	boolean | null | undefined	null	Disabled state
emitImmediately	boolean | undefined	—	Emit the update:modelValue event right when the month or the year changes. Not available with multiple and range.
events	TCalendarEvents | undefined	—	List of events shown in the calendar. Format: YYYY/MM/DD.
eventsColor	TCalendarEventsColor | undefined	'default'	Color of the events in the calendar.
firstDayOfWeek	string | number | undefined	1	First day of the week (Monday by default).
header	boolean | undefined	—	Show the calendar header
hideSiblingMonth	boolean | undefined	—	Hide the days of the neighboring months in the calendar.
locale	string | TDateLocale | undefined	—	Locale for the dates. A locale name ('ru' | 'en') or a TDateLocale object. The current locale from useLocale is taken by default, otherwise ru.
mask	string | undefined	'DD.MM.YYYY'	Date/time format
maxYearMonth	string | undefined	—	Forbid navigating the calendar past the given maximum date in the YYYY/MM format.
minYearMonth	string | undefined	—	Forbid navigating the calendar before the given minimum date in the YYYY/MM format.
modelValue	string | TDatetimeValueRange | (string | TDatetimeValueRange)[] | null | undefined	null	Value of the model
multiple	boolean | undefined	—	Allows selecting several dates. The v-model must be an array.
noUnset	boolean | undefined	—	Forbid resetting the date in the calendar.
range	boolean | undefined	—	Allows selecting a range of dates. The v-model must be an array.
readonly	boolean | null | undefined	null	Read-only state
theme	string | undefined	—	Component theme
title	string | undefined	—	Title of the calendar. Shown in the calendar header.
todayBtn	boolean | undefined	—	Show the "Today" button in the calendar header
view	"Calendar" | "Years" | "Months" | undefined	'Calendar'	Default calendar view. Possible values: 'Calendar', 'Years', 'Months'.

Events

Name	Type	Description
navigation	[payload: { year: number | undefined; month: number | undefined; }]	Navigation to another month or year (also fires when the model is changed from outside).
rangeEnd	[payload: { from: Partial<IRawDate>; to: Partial<IRawDate>; }]	End of a date range selection.
rangeStart	[value: Partial<IRawDate>]	Start of a date range selection.
update:modelValue	[value: string | TDatetimeValueRange | (string | TDatetimeValueRange)[] | null, reason: string, details: Partial<IRawDate>]	The value changed (v-model). Passes the value, the reason of the change and the details of the date.

Slots

Name	Type	Description
default	any	Additional buttons under the calendar.
description	{ year: string | number | undefined; }	Description of the title.
title	{ date: string; }	Title of the calendar.

Exposed

Name	Type	Description
offsetCalendar	(type: "year" | "month", descending: number) => void	Moves the calendar one step forward or backward by months or by years.
setCalendarTo	(year: number, month: number) => void	Scrolls the calendar to the given year and month without changing the selected value.
setEditingRange	(from: IRawDate, to: IRawDate) => void	Sets the highlighted date range in range mode without confirming the selection.
setToday	() => void	Selects today's date and scrolls the calendar to the current month.
setView	(viewMode: "Calendar" | "Years" | "Months") => void	Switches the calendar view: days, months or years.