Calendar

TuiCalendar is a visual calendar component. It utilizes Day.js for underlying date calculations and supports features such as month-view navigation, to-do item marking, and custom date cell content. It is ideally suited for schedule management, attendance displays, or task boards.

Basic Usage

Default Display

Simply bind v-model to display the calendar. By default, Sunday is set as the start of the week.

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

const value = ref(new Date());
</script>

<template>
  <TuiCalendar v-model="value" />
</template>

Data Integration

To-do Items (Todos)

Pass an object to the todos attribute where the keys are date strings (formatted for Day.js parsing, preferably YYYY-MM-DD) and the values represent the number of to-do items. The component will automatically display a badge (Tag) on the corresponding dates.

• tagConfig: You can provide a TuiTag configuration object (e.g., { round: true, type: 'danger' }) to uniformly control the style of the markings.

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

const value = ref(new Date());
const todoData = ref({
  '2025-06-06': 3,
  '2025-06-07': 5,
  '2025-06-15': 1
});
</script>

<template>
  <TuiCalendar 
    v-model="value" 
    :todos="todoData" 
    :tagConfig="{ round: true }"
  />
</template>

Advanced Customization

Custom Cell Content (Slot)

Use the #date-cell="{ data }" slot to completely customize the rendering of the date grid. The data parameter includes:

• date: The Date object.
• day: The day number of the current date (e.g., '01', '15').
• todoCount: The quantity corresponding to the todos data.
• isSelected: Whether the date is currently selected.
• type: The date type ('prev-month', 'current-month', 'next-month').

<template>
  <TuiCalendar v-model="value" :todos="todoData">
    <template #date-cell="{ data }">
      <div class="custom-cell" :class="{ 'is-selected': data.isSelected }">
        <span class="day-num">{{ data.day }}</span>
        
        <div v-if="data.todoCount > 0" class="todo-info">
          <i class="tui-icon ti-bell"></i>
          <span>{{ data.todoCount }} To-do</span>
        </div>
      </div>
    </template>
  </TuiCalendar>
</template>

<style scoped>
.custom-cell { height: 100%; padding: 8px; }
.todo-info { font-size: 12px; color: #f56c6c; margin-top: 4px; }
</style>

Layout and Formatting

• weekStartsOn: Set to 'monday' to make Monday the start of the week.
• titleAlign: Alignment for the title bar (showing year and month) (left, center, right).
• cellAlign: Alignment for the content within the date cells.
• buttons: Controls the button group displayed in the top right; defaults to ['year', 'month', 'today'].

<TuiCalendar
  weekStartsOn="monday"
  titleAlign="center"
  cellAlign="center"
  :buttons="['month', 'today']"
  buttonSize="small"
/>

API Reference

Props

Property	Type	Default	Description
modelValue	Date/String	new Date()	The bound value.
todos	Object	{}	To-do item data mapping { 'YYYY-MM-DD': number }.
range	Array	[]	Time range, including start and end times [startDate, endDate].
weekStartsOn	String	'sunday'	The starting day of the week. Options: sunday, monday.
weekdayFormat	String	'weekdayShort'	Display format for the weekday column. Options: weekday, weekdayShort, weekdayMin.
buttons	Array	['year', 'month', 'today']	Buttons displayed in the header operation bar.
buttonSize	String	'default'	Button size.
titleAlign	String	'left'	Header title alignment. Options: left, center, right.
cellAlign	String	'left'	Date cell content alignment.
tagConfig	Object	-	Configuration object for the to-do marker Tag.

Events

Event Name	Description	Callback Parameters
update:modelValue	Triggered when the bound value changes.	(value: Date)
change	Triggered when the selected date changes.	(value: Date)
select	Triggered when a date cell is clicked.	(value: Date)

Slots

Slot Name	Description	Parameters
date-cell	Customizes the content of date cells.	{ data: { date, day, type, isSelected, todoCount } }

Exposed Methods

Method Name	Description	Parameters
selectDate	Selects a specific month type.	`(type: 'prev-month'
pickDay	Selects a specific date.	(day: Dayjs)
currentDateDayjs	Computed. The month currently displayed on the panel (Dayjs object).	-
selectedDateDayjs	Computed. The currently selected date (Dayjs object).	-