Calendar

날짜 격자의 활성 날짜를 따라 이동해 날짜를 고릅니다.

용법

월간 달력

완전한 한 달 격자에서 날짜를 이동하고 선택합니다.

<!-- Calendar / Month -->
<script setup lang="ts">
import { ref } from 'vue'
import {
  CalendarCell, CalendarContent, CalendarGrid,
  CalendarNextMonth, CalendarPreviousMonth, CalendarRoot,
  type DateValue,
} from '@sectile/vue/temporal/calendar'

const selected = ref<DateValue | null>(null)
const initial = { year: 2026, month: 8, day: 24 }
</script>

<template>
  <CalendarRoot v-model="selected" :default-highlighted-value="initial" default-view="month" v-slot="{ dates, view }" label="Release calendar">
    <CalendarContent>
      <header>
        <CalendarPreviousMonth>Previous</CalendarPreviousMonth>
        <strong>{{ view.year }}-{{ view.month }}</strong>
        <CalendarNextMonth>Next</CalendarNextMonth>
      </header>
      <CalendarGrid>
        <CalendarCell v-for="day in dates.flat()" :key="`${day.year}-${day.month}-${day.day}`" :value="day">
          {{ day.day }}
        </CalendarCell>
      </CalendarGrid>
    </CalendarContent>
  </CalendarRoot>
</template>

주간 달력

선택과 날짜 이동 기능을 유지하면서 한 주의 7일만 집중해 봅니다.

<!-- Calendar / Week -->
<script setup lang="ts">
import { ref } from 'vue'
import {
  CalendarCell, CalendarContent, CalendarGrid,
  CalendarNextWeek, CalendarPreviousWeek, CalendarRoot,
  type DateValue,
} from '@sectile/vue/temporal/calendar'

const selected = ref<DateValue | null>(null)
const initial = { year: 2026, month: 8, day: 24 }
</script>

<template>
  <CalendarRoot v-model="selected" :default-highlighted-value="initial" default-view="week" v-slot="{ dates, view }" label="Release calendar">
    <CalendarContent>
      <header>
        <CalendarPreviousWeek>Previous</CalendarPreviousWeek>
        <strong>{{ view.year }}-{{ view.month }}</strong>
        <CalendarNextWeek>Next</CalendarNextWeek>
      </header>
      <CalendarGrid>
        <CalendarCell v-for="day in dates.flat()" :key="`${day.year}-${day.month}-${day.day}`" :value="day">
          {{ day.day }}
        </CalendarCell>
      </CalendarGrid>
    </CalendarContent>
  </CalendarRoot>
</template>

주말 선택 제한

주말 날짜는 비활성 상태로 표시하고 평일 날짜를 선택합니다.

<!-- Calendar / Disabled Weekends -->
<script setup lang="ts">
import { ref } from 'vue'
import {
  CalendarCell, CalendarContent, CalendarGrid,
  CalendarNextMonth, CalendarPreviousMonth, CalendarRoot,
  type DateValue,
} from '@sectile/vue/temporal/calendar'

const selected = ref<DateValue | null>(null)
const initial = { year: 2026, month: 8, day: 24 }
const policies = { unavailable: (value: DateValue) => {
  const day = new Date(Date.UTC(value.year, value.month - 1, value.day)).getUTCDay()
  return day === 0 || day === 6
} }
</script>

<template>
  <CalendarRoot v-model="selected" :default-highlighted-value="initial" default-view="month" :policies="policies" v-slot="{ dates, view }" label="Release calendar">
    <CalendarContent>
      <header>
        <CalendarPreviousMonth>Previous</CalendarPreviousMonth>
        <strong>{{ view.year }}-{{ view.month }}</strong>
        <CalendarNextMonth>Next</CalendarNextMonth>
      </header>
      <CalendarGrid>
        <CalendarCell v-for="day in dates.flat()" :key="`${day.year}-${day.month}-${day.day}`" :value="day">
          {{ day.day }}
        </CalendarCell>
      </CalendarGrid>
    </CalendarContent>
  </CalendarRoot>
</template>

외부 상태 관리

현재 값은 부모가 관리하고, 허용된 변경을 컴포넌트에 다시 전달합니다.

<!-- Calendar / Controlled -->
<script setup lang="ts">
import { ref } from 'vue'
import {
  CalendarCell, CalendarContent, CalendarGrid,
  CalendarNextMonth, CalendarPreviousMonth, CalendarRoot,
  type DateValue,
} from '@sectile/vue/temporal/calendar'

const selected = ref<DateValue | null>(null)
const initial = { year: 2026, month: 8, day: 24 }
</script>

<template>
  <CalendarRoot v-model="selected" :default-highlighted-value="initial" default-view="month" v-slot="{ dates, view }" label="Release calendar">
    <CalendarContent>
      <header>
        <CalendarPreviousMonth>Previous</CalendarPreviousMonth>
        <strong>{{ view.year }}-{{ view.month }}</strong>
        <CalendarNextMonth>Next</CalendarNextMonth>
      </header>
      <CalendarGrid>
        <CalendarCell v-for="day in dates.flat()" :key="`${day.year}-${day.month}-${day.day}`" :value="day">
          {{ day.day }}
        </CalendarCell>
      </CalendarGrid>
    </CalendarContent>
  </CalendarRoot>
</template>

API

Vue 패키지: @sectile/vue/temporal/calendar

컴포넌트

CalendarRoot
CalendarContent
CalendarGrid
CalendarCell
CalendarMonthCell
CalendarInput
CalendarPreviousWeek
CalendarNextWeek
CalendarPreviousMonth
CalendarNextMonth
CalendarPreviousYear
CalendarNextYear
CalendarWeekViewTrigger
CalendarMonthViewTrigger
CalendarYearViewTrigger

Props

`CalendarRootProps`

defaultHighlightedValue: 타입DateValue기본값undefined
컴포넌트가 관리하는 처음 강조 값입니다.
defaultValue: 타입DateValue | null기본값null
컴포넌트가 값을 관리할 때 사용할 초깃값입니다.
defaultView: 타입CalendarViewMode기본값'month'
달력 또는 선택기의 초기 보기입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
highlightedValue: 타입DateValue기본값undefined
키보드 조작 대상으로 강조된 현재 값입니다.
label: 타입string기본값undefined
보조 기술이 읽는 컨트롤 이름입니다.
modelValue: 타입DateValue | null기본값undefined
부모가 상태를 관리할 때 사용할 현재 값입니다.
policies: 타입CalendarPolicies기본값undefined
검증, 이동, 선택 동작을 조정하는 정책입니다.
readonly: 타입boolean기본값false
값 확인만 허용하는 읽기 전용 상태 여부입니다.
referenceDate: 타입DateValue기본값undefined
달력의 선택값과 강조값을 초기화할 때 사용하는 민간 기준 날짜입니다.
required: 타입boolean기본값false
제출 전에 올바른 값이 반드시 있어야 하는지 여부입니다.

`CalendarCellProps`

as: 타입PrimitiveAs기본값'button'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
value: 타입DateValue기본값필수
이 계약이 노출하는 현재 값입니다.

`CalendarMonthCellProps`

as: 타입PrimitiveAs기본값'button'
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
value: 타입CalendarMonthValue기본값필수
이 계약이 노출하는 현재 값입니다.

`CalendarPartProps`

as: 타입PrimitiveAs기본값파트별로 다름
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값false
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.

슬롯

`CalendarRootSlotProps`

dates: 타입readonly (readonly DateValue[])[]
현재 보기에 표시할 날짜입니다.
disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
highlightedValue: 타입DateValue
조작 대상으로 강조된 현재 값입니다.
months: 타입readonly (readonly CalendarMonthValue[])[]
현재 보기에 표시할 달입니다.
readonly: 타입boolean
값 확인만 허용하는 읽기 전용 상태 여부입니다.
value: 타입DateValue | null
이 계약이 노출하는 현재 값입니다.
view: 타입{ readonly year: number; readonly month: number }
현재 달력 기준점입니다.
viewMode: 타입CalendarViewMode
현재 달력 보기 방식입니다.

`CalendarCellSlotProps`

disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
highlighted: 타입boolean
조작 대상으로 강조된 항목인지 여부입니다.
inRange: 타입boolean
선택한 범위 안에 있는 값인지 여부입니다.
outsideMonth: 타입boolean
인접한 달의 날짜인지 여부입니다.
selected: 타입boolean
현재 선택된 항목인지 여부입니다.
value: 타입DateValue
이 계약이 노출하는 현재 값입니다.

`CalendarMonthCellSlotProps`

disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
highlighted: 타입boolean
조작 대상으로 강조된 항목인지 여부입니다.
inRange: 타입boolean
선택한 범위 안에 있는 값인지 여부입니다.
selected: 타입boolean
현재 선택된 항목인지 여부입니다.
value: 타입CalendarMonthValue
이 계약이 노출하는 현재 값입니다.

이벤트

`CalendarRoot`

update:highlightedValue: 페이로드DateValue
새 강조 값을 요청할 때 발생합니다.
update:modelValue: 페이로드DateValue | null
컴포넌트가 외부 제어 값의 변경을 요청할 때 발생합니다.

기타 타입

`CalendarValueChangeHandler`

type CalendarValueChangeHandler = NonNullable<InstanceType<typeof CalendarRoot>['$props']['onUpdate:modelValue']>

`CalendarHighlightedValueChangeHandler`

type CalendarHighlightedValueChangeHandler = NonNullable<InstanceType<typeof CalendarRoot>['$props']['onUpdate:highlightedValue']>

`CalendarMonthValue`

이름	타입	필수
`year`	`number`	필수
`month`	`number`	필수

`CalendarPolicies`

이름	타입	필수
`min`	`DateValue`	—
`max`	`DateValue`	—
`required`	`boolean`	—
`unavailable`	`(value: DateValue) => boolean`	—
`weekStartsOn`	`1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7`	—
`maxScan`	`number`	—

`CalendarViewMode`

type CalendarViewMode = 'week' | 'month' | 'year'

`DateValue`

이름	타입	필수
`year`	`number`	필수
`month`	`number`	필수
`day`	`number`	필수

파트

공통 범위: [data-scope="calendar"]. 컴포넌트 내부로 스타일을 제한할 때 파트 선택자와 함께 사용합니다.

파트	선택자	역할	추가 속성
`content`	`[data-part="content"]`	현재 상태에 맞는 컴포넌트 콘텐츠를 담습니다.	—
`input`	`[data-part="input"]`	선택한 날짜를 네이티브 폼 제출 값으로 유지합니다.	—
`week-view-trigger`	`[data-part="week-view-trigger"]`	달력을 주 보기로 전환합니다.	—
`month-view-trigger`	`[data-part="month-view-trigger"]`	달력을 월 보기로 전환합니다.	—
`year-view-trigger`	`[data-part="year-view-trigger"]`	달력을 년 보기로 전환합니다.	—
`previous-week`	`[data-part="previous-week"]`	이전 주(으)로 이동합니다.	—
`next-week`	`[data-part="next-week"]`	다음 주(으)로 이동합니다.	—
`previous-month`	`[data-part="previous-month"]`	이전 월(으)로 이동합니다.	—
`next-month`	`[data-part="next-month"]`	다음 월(으)로 이동합니다.	—
`previous-year`	`[data-part="previous-year"]`	이전 년(으)로 이동합니다.	—
`next-year`	`[data-part="next-year"]`	다음 년(으)로 이동합니다.	—
`grid`	`[data-part="grid"]`	셀을 탐색 가능한 2차원 구조로 묶습니다.	—
`cell`	`[data-part="cell"]`	탐색하거나 선택할 수 있는 그리드 값 하나입니다.	—
`month-cell`	`[data-part="month-cell"]`	선택할 수 있는 월 하나입니다.	—

키보드 동작

키	동작
`Arrow Left` / `Arrow Right`	하루 전 또는 다음 날로 이동합니다.
`Arrow Up` / `Arrow Down`	일주일 전 또는 다음 주로 이동합니다.
`Home` / `End`	한 주의 시작 또는 끝으로 이동합니다.
`Page Up` / `Page Down`	한 달 단위로 이동하고, Shift와 함께 누르면 일 년 단위로 이동합니다.
`Enter` / `Space`	현재 강조된 날짜를 선택합니다.

접근성

인라인 콘텐츠가 이름 있는 격자를 소유하며 각 칸은 선택·강조·선택 불가·현재 달 외부 상태를 노출합니다.

관련 WAI-ARIA 패턴에서 호스트 접근성 규칙을 확인할 수 있습니다.

Calendar ​

용법 ​

월간 달력 ​

주간 달력 ​

주말 선택 제한 ​

외부 상태 관리 ​

API ​

Props ​

CalendarRootProps ​

CalendarCellProps ​

CalendarMonthCellProps ​

CalendarPartProps ​

슬롯 ​

CalendarRootSlotProps ​

CalendarCellSlotProps ​

CalendarMonthCellSlotProps ​

이벤트 ​

CalendarRoot ​

기타 타입 ​

CalendarValueChangeHandler ​

CalendarHighlightedValueChangeHandler ​

CalendarMonthValue ​

CalendarPolicies ​

CalendarViewMode ​

DateValue ​

파트 ​

키보드 동작 ​

접근성 ​