Date / time picker

미리보기

로컬 미리보기입니다. 실제 계정, 환경, 실행 데이터에는 영향을 주지 않습니다.

사용법

로케일 형식으로 날짜, 날짜 범위, 또는 시간을 입력하거나 캘린더에서 선택하세요. React Aria의 분할 입력, 캘린더 그리드, 범위 선택을 공유 폼 표면에서 구성합니다. DateLocaleProvider가 로케일 형식을 설정합니다. 예시는 한국어, 영어, RTL을 다룹니다. 최소/최대, 사용 불가 날짜, 필수 값, 폼 제출, 리셋이 검증됩니다.

• 날짜 타입을 서로 바꿔 쓰지 마세요. 캘린더 날짜에는 CalendarDate, 로컬 날짜-시간에는 CalendarDateTime, 인스턴트에는 ZonedDateTime, 벽시계 시간에는 Time을 사용하세요.
• 날짜 전용 값을 UTC 자정으로 변환하지 마세요. CalendarDate로 유지하세요.
• IANA 시간대와 명시적 DST 정책 없이 실제 실행 시간을 저장하지 마세요.
• 모호하거나 존재하지 않는 로컬 시간에 대해 사용자 대신 이전/이후를 선택하지 마세요. 기본적으로 예시는 이러한 시간을 거부합니다.
• 이 라이브러리를 Temporal이나 서버 측 일정·권한 검증의 대체재로 취급하지 마세요.
• 날짜 객체를 변경하지 마세요. 불변으로 유지하고 같은 타입을 쓰세요.
• 폼 리셋이 제어된 값을 복원하리라 기대하지 마세요. onReset에서 직접 리셋하세요.

크기: SizeProvider size="small" 포털까지 포함해 구성 전체의 크기를 바꿉니다. 기본 크기는 Default입니다. 크기 안내 및 비교

구성

DateLocaleProvider → DatePicker / DateRangePicker / TimeField → Label + Group + DateInput segments + calendar trigger → Popover + Dialog + Calendar/RangeCalendar → month navigation + weekday headers + grid cells; description + FieldError

키보드와 접근성

• Tab, Shift+Tab, 왼쪽·오른쪽 화살표 키가 세그먼트 사이를 이동합니다.
• 숫자를 입력해 세그먼트를 채우세요. 위·아래 화살표는 값을 늘리고 줄이며, Home, End, Backspace, Delete는 편집합니다.
• 캘린더에서 화살표 키는 일 단위로, Page Up과 Page Down은 월 단위로 이동합니다. Shift+Page Up과 Shift+Page Down은 연 단위로 이동합니다.
• 캘린더 버튼에서 Enter 또는 Space를 누르면 캘린더가 열립니다. 캘린더에서 Enter 또는 Space는 날짜, 또는 범위의 시작과 끝을 선택합니다.
• Escape는 캘린더를 닫고 포커스를 트리거로 돌려보냅니다.
• 비활성 값은 편집할 수 없습니다. 읽기 전용 값은 탐색하고 읽을 수 있지만 변경할 수는 없습니다.
• 팝업은 충돌을 피하고 터치 선택이 동작합니다.
• 각 날짜·시간 세그먼트는 spinbutton입니다.

각 컨트롤에 목적을 설명하는 이름을 지정하세요. 오류 메시지를 해당 컨트롤에 연결하고, 상태를 색만으로 알리지 마세요. 자동 검사는 수동 키보드 및 보조 기술 테스트를 대신하지 않습니다.

예시 코드

공유 컴포넌트는 디자인 토큰에서 스타일을 가져옵니다. 각 예시는 자체 구성과 접근성 속성을 설정합니다. 호출하는 화면이 콜백, ref, 제품 데이터를 정의합니다.

// Needs React Aria Components: npm install react-aria-components
import {
  DatePicker,
  DateRangePicker,
  TimeField,
  DateLocaleProvider,
} from '@surflane/ui/date-picker'
import {
  parseDate,
  parseDateTime,
  Time,
  toZoned,
} from '@internationalized/date'

<DateLocaleProvider locale='en-US'>
  <DatePicker
    label='Run date'
    name='runDate'
    value={date}
    onValueChange={setDate}
    minValue={parseDate('2026-10-01')}
    maxValue={parseDate('2026-12-31')}
    required
    description='October–December 2026'
  />
  <DateRangePicker
    label='Release window'
    startName='from'
    endName='to'
    value={range}
    onValueChange={setRange}
  />
  <TimeField
    label='Start time'
    name='time'
    defaultValue={new Time(9, 30)}
    hourCycle={24}
  />
</DateLocaleProvider>

// A local time is not an instant. Resolve explicitly and handle rejection.
try {
  const instant = toZoned(
    parseDateTime('2026-11-01T01:30'),
    'America/New_York',
    'reject',
  )
  console.log(instant.toAbsoluteString())
} catch {
  /* Ask for another time or an explicit earlier/later decision. */
}
// Controlled form reset: explicitly restore date/range state in onReset.

주요 API

표는 공통 래퍼의 주요 props를 나열합니다. 전체 타입은 패키지 타입 선언을 참조하세요.

관련 토큰