Datepicker

달력에서 날짜를 고른다. 내부는 react-day-picker 이고 값은 Date 객체로 주고받는다. 기간은 DateRangePicker, 여러 날짜는 DateMultiplePicker 다.

import { Datepicker, DateRangePicker, DateMultiplePicker } from "@nui-kit/react";
// 서브패스로 좁힐 때
import { Datepicker } from "@nui-kit/react/datepicker";
import "@nui-kit/react/styles/datepicker.css";   // 온디맨드일 때

import { Datepicker, DateRangePicker } from "@nui-kit/react";

<Datepicker selected={date} onSelectedChange={setDate} />
<DateRangePicker selected={range} onSelectedChange={setRange} />

직접 입력

Datepicker 와 DateRangePicker 는 입력창에 날짜를 직접 칠 수 있다. 달력이 있어도 입력 필드를 읽기 전용으로 만들지 않는다는 KRDS 기준(가이드 675쪽)을 따른다. 형식은 displayFormat (기본 yyyy.MM.dd), 기간은 2026.09.01 - 2026.09.05 처럼 앞뒤에 공백을 둔 대시로 잇는다.

치는 동안 달력은 그 날짜의 달로 따라 이동한다. 예전처럼 달력으로만 값을 받고 싶으면 isTextInputBlocked 를 준다. DateMultiplePicker 는 아직 읽기 전용이다 — 날짜 목록의 구분자 규칙이 따로 필요해 다음 단계로 미뤘다.

형식 안내는 infoMessage 로 적는다. 플레이스홀더만으로 형식을 알리지 않는다 — 값을 치기 시작하면 사라지기 때문이다.

기본 — 날짜 하나

입력창을 클릭하거나 캘린더 버튼을 누르면 달력이 열린다. 날짜를 고르면 자동으로 닫힌다.

<Datepicker selected={date} onSelectedChange={setDate} />

기간 선택

시작일과 종료일을 차례로 고른다. 둘 다 정해지기 전까지는 onSelectedChange 가 undefined 를 넘긴다 — 불완전한 기간이 폼에 들어가지 않는다.

<DateRangePicker selected={range} onSelectedChange={setRange} />

여러 날짜

날짜를 여러 개 고른다. 선택할 때마다 달력이 닫히면 불편하므로 열린 상태를 유지한다.

<DateMultiplePicker selected={dates} onSelectedChange={setDates} />

선택 가능 범위 제한

dayPickerProps 로 react-day-picker 에 그대로 전달한다. 오늘 이전 날짜를 막은 예다.

dayPickerProps={{ disabled: { before: new Date() } }}

상태

<Datepicker selected={date} errorMessage="날짜를 선택해주세요" />

잘리는 상자 안에서 — hasPortal

달력은 기본적으로 제자리에 뜬다. 조상에 overflow: hidden 이 있으면 잘려서 날짜를 고를 수 없다. 카드나 팝업 안에 넣을 때 hasPortal 을 켜면 달력이 body 로 나가 잘리지 않는다. Tooltip · Select 의 같은 이름 prop 과 한 규칙이다.

<Datepicker hasPortal />   // 잘리는 상자 안에서

Field 와 함께

react-hook-form 연동

@nui-kit/react/rhf 의 RHFDatepicker · RHFDateRangePicker · RHFDateMultiplePicker 는 control 만 넘기면 값과 에러를 스스로 소유한다. selected · name · onBlur 는 타입에서 제외되어 중복 소유가 생기지 않는다.

{
  "visitDate": null,
  "stay": null,
  "extraDates": null,
  "isValid": false,
  "errors": {}
}

스타일 커스터마이징

공개 CSS 변수로 달력 치수와 팝업 외형을 조정한다.

색은 컴포넌트별로 열지 않는다. 한 곳만 바꾸려면 className 을, 화면 전체를 바꾸려면 브랜드 프리셋을 쓴다.

접근성

• 입력창에 aria-haspopup="dialog" · aria-expanded · aria-controls 가 붙고, 팝업은 role="dialog" 로 연결된다
• 키보드로 연다 — Enter Space ↓, Esc 로 닫는다. 바깥을 클릭해도 닫힌다
• 달력 안에서는 react-day-picker 의 키보드 탐색을 그대로 쓴다 (방향키로 날짜 이동, Enter 로 선택)
• 토요일·일요일은 색으로만 구분하지 않는다 — 요일 헤더가 항상 함께 보인다
• readOnly 는 값을 보여주되 달력을 열지 않는다. disabled 는 포커스도 받지 않는다
• prefers-reduced-motion 에서 팝업 애니메이션이 꺼진다
• 날짜 셀과 이전/다음 버튼은 누르는 범위가 44px 이다. 날짜 버튼은 36px, 화살표는 32px 로 보이고 히트만 넓혔다. 셀 크기는 --nui-datepicker--day-size 로 바꿀 수 있다

API

세 컴포넌트는 selected 의 타입만 다르고 나머지는 같다. dayPickerProps 로 react-day-picker 의 설정(disabled, startMonth, locale 등)을 그대로 전달한다.

Datepicker

DatepickerProps 에서 자동 생성됨 (components/Datepicker/Datepicker.tsx). 표준 DOM 속성 297개는 그대로 전달되며 표에서 생략했다.

DateRangePicker

DateRangePickerProps 에서 자동 생성됨 (components/Datepicker/DateRangePicker.tsx). 표준 DOM 속성 297개는 그대로 전달되며 표에서 생략했다.

DateMultiplePicker

DateMultiplePickerProps 에서 자동 생성됨 (components/Datepicker/DateMultiplePicker.tsx). 표준 DOM 속성 297개는 그대로 전달되며 표에서 생략했다.