Date Range Picker

여러 달을 이동하며 양 끝을 포함하는 날짜 범위를 고릅니다.

용법

예약

예약의 시작일과 종료일을 양 끝을 포함하는 범위로 선택합니다.

<!-- Date Range Picker / Booking -->
<script setup lang="ts">
import { DateRangePickerRoot, DateRangePickerAnchor, DateRangePickerStartInput, DateRangePickerEndInput, DateRangePickerTrigger, DateRangePickerContent, DateRangePickerPreviousWeek, DateRangePickerPreviousMonth, DateRangePickerPreviousYear, DateRangePickerNextWeek, DateRangePickerNextMonth, DateRangePickerNextYear, DateRangePickerWeekViewTrigger, DateRangePickerMonthViewTrigger, DateRangePickerYearViewTrigger, DateRangePickerGrid, DateRangePickerCell, DateRangePickerMonthCell } from '@sectile/vue/date-range-picker'
import { CalendarDays } from '@lucide/vue'
const initialRange = {
  start: { year: 2026, month: 8, day: 22 },
  end: { year: 2026, month: 8, day: 25 },
}
const unavailableDates = new Set(['2026-08-27', '2026-08-29'])
const policies = {
  unavailable: (value: { year: number; month: number; day: number }) =>
    unavailableDates.has(
      [value.year, String(value.month).padStart(2, '0'), String(value.day).padStart(2, '0')].join('-'),
    ),
}
const monthNames = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

</script>

<template>
  <DateRangePickerRoot :default-value="initialRange" :policies="policies" v-slot="{ dates, months, view, viewMode }" class="catalog-stack catalog-temporal-picker">
    <DateRangePickerAnchor class="catalog-inline">
      <DateRangePickerStartInput class="catalog-input" />
      <DateRangePickerEndInput class="catalog-input" />
      <DateRangePickerTrigger class="catalog-picker-trigger" aria-label="Open date range picker">
        <CalendarDays :size="18" aria-hidden="true" />
      </DateRangePickerTrigger>
    </DateRangePickerAnchor>
    <DateRangePickerContent class="catalog-popup catalog-picker-popup catalog-picker-popup--floating">
      <div class="catalog-picker-toolbar">
        <div class="catalog-inline">
          <DateRangePickerPreviousWeek v-if="viewMode === 'week'">‹</DateRangePickerPreviousWeek>
          <DateRangePickerPreviousMonth v-else-if="viewMode === 'month'">‹</DateRangePickerPreviousMonth>
          <DateRangePickerPreviousYear v-else>‹</DateRangePickerPreviousYear>
          <strong>{{ viewMode === 'year' ? view.year : monthNames[view.month - 1] + ' ' + view.year }}</strong>
          <DateRangePickerNextWeek v-if="viewMode === 'week'">›</DateRangePickerNextWeek>
          <DateRangePickerNextMonth v-else-if="viewMode === 'month'">›</DateRangePickerNextMonth>
          <DateRangePickerNextYear v-else>›</DateRangePickerNextYear>
        </div>
        <div class="catalog-view-switch">
          <DateRangePickerWeekViewTrigger>Week</DateRangePickerWeekViewTrigger>
          <DateRangePickerMonthViewTrigger>Month</DateRangePickerMonthViewTrigger>
          <DateRangePickerYearViewTrigger>Year</DateRangePickerYearViewTrigger>
        </div>
      </div>

      <DateRangePickerGrid v-if="viewMode !== 'year'" class="catalog-calendar" :data-view="viewMode">
        <DateRangePickerCell
          v-for="day in dates.flat()"
          :key="[day.year, day.month, day.day].join('-')"
          :value="day"
        >
          {{ day.day }}
        </DateRangePickerCell>
      </DateRangePickerGrid>
      <DateRangePickerGrid v-else class="catalog-month-grid">
        <DateRangePickerMonthCell
          v-for="month in months.flat()"
          :key="[month.year, month.month].join('-')"
          :value="month"
        >
          {{ monthNames[month.month - 1] }}
        </DateRangePickerMonthCell>
      </DateRangePickerGrid>
    </DateRangePickerContent>
  </DateRangePickerRoot>
</template>

범위 제한

입력값을 설정한 최솟값과 최댓값 범위 안에서 확정합니다.

<!-- Date Range Picker / Bounded -->
<script setup lang="ts">
import { DateRangePickerRoot, DateRangePickerAnchor, DateRangePickerStartInput, DateRangePickerEndInput, DateRangePickerTrigger, DateRangePickerContent, DateRangePickerPreviousWeek, DateRangePickerPreviousMonth, DateRangePickerPreviousYear, DateRangePickerNextWeek, DateRangePickerNextMonth, DateRangePickerNextYear, DateRangePickerWeekViewTrigger, DateRangePickerMonthViewTrigger, DateRangePickerYearViewTrigger, DateRangePickerGrid, DateRangePickerCell, DateRangePickerMonthCell } from '@sectile/vue/date-range-picker'
import { CalendarDays } from '@lucide/vue'
const initialRange = {
  start: { year: 2026, month: 8, day: 22 },
  end: { year: 2026, month: 8, day: 25 },
}
const unavailableDates = new Set(['2026-08-27', '2026-08-29'])
const policies = {
  unavailable: (value: { year: number; month: number; day: number }) =>
    unavailableDates.has(
      [value.year, String(value.month).padStart(2, '0'), String(value.day).padStart(2, '0')].join('-'),
    ),
}
const monthNames = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']

</script>

<template>
  <DateRangePickerRoot :default-value="initialRange" :policies="policies" v-slot="{ dates, months, view, viewMode }" class="catalog-stack catalog-temporal-picker">
    <DateRangePickerAnchor class="catalog-inline">
      <DateRangePickerStartInput class="catalog-input" />
      <DateRangePickerEndInput class="catalog-input" />
      <DateRangePickerTrigger class="catalog-picker-trigger" aria-label="Open date range picker">
        <CalendarDays :size="18" aria-hidden="true" />
      </DateRangePickerTrigger>
    </DateRangePickerAnchor>
    <DateRangePickerContent class="catalog-popup catalog-picker-popup catalog-picker-popup--floating">
      <div class="catalog-picker-toolbar">
        <div class="catalog-inline">
          <DateRangePickerPreviousWeek v-if="viewMode === 'week'">‹</DateRangePickerPreviousWeek>
          <DateRangePickerPreviousMonth v-else-if="viewMode === 'month'">‹</DateRangePickerPreviousMonth>
          <DateRangePickerPreviousYear v-else>‹</DateRangePickerPreviousYear>
          <strong>{{ viewMode === 'year' ? view.year : monthNames[view.month - 1] + ' ' + view.year }}</strong>
          <DateRangePickerNextWeek v-if="viewMode === 'week'">›</DateRangePickerNextWeek>
          <DateRangePickerNextMonth v-else-if="viewMode === 'month'">›</DateRangePickerNextMonth>
          <DateRangePickerNextYear v-else>›</DateRangePickerNextYear>
        </div>
        <div class="catalog-view-switch">
          <DateRangePickerWeekViewTrigger>Week</DateRangePickerWeekViewTrigger>
          <DateRangePickerMonthViewTrigger>Month</DateRangePickerMonthViewTrigger>
          <DateRangePickerYearViewTrigger>Year</DateRangePickerYearViewTrigger>
        </div>
      </div>

      <DateRangePickerGrid v-if="viewMode !== 'year'" class="catalog-calendar" :data-view="viewMode">
        <DateRangePickerCell
          v-for="day in dates.flat()"
          :key="[day.year, day.month, day.day].join('-')"
          :value="day"
        >
          {{ day.day }}
        </DateRangePickerCell>
      </DateRangePickerGrid>
      <DateRangePickerGrid v-else class="catalog-month-grid">
        <DateRangePickerMonthCell
          v-for="month in months.flat()"
          :key="[month.year, month.month].join('-')"
          :value="month"
        >
          {{ monthNames[month.month - 1] }}
        </DateRangePickerMonthCell>
      </DateRangePickerGrid>
    </DateRangePickerContent>
  </DateRangePickerRoot>
</template>

외부 상태 관리

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

<!-- Date Range Picker / Controlled -->
<script setup lang="ts">
import { ref } from 'vue'
import { DateRangePickerRoot, DateRangePickerAnchor, DateRangePickerStartInput, DateRangePickerEndInput, DateRangePickerTrigger, DateRangePickerContent, DateRangePickerPreviousWeek, DateRangePickerPreviousMonth, DateRangePickerPreviousYear, DateRangePickerNextWeek, DateRangePickerNextMonth, DateRangePickerNextYear, DateRangePickerWeekViewTrigger, DateRangePickerMonthViewTrigger, DateRangePickerYearViewTrigger, DateRangePickerGrid, DateRangePickerCell, DateRangePickerMonthCell } from '@sectile/vue/date-range-picker'
import { CalendarDays } from '@lucide/vue'
const initialRange = {
  start: { year: 2026, month: 8, day: 22 },
  end: { year: 2026, month: 8, day: 25 },
}
const unavailableDates = new Set(['2026-08-27', '2026-08-29'])
const policies = {
  unavailable: (value: { year: number; month: number; day: number }) =>
    unavailableDates.has(
      [value.year, String(value.month).padStart(2, '0'), String(value.day).padStart(2, '0')].join('-'),
    ),
}
const monthNames = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']


const value = ref(initialRange)
</script>

<template>
  <DateRangePickerRoot v-model="value" :policies="policies" v-slot="{ dates, months, view, viewMode }" class="catalog-stack catalog-temporal-picker">
    <DateRangePickerAnchor class="catalog-inline">
      <DateRangePickerStartInput class="catalog-input" />
      <DateRangePickerEndInput class="catalog-input" />
      <DateRangePickerTrigger class="catalog-picker-trigger" aria-label="Open date range picker">
        <CalendarDays :size="18" aria-hidden="true" />
      </DateRangePickerTrigger>
    </DateRangePickerAnchor>
    <DateRangePickerContent class="catalog-popup catalog-picker-popup catalog-picker-popup--floating">
      <div class="catalog-picker-toolbar">
        <div class="catalog-inline">
          <DateRangePickerPreviousWeek v-if="viewMode === 'week'">‹</DateRangePickerPreviousWeek>
          <DateRangePickerPreviousMonth v-else-if="viewMode === 'month'">‹</DateRangePickerPreviousMonth>
          <DateRangePickerPreviousYear v-else>‹</DateRangePickerPreviousYear>
          <strong>{{ viewMode === 'year' ? view.year : monthNames[view.month - 1] + ' ' + view.year }}</strong>
          <DateRangePickerNextWeek v-if="viewMode === 'week'">›</DateRangePickerNextWeek>
          <DateRangePickerNextMonth v-else-if="viewMode === 'month'">›</DateRangePickerNextMonth>
          <DateRangePickerNextYear v-else>›</DateRangePickerNextYear>
        </div>
        <div class="catalog-view-switch">
          <DateRangePickerWeekViewTrigger>Week</DateRangePickerWeekViewTrigger>
          <DateRangePickerMonthViewTrigger>Month</DateRangePickerMonthViewTrigger>
          <DateRangePickerYearViewTrigger>Year</DateRangePickerYearViewTrigger>
        </div>
      </div>

      <DateRangePickerGrid v-if="viewMode !== 'year'" class="catalog-calendar" :data-view="viewMode">
        <DateRangePickerCell
          v-for="day in dates.flat()"
          :key="[day.year, day.month, day.day].join('-')"
          :value="day"
        >
          {{ day.day }}
        </DateRangePickerCell>
      </DateRangePickerGrid>
      <DateRangePickerGrid v-else class="catalog-month-grid">
        <DateRangePickerMonthCell
          v-for="month in months.flat()"
          :key="[month.year, month.month].join('-')"
          :value="month"
        >
          {{ monthNames[month.month - 1] }}
        </DateRangePickerMonthCell>
      </DateRangePickerGrid>
    </DateRangePickerContent>
  </DateRangePickerRoot>
</template>

Floating 위치

이 컴포넌트는 공통 위치 엔진을 사용합니다. 실시간 위치 예시에서 side, align, 간격, 충돌 경계, strategy, tracking을 바꾸며 계산 결과를 확인할 수 있습니다.

API

Vue 패키지: @sectile/vue/temporal/date-range-picker

컴포넌트

DateRangePickerRoot
DateRangePickerTrigger
DateRangePickerAnchor
DateRangePickerPortal
DateRangePickerContent
DateRangePickerGrid
DateRangePickerCell
DateRangePickerMonthCell
DateRangePickerStartInput
DateRangePickerEndInput
DateRangePickerPreviousWeek
DateRangePickerNextWeek
DateRangePickerPreviousMonth
DateRangePickerNextMonth
DateRangePickerPreviousYear
DateRangePickerNextYear
DateRangePickerWeekViewTrigger
DateRangePickerMonthViewTrigger
DateRangePickerYearViewTrigger

Props

`DateRangePickerRootProps`

align: 타입PickerPositionOptions['align']기본값'center'
기준 요소를 중심으로 팝업 내용을 정렬할 위치입니다.
as: 타입PrimitiveAs기본값undefined
이 파트가 렌더링할 요소 또는 컴포넌트입니다.
asChild: 타입boolean기본값undefined
하나뿐인 자식 요소에 파트 속성을 직접 합칠지 여부입니다.
avoidCollisions: 타입boolean기본값true
팝업이 화면 안에 남도록 위치를 뒤집거나 이동할지 여부입니다.
collisionBoundary: 타입PickerPositionOptions['collisionBoundary']기본값undefined
팝업을 화면 안에 유지할 때 사용할 경계입니다.
collisionPadding: 타입PickerPositionOptions['collisionPadding']기본값8
팝업과 충돌 경계 사이에 둘 간격입니다.
defaultHighlightedValue: 타입DateValue기본값undefined
컴포넌트가 관리하는 처음 강조 값입니다.
defaultOpen: 타입boolean기본값false
컴포넌트가 관리하는 초기 열림 상태입니다.
defaultValue: 타입DateRange | null기본값null
컴포넌트가 값을 관리할 때 사용할 초깃값입니다.
defaultView: 타입PickerRootSlotProps['viewMode']기본값'month'
달력 또는 선택기의 초기 보기입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
hideWhenDetached: 타입boolean기본값false
기준 요소가 레이아웃에서 벗어나면 팝업을 숨길지 여부입니다.
highlightedValue: 타입DateValue기본값undefined
키보드 조작 대상으로 강조된 현재 값입니다.
label: 타입string기본값undefined
보조 기술이 읽는 컨트롤 이름입니다.
modelValue: 타입DateRange | null기본값undefined
부모가 상태를 관리할 때 사용할 현재 값입니다.
open: 타입boolean기본값undefined
연결된 팝업이나 펼침 영역이 열려 있는지 여부입니다.
policies: 타입DateRangePickerOptions['policies']기본값undefined
검증, 이동, 선택 동작을 조정하는 정책입니다.
position: 타입boolean기본값true
실행 요소를 기준으로 팝업 위치를 계산할지 여부입니다.
readonly: 타입boolean기본값false
값 확인만 허용하는 읽기 전용 상태 여부입니다.
referenceDate: 타입DateValue기본값undefined
달력의 선택값과 강조값을 초기화할 때 사용하는 민간 기준 날짜입니다.
required: 타입boolean기본값false
제출 전에 올바른 값이 반드시 있어야 하는지 여부입니다.
side: 타입PickerPositionOptions['side']기본값'bottom'
기준 요소를 중심으로 팝업을 우선 배치할 방향입니다.
sideOffset: 타입number기본값8
팝업과 기준 요소 사이 거리입니다.
strategy: 타입PickerPositionOptions['strategy']기본값'absolute'
기준 요소에 연결된 콘텐츠의 CSS 위치 전략입니다.
tracking: 타입PickerPositionOptions['tracking']기본값undefined
기준 요소에 연결된 콘텐츠가 열린 동안 위치를 갱신할 방식입니다.

`DateRangePickerPartProps`

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

`DateRangePickerPortalProps`

defer: 타입boolean기본값false
Teleport 대상을 현재 mount 또는 update tick이 끝날 때 찾을지 여부입니다.
disabled: 타입boolean기본값false
사용자 조작을 막을지 여부입니다.
to: 타입string | HTMLElement기본값'body'
포털 콘텐츠를 옮길 대상입니다.

슬롯

`DateRangePickerRootSlotProps`

dates: 타입readonly (readonly DateValue[])[]
현재 보기에 표시할 날짜입니다.
disabled: 타입boolean
사용자 조작을 막을지 여부입니다.
highlightedValue: 타입DateValue
조작 대상으로 강조된 현재 값입니다.
months: 타입readonly (readonly CalendarMonthValue[])[]
현재 보기에 표시할 달입니다.
open: 타입boolean
연결된 팝업이나 펼침 영역이 열려 있는지 여부입니다.
readonly: 타입boolean
값 확인만 허용하는 읽기 전용 상태 여부입니다.
value: 타입Value
이 계약이 노출하는 현재 값입니다.
view: 타입{ readonly year: number; readonly month: number }
현재 달력 기준점입니다.
viewMode: 타입CalendarViewMode
현재 달력 보기 방식입니다.
years: 타입readonly (readonly PickerYearValue[])[]
현재 보기에 표시할 연도입니다.

`DateRangePickerCellSlotProps`

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

`DateRangePickerMonthCellSlotProps`

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

기타 타입

`DateRangePickerValueChangeHandler`

type DateRangePickerValueChangeHandler = NonNullable<InstanceType<typeof DateRangePickerRoot>['$props']['onUpdate:modelValue']>

`DateRangePickerOpenChangeHandler`

type DateRangePickerOpenChangeHandler = NonNullable<InstanceType<typeof DateRangePickerRoot>['$props']['onUpdate:open']>

`DateRangePickerHighlightedValueChangeHandler`

type DateRangePickerHighlightedValueChangeHandler = NonNullable<InstanceType<typeof DateRangePickerRoot>['$props']['onUpdate:highlightedValue']>

`DateRange`

이름	타입	필수
`start`	`DateValue`	필수
`end`	`DateValue`	필수

`DateValue`

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

파트

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

파트	선택자	역할	추가 속성
`start-input`	`[data-part="start-input"]`	시작 값을 편집합니다.	—
`end-input`	`[data-part="end-input"]`	종료 값을 편집합니다.	—
`anchor`	`[data-part="anchor"]`	떠 있는 콘텐츠의 배치 기준을 제공합니다.	—
`trigger`	`[data-part="trigger"]`	연결된 콘텐츠를 열고 닫거나 활성화합니다.	—
`content`	`[data-part="content"]`	현재 상태에 맞는 컴포넌트 콘텐츠를 담습니다.	—
`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 keys`	강조된 날짜를 하루 또는 일주일 단위로 이동합니다.
`Home` / `End`	한 주의 시작 또는 끝으로 이동합니다.
`Page Up` / `Page Down`	한 달 단위로 이동하고, Shift와 함께 누르면 일 년 단위로 이동합니다.
`Enter` / `Space`	강조된 날짜를 선택합니다.
`Escape`	현재 날짜를 유지한 채 달력을 닫습니다.

접근성

시작과 종료 입력이 달력 격자를 공유하되 각 양 끝의 이름을 독립적으로 유지합니다.

Date Range Picker ​

용법 ​

예약 ​

범위 제한 ​

외부 상태 관리 ​

Floating 위치 ​

API ​

Props ​

DateRangePickerRootProps ​

DateRangePickerPartProps ​

DateRangePickerPortalProps ​

슬롯 ​

DateRangePickerRootSlotProps ​

DateRangePickerCellSlotProps ​

DateRangePickerMonthCellSlotProps ​

기타 타입 ​

DateRangePickerValueChangeHandler ​

DateRangePickerOpenChangeHandler ​

DateRangePickerHighlightedValueChangeHandler ​

DateRange ​

DateValue ​

파트 ​

키보드 동작 ​

접근성 ​