DatePicker

달력에서 날짜 하나를 고르는 컴포넌트예요. 마감일, 시작일, 일정 날짜에 써요. 넓은 화면에서는 Popover, 좁은 화면에서는 BottomSheet로 열려요. 생년월일처럼 달력에서 찾기 먼 날짜는 Input으로 입력받아요.

사용 예시

마감일

Field로 감싸면 FieldLabel이 트리거의 이름이 돼요. 달을 넘겨도 값은 그대로이고, 날짜를 누르면 값을 바꾸고 닫혀요.

마감일

마감일이 지나면 목록에 표시돼요.

tsx

<Field className="w-64">  <FieldLabel>마감일</FieldLabel>  <DatePicker value={due} onValueChange={setDue} />  <FieldHelp>마감일이 지나면 목록에 표시돼요.</FieldHelp></Field>

고르지 않은 상태

값이 null이면 placeholder가 보여요. 달력은 오늘이 있는 달로 열려요.

시작일

tsx

<Field className="w-64">  <FieldLabel>시작일</FieldLabel>  <DatePicker value={start} onValueChange={setStart} placeholder="시작일을 고르세요" /></Field>

고를 수 있는 범위

시작일보다 앞선 마감일처럼 고르면 안 되는 날짜를 min과 max로 막아요.

마감일

11월 10일부터 11월 20일까지 고를 수 있어요.

tsx

<Field className="w-64">  <FieldLabel>마감일</FieldLabel>  <DatePicker value={due} onValueChange={setDue} min="2026-11-10" max="2026-11-20" />  <FieldHelp>11월 10일부터 11월 20일까지 고를 수 있어요.</FieldHelp></Field>

표시 형식

연도가 뻔한 화면에서는 format으로 짧게 보여요. 값은 그대로 YYYY-MM-DD예요.

마감일

tsx

<Field className="w-64">  <FieldLabel>마감일</FieldLabel>  <DatePicker value={due} onValueChange={setDue} format={monthDayWeekday} /></Field>

오류

Field에 invalid를 주면 트리거에 빨간 링이 보이고 스크린 리더가 오류 상태를 읽어요.

마감일

마감일은 시작일 뒤여야 해요. 11월 2일 이후로 고르세요.

tsx

<Field invalid className="w-64">  <FieldLabel>마감일</FieldLabel>  <DatePicker defaultValue="2026-11-01" />  <FieldError match>마감일은 시작일 뒤여야 해요. 11월 2일 이후로 고르세요.</FieldError></Field>

권장

앱 안의 날짜는 DatePicker로 받아요. 어느 브라우저에서도 같은 모양이고, 달을 넘겨도 닫히지 않아요.

지양

브라우저 날짜 입력은 브라우저마다 모양과 동작이 달라요.

유형

surface

폼에서는 bare나 well, 표 셀과 헤더에서 값을 바로 고칠 때는 ghost를 써요.

tsx

<DatePicker surface="bare" defaultValue="2026-11-14" aria-label="bare" /><DatePicker surface="well" defaultValue="2026-11-14" aria-label="well" /><DatePicker surface="ghost" defaultValue="2026-11-14" aria-label="ghost" />

size

함께 놓인 Input과 같은 크기를 써요.

tsx

<DatePicker size="sm" defaultValue="2026-11-14" aria-label="sm" /><DatePicker size="md" defaultValue="2026-11-14" aria-label="md" /><DatePicker size="lg" defaultValue="2026-11-14" aria-label="lg" />

컨트롤

surface

size

disabled

값"2026-11-14"

tsx

<DatePicker value={date} onValueChange={setDate} aria-label="날짜" />

명세

이름
이름	값	기본
value	string \| null	-
고른 날짜예요. YYYY-MM-DD 글자 값이고 고르지 않은 상태는 null이에요.
defaultValue	string \| null	null
처음에 고를 날짜를 정해요.
onValueChange	(value: string) => void	-
날짜를 고르면 호출돼요. 이미 고른 날짜를 다시 누르면 호출되지 않아요.
min	string	-
고를 수 있는 첫 날짜예요.
max	string	-
고를 수 있는 마지막 날짜예요.
today	string	브라우저의 오늘
오늘로 표시할 날짜예요. 서버 시간대를 따라야 할 때 넘겨요.
format	(day: string) => ReactNode	YYYY년 M월 D일
트리거에 보일 글자를 정해요.
placeholder	string	날짜를 고르세요
고르지 않은 상태에 보여요.
title	string	날짜 고르기
BottomSheet의 제목이고 Popover의 이름이에요.
surface	bare, well, ghost	bare
Input의 surface와 같아요.
size	sm, md, lg	md
높이가 32, 36, 40px이에요.
disabled	boolean	false
aria-label	string	-
Field 밖에서 쓸 때 이름을 정해요.
className	string	-
트리거에 적용돼요. 폭은 wrapper로 정해요.