Date Picker

Date Picker

캘린더에서 날짜 또는 날짜 범위를 선택할 때 사용하는 컴포넌트예요. 다양한 뷰와 선택 모드를 지원하는 캘린더 UI를 제공해요.

출처: 문서

본문

사용법 (Usage)

import { DatePicker } from "@chakra-ui/react"

<DatePicker.Root>
  <DatePicker.Label />
  <DatePicker.Control>
    <DatePicker.Input />
    <DatePicker.IndicatorGroup>
      <DatePicker.Trigger>
        <LuCalendar />
      </DatePicker.Trigger>
    </DatePicker.IndicatorGroup>
  </DatePicker.Control>
  <Portal>
    <DatePicker.Positioner>
      <DatePicker.Content>
        <DatePicker.View view="day">
          <DatePicker.Header />
          <DatePicker.DayTable />
        </DatePicker.View>
        <DatePicker.View view="month">
          <DatePicker.Header />
          <DatePicker.MonthTable />
        </DatePicker.View>
        <DatePicker.View view="year">
          <DatePicker.Header />
          <DatePicker.YearTable />
        </DatePicker.View>
      </DatePicker.Content>
    </DatePicker.Positioner>
  </Portal>
</DatePicker.Root>

날짜 값 (Date Value)

날짜 값은 @internationalized/date의 객체를 사용해 제공되며, 시간대 안전(timezone-safe)하고 로케일 인식(locale-aware) 날짜 처리를 담당해요.

이것은 Temporal API가 브라우저에서 널리 지원될 때 대체될 예정이에요.

예시 (Examples)

크기 (Sizes)

size prop을 사용하면 데이트 피커의 크기를 바꿀 수 있어요.

변형 (Variants)

variant prop을 사용하면 데이트 피커의 시각적 스타일을 바꿀 수 있어요.

비활성화 (Disabled)

disabled prop을 사용하면 데이트 피커와의 사용자 상호작용을 막을 수 있어요.

읽기 전용 (Read Only)

readOnly prop을 사용하면 값을 유지하면서 수정을 막을 수 있어요.

기본 뷰 (Default View)

defaultView prop을 사용하면 초기 캘린더 뷰를 "day", "month", "year"로 설정할 수 있어요.

기본값 (Default Value)

defaultValue prop을 사용하면 초기에 선택된 날짜를 설정할 수 있어요.

제어 (Controlled)

value와 onValueChange prop을 사용하면 선택된 날짜를 제어할 수 있어요.

스토어 (Store)

데이트 피커를 제어하는 또 다른 방법은 RootProvider 컴포넌트와 useDatePicker 스토어 훅을 사용하는 거예요.

범위 선택 (Range Selection)

selectionMode prop을 "range"로 설정하면 시작/종료 날짜를 선택할 수 있게 해 줘요.

다중 선택 (Multiple Selection)

selectionMode prop을 "multiple"로 설정하면 여러 날짜를 선택할 수 있게 해 줘요.

월 피커 (Month Picker)

defaultView와 minView prop을 "month"로 설정하면 월 선택만 가능하도록 피커를 제한할 수 있어요.

월 범위 (Month Range)

selectionMode prop을 "range"로, minView를 "month"로 설정하면 월 범위를 선택할 수 있어요.

연도 피커 (Year Picker)

defaultView와 minView prop을 "year"로 설정하면 연도 선택만 가능하도록 피커를 제한할 수 있어요.

연도 범위 (Year Range)

selectionMode prop을 "range"로, minView를 "year"로 설정하면 연도 범위를 선택할 수 있어요.

최소/최대 (Min/Max)

min과 max prop을 사용하면 날짜 선택을 특정 범위로 제한할 수 있어요.

선택 불가 날짜 (Unavailable Dates)

isDateUnavailable prop을 사용하면 특정 날짜(예: 주말, 공휴일)를 비활성화할 수 있어요.

형식화와 파싱 (Formatting & Parsing)

format과 parse prop을 사용하면 날짜가 표시되고 해석되는 방식을 제어할 수 있어요.

지역화 (Localization)

locale prop을 사용하면 캘린더를 다른 언어와 지역 형식으로 표시할 수 있어요.

페르시아 (자할리) 캘린더

locale="fa-IR"와 함께 createCalendar prop을 사용하면 페르시아(자할리) 캘린더를 렌더링할 수 있어요.

버튼 트리거 (Button Trigger)

기본 트리거를 스타일링된 커스텀 버튼으로 교체할 수 있어요.

외부 아이콘 (Outside Icon)

트리거 아이콘을 입력 필드 밖에 배치할 수 있어요.

입력 그룹 (Input Group)

시작/끝 요소가 있는 커스텀 입력 레이아웃을 위해 InputGroup과 통합할 수 있어요.

클리어 아이콘 (Clear Icon)

선택을 리셋하는 클리어 트리거를 추가할 수 있어요.

배치 (Placement)

positioning prop을 사용하면 캘린더 팝오버의 배치를 제어할 수 있어요.

헤더 레이아웃 (Header Layout)

RangeText와 내비게이션 버튼으로 헤더 레이아웃을 커스터마이즈하는 예시예요.

월/연도 선택 (Month and Year Select)

빠른 월/연도 내비게이션을 위해 DatePicker.MonthSelect와 DatePicker.YearSelect 컴포넌트를 렌더링할 수 있어요.

여러 달 (Multiple Months)

numOfMonths prop을 사용하면 여러 달을 나란히 표시할 수 있어요.

프리셋 (Presets)

DatePicker.PresetTrigger 컴포넌트를 렌더링해 빠른 날짜 선택 옵션을 제공할 수 있어요.

프리셋 사이드바 (Presets Sidebar)

프리셋 사이드바와 캘린더를 나란히 배치한 작업 관리 스타일 피커의 예시예요.

오늘 버튼 (Today Button)

오늘 날짜로 빠르게 이동하는 푸터 버튼을 추가하는 예시예요.

시간 포함 (With Time)

날짜 선택과 시간 입력을 결합한 데이트타임 피킹 예시예요.

폼 (Form)

네이티브 폼 검증과 통합하는 예시예요.

React Hook Form

Controller 패턴을 사용해 react-hook-form과 통합하는 예시예요.

고정 주 (Fixed Weeks)

fixedWeeks prop을 사용하면 캘린더에 항상 6주를 표시해, 월과 관계없이 일관된 높이를 보장할 수 있어요.

클릭 시 열기 (Open on Click)

openOnClick prop을 사용하면 입력 필드를 클릭할 때 캘린더가 열리게 해, 별도의 트리거 버튼이 필요 없게 할 수 있어요.

필드 (Field)

DatePicker는 아직 Field 컴포넌트와 네이티브로 통합되지 않았어요. Field.Context를 사용해 필드 상태를 수동으로 연결해 주세요. 네이티브 지원은 향후 버전에서 추가될 예정이에요.

Props

Root

DatePicker 컴포넌트의 Root 부분에 전달할 수 있는 prop을 확인해 주세요.

Input

DatePicker 컴포넌트의 Input 부분에 전달할 수 있는 prop을 확인해 주세요.

View

DatePicker 컴포넌트의 View 부분에 전달할 수 있는 prop을 확인해 주세요.

TableCell

DatePicker 컴포넌트의 TableCell 부분에 전달할 수 있는 prop을 확인해 주세요.

PresetTrigger

DatePicker 컴포넌트의 PresetTrigger 부분에 전달할 수 있는 prop을 확인해 주세요.

Explorer

DatePicker 컴포넌트의 각 부분을 인터랙티브하게 탐색해 보세요. 사이드바에서 부분을 클릭하면 미리보기에서 강조 표시돼요.

더 알아보기 (Learn more)

Chakra UI의 Date Picker 컴포넌트에 대해 더 자세히 알아보려면 공식 문서를 확인해 보세요.