Calendar

A container for displaying data in calendar form.

When to Use

Use when you need to display a set of data in calendar form, or let users select a date.

Basic Usage

Use v-model for date selection. Default week starts on Monday.

<TCalendar v-model="selectedDate" />

Controlled Mode

Pass a preset value and the calendar will automatically highlight the corresponding date.

const presetDate = ref('2026-06-01')
<TCalendar v-model="presetDate" />

Show Week Numbers

Set show-week to display ISO week numbers on the left column.

<TCalendar show-week />

Auto Switch Month

Click on dates from previous or next month (shown in gray), and the calendar will automatically navigate to that month and select the date.

<TCalendar v-model="selectedDate" />

Custom First Day of Week

Set first-day-of-week="0" to start the week on Sunday.

<TCalendar :first-day-of-week="0" show-week />

Range Restriction

Use min and max to restrict selectable date range.

<TCalendar min="2026-01-01" max="2026-01-31" />

Custom Disabled Dates

Use disabled-date prop to dynamically control which dates are disabled.

const isWeekend = (date) => {
  const d = new Date(date);
  return d.getDay() === 0 || d.getDay() === 6;
}
<TCalendar :disabled-date="isWeekend" />

Range Selection

Set range to enable range selection mode. Use v-model:range-start and v-model:range-end for two-way binding. Click the first date as start, then the second as end. A third click starts a new range.

const rangeStart = ref('2026-01-01')
const rangeEnd = ref('2026-01-14')

<TCalendar
  range
  v-model:range-start="rangeStart"
  v-model:range-end="rangeEnd"
/>

Internationalization

Pass a custom locale object to fully customize week day names, month names, button text, and year format.

const enLocale = {
  weekDays: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun'],
  months: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
    'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
  today: 'Back to Today',
  week: 'Wk',
  yearFormat: '{y}',
  prevMonth: 'Prev Month',
  nextMonth: 'Next Month',
  prevYear: 'Prev Year',
  nextYear: 'Next Year',
}

<TCalendar :locale="enLocale" show-week />

Fullscreen Mode

Set fullscreen to enable large-size calendar, suitable for embedding in page content areas.

<TCalendar fullscreen />

Mini Mode

Set mini for a compact layout. No content area, centered core info, smaller spacing. Ideal for sidebars, cards, and small spaces.

<TCalendar mini />
<TCalendar mini show-week />
<TCalendar mini mode="year" />

Lock View

Set lockView to freeze the current view mode. Hides the mode switch buttons. Clicking a month in year view navigates without switching views.

<TCalendar lockView="y" mini />

Hide View Switch

Set show-view-switch to false to hide the view switch buttons.

<TCalendar :show-view-switch="false" />

Week Select Mode

Set week-select to enable week selection. Click any date to select the entire week. The v-model value uses ISO week format (e.g., 2026-W29).

<TCalendar week-select show-week />

Custom Week Format

Use week-format to customize the value format. Supports {y} (year) and {wk} (week number) placeholders.

<TCalendar week-select week-format="W{wk}-{y}" show-week />

Read-Only Mode

Set readonly to disable all selection operations. Ideal for displaying confirmed dates, weeks, or months.

<TCalendar :model-value="'2026-06-01'" readonly />
<TCalendar :model-value="'2026-06-01'" readonly mode="year" />
<TCalendar week-select readonly week-format="W{wk}-{y}" show-week />

API

TCalendar Props

Prop	Description	Type	Default
model-value	Selected date (v-model, format YYYY-MM-DD)	string | null	null
min	Minimum selectable date	string	undefined
max	Maximum selectable date	string	undefined
first-day-of-week	First day of week: 0=Sunday, 1=Monday	0 | 1	1
disabled-date	Custom disabled date function	(date: string) => boolean	undefined
fullscreen	Fullscreen/large mode	boolean	false
show-week	Show ISO week number column	boolean	false
range	Enable range selection mode	boolean	false
range-start	Range start date (v-model:range-start)	string | null	null
range-end	Range end date (v-model:range-end)	string | null	null
mode	View mode	'year' | 'month' | 'week'	'month'
locale	Internationalization config	CalendarLocale	defaultLocale
lock-view	Lock view: y=year, m=month, w=week	'y' | 'm' | 'w'	undefined
show-view-switch	Show view switch buttons	boolean	true
mini	Mini mode (no content area, centered)	boolean	false
week-select	Enable week selection mode	boolean	false
week-format	Week value format template	string	'{y}-W{wk}'
readonly	Read-only mode (disable selection)	boolean	false

TCalendar Events

Event	Description	Parameters
update:model-value	Single mode date changed	(value: string) => void
update:mode	View mode changed	(value: 'year' | 'month' | 'week') => void
update:range-start	Range start changed	(value: string | null) => void
update:range-end	Range end changed	(value: string | null) => void
change	Date selected	(value: string | { start, end }) => void
panel-change	Panel year/month changed	(year: number, month: number) => void

TCalendar Slots

Slot	Description	Scoped Props
cell	Fully customize the entire cell	{ day: CalendarDay }: date, day, isCurrentMonth, isToday, isSelected, isDisabled, weekNumber, isRangeStart, isRangeEnd, isInRange
cell-content	Customize the inner content area (works in year/month/week views)	{ cell: CalendarDay | CalendarMonthCell | CalendarWeekDay, mode: 'year' | 'month' | 'week' }

TCalendar Exposed Methods

Method	Description	Parameters
goToDate	Navigate to specific year/month	(year: number, month?: number)
goToToday	Navigate back to today	-
currentYear	Current display year (readonly)	-
currentMonthNum	Current display month 1-12 (readonly)	-
resetRange	Reset range selection state	-