DatePicker

캘린더 팝업으로 날짜를 선택하는 기본 컴포넌트

개요

Foundation DatePicker는 Button + Popover + Calendar을 조합한 날짜 선택 컴포넌트입니다. 단일 날짜 선택을 위한 기본 빌딩 블록으로, iCignal 레이어에서 FormItem 통합, 키보드 입력, 범위 선택 등 확장 기능을 제공합니다.

주요 특징

• ✅ 캘린더 팝업: Popover 기반 날짜 선택
• ✅ 범위 선택: mode="range"로 기간 선택 (종료일 optional)
• ✅ 월/연도 선택: mode="month", mode="year"로 월/연도 선택
• ✅ 캘린더 아이콘: 트리거 버튼에 아이콘 표시
• ✅ 월/연도 드롭다운: captionLayout=“dropdown” 기본 적용
• ✅ 날짜 포맷: DatePicker(yyyy-MM-dd), MonthPicker(YYYY.MM), YearPicker(YYYY)
• ✅ 접근성: Button 기반 키보드 네비게이션
• ✅ 디자인 토큰: 테마 커스터마이징 지원

사용 예시

기본 날짜 선택

버튼을 클릭하면 캘린더 팝업이 열리고, 날짜를 선택하면 입력 필드에 반영됩니다.

const [date, setDate] = useState<Date | undefined>()
 
<DatePicker value={date} onChange={setDate} width={200} />

기본값 설정

value에 초기 Date 객체를 전달하여 기본 날짜를 설정합니다.

<DatePicker value={new Date()} onChange={setDate} width={200} />

비활성 상태

disabled를 설정하면 버튼이 비활성화되어 캘린더를 열 수 없습니다.

<DatePicker disabled width={200} />

기간 선택 (Range)

mode="range"를 설정하면 시작일~종료일 기간 선택이 가능합니다. 종료일은 optional으로, 시작일만 선택한 상태에서 팝업 바깥을 클릭하면 시작일만 선택된 상태로 확정됩니다.

const [range, setRange] = useState<DateRange | undefined>()
 
<DatePicker
  mode="range"
  value={range}
  onChange={setRange}
  width={300}
/>

Calendar 직접 사용 (Range)

Calendar 컴포넌트를 직접 사용하여 기간(range) 선택도 가능합니다.

const [range, setRange] = useState<DateRange | undefined>()
 
<Calendar
  mode="range"
  selected={range}
  onSelect={setRange}
  numberOfMonths={2}
/>

Calendar 월/연도 드롭다운

captionLayout="dropdown"으로 월과 연도를 드롭다운으로 빠르게 전환할 수 있습니다. DatePicker에는 기본 적용되어 있습니다.

<Calendar mode="single" captionLayout="dropdown" />

월 선택 (Month)

mode="month"를 설정하면 월 단위로 날짜를 선택합니다. YYYY.MM 포맷으로 표시되며 키보드 직접 입력도 지원합니다.

const [month, setMonth] = useState<Date | undefined>()
 
<DatePicker mode="month" value={month} onChange={setMonth} />
<DatePicker mode="month" defaultValue={new Date()} />
<DatePicker mode="month" disabled />
<DatePicker mode="month" readOnly defaultValue={new Date()} />

월 선택 범위 제한

minDate/maxDate로 선택 가능한 월 범위를 제한합니다.

<DatePicker
  mode="month"
  minDate={new Date(2024, 0)}
  maxDate={new Date(2025, 11)}
/>

월 범위 선택 (Month Range)

mode="month-range"를 설정하면 시작월~종료월 범위를 선택합니다. 첫 클릭으로 시작월, 두 번째 클릭으로 종료월을 선택합니다.

const [range, setRange] = useState<DateRange | undefined>()
 
<DatePicker
  mode="month-range"
  value={range}
  onChange={setRange}
  width={250}
/>

연도 선택 (Year)

mode="year"를 설정하면 연도 단위로 날짜를 선택합니다. YYYY 포맷으로 표시되며 10년 단위로 네비게이션합니다.

const [year, setYear] = useState<Date | undefined>()
 
<DatePicker mode="year" value={year} onChange={setYear} />
<DatePicker mode="year" defaultValue={new Date()} />
<DatePicker mode="year" disabled />
<DatePicker mode="year" readOnly defaultValue={new Date()} />

연도 선택 범위 제한

minDate/maxDate로 선택 가능한 연도 범위를 제한합니다.

<DatePicker
  mode="year"
  minDate={new Date(2020, 0)}
  maxDate={new Date(2030, 0)}
/>

연도 범위 선택 (Year Range)

mode="year-range"를 설정하면 시작년도~종료년도 범위를 선택합니다.

const [range, setRange] = useState<DateRange | undefined>()
 
<DatePicker
  mode="year-range"
  value={range}
  onChange={setRange}
  width={200}
/>

포맷 비교

각 Picker 유형별 포맷이 다릅니다.

{/* single: yyyy-MM-dd */}
<DatePicker value={new Date()} width={200} />
 
{/* month: YYYY.MM */}
<DatePicker mode="month" defaultValue={new Date()} />
 
{/* year: YYYY */}
<DatePicker mode="year" defaultValue={new Date()} />

API Reference

DatePicker Props (mode=“single”, 기본값)

DatePicker Props (mode=“range”)

종료일 Optional: mode="range" 시 시작일만 선택한 상태에서 팝업을 닫으면 { from: Date, to: undefined } 값이 유지됩니다.

DatePicker Props (mode=“month”)

DatePicker Props (mode=“year”)

DatePicker Props (mode=“month-range”)

DatePicker Props (mode=“year-range”)

기본 사용법

import { DatePicker, Calendar } from "@vortex/ui-foundation"
import type { DateRange } from "react-day-picker"
 
// 단일 날짜 선택 (기본값)
<DatePicker value={date} onChange={setDate} width={200} />
 
// 기간 선택 (종료일 optional)
<DatePicker mode="range" value={range} onChange={setRange} width={300} />
 
// 월 선택 (YYYY.MM)
<DatePicker mode="month" value={month} onChange={setMonth} />
 
// 연도 선택 (YYYY)
<DatePicker mode="year" value={year} onChange={setYear} />
 
// 월 범위 선택
<DatePicker mode="month-range" value={monthRange} onChange={setMonthRange} width={250} />
 
// 연도 범위 선택
<DatePicker mode="year-range" value={yearRange} onChange={setYearRange} width={200} />
 
// Calendar 직접 사용
<Calendar mode="single" captionLayout="dropdown" />
<Calendar mode="range" numberOfMonths={2} />

접근성

ARIA 속성

• Button 기반으로 role="button" 자동 적용
• Popover에 포커스 트랩 지원

키보드 네비게이션

• Enter/Space: 캘린더 팝업 열기/닫기
• Arrow Keys: 캘린더 내 날짜 이동
• Tab: 포커스 이동

권장 사항

• ✅ 폼 필드에서 사용 시 iCignal DatePicker 권장 (label, error, required 지원)
• ✅ 키보드 직접 입력이 필요하면 iCignal DatePicker 사용
• ❌ Foundation DatePicker를 label 없이 단독 사용 지양

관련 컴포넌트

• Calendar: 캘린더 컴포넌트
• Button: 버튼 컴포넌트
• DatePicker (iCignal): FormItem 통합 DatePicker