Date Picker

구조는 당근 SEED Date Picker(Apache-2.0)를 따른다 — 머리(연 · 월 제목 · 이전 · 다음) · 요일 줄 · 날짜 칸(원 · 숫자) · 기간 띠, 하루 · 기간 · 여러 날, 한 달 · 두 달 · 이어지는 달. 값은 groo 토큰이고, SEED 와 다른 자리는 맨 아래 "SEED 와 다른 점" 에 적었다(2026-10-03 사용자 결정). 옛 Calendar 스펙을 대신한다.

수치 원본은 date-picker.yaml이다. 수치 표 자리([표: …])와 그림 자리([그림: …])는 사이트가 그 파일로 그린다 — GitHub 에서는 그 파일 · 그림 코드로 가는 링크로 보인다.

직접 골라 보기제목 링크 복사

고르기(하루 · 기간 · 여러 날) · 여는 자리(시트 · 팝오버) · 막힌 날 · 빠른 기간을 고르면 스펙대로 그린 달력과 그 코드가 바뀐다. 실제로 날짜를 누르고 "완료" 로 칸에 넣을 수 있다.

import { DatePicker } from "@/components/ui/date-picker"

// 1280 미만 — BottomSheetContent 의 본문 — useInputButtonSurface(input-button.md)
<DatePicker
  selection="single"
  autoFocus
  value={draft}
  onValueChange={setDraft}
/>
<Button disabled={!draft} onClick={apply}>완료</Button>

Anatomy제목 링크 복사

부위

Properties제목 링크 복사

머리 · 요일 · 날짜 칸제목 링크 복사

머리 · 요일 줄 · 날짜 줄은 모두 48 이다. 날짜 칸은 달력 폭을 7로 나눈 폭에 높이 48 이고 칸 전체가 누르는 자리다 — 원 42 는 칸 위 3 에 놓여 원 · 띠끼리 6 떨어진다. 숫자는 16 / 22 · 500, 요일은 14 / 19 · 500 fg-neutral-subtle. 제목은 16 / 22 · 700 에 셰브론 20, 이전 · 다음은 Button ghost 40(아이콘 18)을 오른쪽 끝에 붙인다.

달력은 늘 6주다 — 앞뒤 달 날짜를 흐리게 채워 달을 넘겨도 머리 · 바닥이 움직이지 않는다. 앞뒤 달 날짜는 보이기만 하고 누르지 못한다(보조 기술에도 숨긴다) — 다른 달은 이전 · 다음 · 화살표 키로 넘긴다.

공통

팝오버의 달력은 336(칸 48 × 7), 시트는 시트 폭에서 좌우 24 를 뺀 폭이다(360 화면 312). 칸이 44 보다 좁으면(320 화면) 원을 칸 폭 − 2 로 줄인다.

글자 크기 설정은 글자(숫자 · 요일 · 제목)만 따른다. 칸 · 머리 · 요일 줄은 최소 48 이고 글이 더 크면 그만큼만 늘어나며, 원 42 · 이전 · 다음 40 은 px 그대로다(SEED — dateCell minHeight). 날짜 칸은 숫자 줄 높이에 위아래 3 · 3 을 더한 높이와 48 중 큰 쪽이다 — 날짜 버튼과 앞뒤 달 숫자가 위아래 3 을 가지므로 숫자 줄이 원 42 를 넘는 큰 글자에서 칸이 줄 높이 + 6 이 된다(100% 48 · 200% 44 + 6 = 50). 웹 · 앱이 같은 모양이다. 글자 200% 에서 달력은 396(머리 48 · 요일 48 · 칸 50 × 6) — 시트 안에 6주가 다 들고 제목이 한 줄로 보인다. 이어지는 달의 달 높이(이름 줄 + 칸 × 주 + 16)도 같은 칸 높이로 셈하고, 배율이 바뀌면 다시 재서 보던 달로 맞춘다. 연 · 월 휠 자리도 요일 줄 + 6 × 칸이라 함께 늘어난다(100% 336 · 200% 348) — 제목을 눌러 휠을 열고 닫아도 달력 높이가 그대로다(2026-10-22 I-04 검수 — 레시피가 칸에 위아래 3 을 두지 않아 200% 에서 384 였다). 대가 — 두 자리 숫자(32px)가 원 42 를 채워 이웃 숫자와 약 6 떨어진다(SEED 와 같은 값)(2026-10-21 사용자 결정 — 03-C 1B, 비교 페이지 https://claude.ai/artifact/3nWUZCYpPh2Cg3uXc3DKtp).

Selection제목 링크 복사

고르기

Visible Range제목 링크 복사

하루 · 여러 날은 한 달(month)이다. 기간은 여는 자리에 따라 바뀐다 — 1280 미만 시트는 달이 위아래로 이어지고(continuous, 스크롤로 달을 넘긴다 · 요일 줄이 위에 붙는다 · 아래 안개 96), 1280 이상 팝오버는 두 달을 나란히(twoMonths, 사이 24 — 팝오버 폭 744 는 Popover 최대 480 의 예외다).

보이는 범위

State제목 링크 복사

상태

상태가 겹칠 때제목 링크 복사

• 고름이 이긴다 — 오늘을 고르면 짙은 원이다. 오늘의 굵기(700)는 남는다.
• 기간 안의 오늘은 원 없이 띠 위에 굵은 숫자다.
• 막힌 날이 기간 안에 있으면 띠는 그대로 깔리고 숫자만 흐린 취소선이다. 미완성 기간(시작만 고름)의 시작일이 막힌 날이어도 시작 원 위에는 취소선을 긋지 않는다.
• 오늘인데 막힌 날은 원 없이 굵은 숫자 + 취소선, 고른 날인데 막힌 날은 고른 모양 + 취소선이다.
• 막힌 날 · 읽기 전용 · 앞뒤 달에는 호버 원이 없다.

모션

Guidelines제목 링크 복사

날짜는 고르게 한다제목 링크 복사

날짜를 치는 칸은 두지 않는다 — 날짜 칸은 Input Button 이고, 누르면 이 달력이 열린다. 고르는 동안 칸 값은 그대로이고 "완료" 를 누를 때 들어간다. 바깥 · 끌어내리기 · Esc 로 닫으면 고르던 것은 버린다. 열 때는 칸의 값에서 시작한다 — 비었으면 오늘이 든 달을 열고 오늘을 짚기만 한다(고른 것처럼 칠하지 않는다). "완료" 는 하루를 고르기 전, 기간의 끝을 고르기 전에는 막힌다.

어디에 놓나 — 시트 · 팝오버 · 펼친 달력제목 링크 복사

SEED 는 "날짜 선택이 화면에서 차지하는 비중과 플랫폼에 따라" 놓는 자리(Layout)를 고른다 — 폼의 칸이면 시트 · 팝오버, 날짜 고르기가 그 화면의 핵심 작업이거나 여러 단계 흐름의 한 단계면 화면에 바로 펼친 달력(Inline)이다. 시트 · 팝오버의 1280 은 사용자 결정이고, 펼친 달력은 SEED 와 같게 두되 지금 쓰는 곳은 없다(multiple · 읽기 전용과 같은 결 — 2026-10-22 사용자 결정 1C · 2B · 3B, https://claude.ai/artifact/Mag1tEv51MdQHdy1o8hY3L).

예외 · 주의

• 펼친 달력은 확정 버튼이 없다 — 화면의 "다음" 이 확정이고, 고른 날은 달력 아래 한 줄로 되짚는다("2027년 3월 12일 (금)까지 · 141일 남았어요").
• 펼친 달력도 달력 모양 · 키 · 6주 · 막힌 날은 시트 · 팝오버와 같다 — 바뀌는 것은 놓이는 자리와 확정뿐이다.
• 폼 안에 달력을 펼쳐 두지 않는다 — 폼의 여러 칸 가운데 하나면 칸이다. 펼치면 폼이 두 배로 길어지고 다른 칸이 밀린다.
• 먼 날짜가 잦은 칸(입사일 · 만기일)은 열 때 그 자리의 흔한 해로 시작해도 된다 — 연의 범위는 자리마다 정한다(아래 "연 · 월 옮기기").

기간 — 칸 하나, 달력 하나제목 링크 복사

기간은 시작 · 종료 두 칸으로 나누지 않는다 — 칸 하나("9월 28일~10월 6일")를 누르면 한 달력에서 시작과 끝을 고른다.

• 첫 탭이 시작, 시작 뒤의 날을 누르면 끝 — 사이가 띠로 이어진다.
• 시작보다 앞을 누르면 그날이 새 시작이다(둘을 바꾸지 않는다).
• 같은 날을 두 번 누르면 하루짜리 기간이다. 하루짜리를 막아야 하는 자리는 "2일 이상" 같은 제약을 둔다.
• 기간이 완성된 뒤 다시 누르면 새로 시작한다.
• 끝을 고르는 동안 미리 칠해 보이지 않는다. 시작을 고르는 순간 제약에 걸린 날이 한꺼번에 막힌 날로 바뀔 수 있다 — 그런 제약(최소 · 최대 기간)은 달력 위 Callout 으로 미리 알린다.

빠른 기간제목 링크 복사

기간 달력 위에 칩 한 줄을 둔다. 누르면 그 기간을 달력에 칠하고(그 달로 옮긴다) "완료" 로 넣는다 — 하나 고르기라 고른 칩은 짙게 채워지고, 달력에서 다른 날을 누르면 칩 고름이 풀린다. 이름과 범위는 아래 한 벌이고, 화면은 이 안에서 고른다(이름이 같으면 어디서나 같은 기간이다).

달력 단위다 — 끝은 그 단위의 마지막 날이고, 앞으로의 날(예정 거래 · 일정)도 들어간다. 주는 달력처럼 일요일부터다. 칩을 누르면 그 기간의 시작이 든 달로 옮긴다. 기간의 시작 · 끝이 고를 수 있는 범위 밖이거나 막힌 날이면 그 칩을 막는다 — 잘라서 넣지 않는다(이름이 같으면 같은 기간이어야 한다). 사이에 막힌 날이 있는 것은 괜찮다(손으로 고를 때와 같다).

연 · 월 옮기기제목 링크 복사

하루를 고르면 달력이 기본이다 — 요일 · 오늘과의 거리가 보인다. 몇 해 앞뒤의 먼 날도 이 길로 고른다 — 연 · 월 · 일 세 휠은 피한다(Wheel Picker 의 "휠을 쓰는 자리"). 제목을 누르면 요일 줄과 날짜 자리(요일 줄 + 6 × 칸 — 100% 336, 글이 크면 달력을 따라 늘어난다)에 연 | 월 휠이 뜬다(Wheel Picker medium · 7칸). 셰브론이 위로 돌고 이전 · 다음은 막힌다. 제목을 다시 누르면 고른 달로 옮긴다. 연의 범위는 자리마다 정하고(기본 오늘 ± 100년), 월은 돌아간다.

고를 수 없는 날제목 링크 복사

자리마다 고를 수 있는 범위가 다르다(환불일은 거래일 ~ 오늘, 할 일 마감은 오늘부터). 그 밖의 날은 막힌 날로 그린다 — 흐린 숫자 + 취소선, 키보드 초점은 간다. 이미 확정돼 바꿀 수 없는 시작일(진행 중인 기간 늘리기)은 읽기 전용 — 채움을 남겨 흐리게 그린다. 달력 전체가 보기 전용이면 날짜마다가 아니라 달력 전체를 읽기 전용으로 둔다.

여러 날제목 링크 복사

multiple 은 누를 때마다 고르고 풀린다 — 고른 날은 따로 그린 원이고 띠로 잇지 않는다. 최대 개수가 있으면 달력 위에 남은 개수를 보이고, 다 고르면 고르지 않은 날이 막힌 날(취소선)이 된다 — 고른 날은 풀 수 있다. 칸에는 가장 이른 날 + 나머지 개수("10월 14일 (수) 외 2개" — Select 여럿 고르기와 같은 꼴). 지금 쓰는 곳은 없다.

글제목 링크 복사

칸에 들어가는 값은 International Design(v106)의 표기다 — 올해는 "10월 15일 (목)", 다른 해는 "2027년 1월 3일 (일)", 기간은 "10월 1일~10월 31일"(물결표를 앞뒤에 붙여 쓴다 — International Design, 올해가 아닌 날이 끼면 양쪽에 연도). 시트 제목은 고를 값의 종류("날짜 선택" · "기간 선택"), 칸이 비면 placeholder 도 같은 말이다.

코드제목 링크 복사

레시피 recipes/shadcn/components/ui/date-picker.tsx 를 Input Button 이 연 시트 · 팝오버 안에 둔다. 값은 쓰는 쪽이 가진다 — 달력은 고르던 값(draft)을 보이고, "완료" 가 칸에 넣는다. 여는 자리는 useInputButtonSurface()(1280 미만 "sheet" · 이상 "popover")가 정한다. 아래 미리보기는 스펙 값으로 그린 모습이다.

날짜 하나 — "완료" 로 넣는다제목 링크 복사

import { CalendarDays } from "lucide-react"
import { DatePicker, formatDateValue } from "@/components/ui/date-picker"
import { InputButton, useInputButtonSurface } from "@/components/ui/input-button"

const surface = useInputButtonSurface()
const [draft, setDraft] = React.useState(date)

<InputButton value={formatDateValue(date)} placeholder="날짜 선택" suffixIcon={<CalendarDays />} onClick={() => { setDraft(date); setOpen(true) }} />

// 열면 고른 날(없으면 오늘)로 초점을 옮긴다
<DatePicker selection="single" value={draft} onValueChange={setDraft} autoFocus />
<Button disabled={!draft} onClick={() => { setDate(draft); setOpen(false) }}>완료</Button>

기간 — 칩 줄 · 이어지는 달 · 두 달제목 링크 복사

// 이어지는 달은 시트 높이를 채운다(시트 h-[90dvh]), 두 달은 팝오버 폭 744 — PopoverContent className={DATE_PICKER_TWO_MONTHS_POPOVER}
<DatePicker
  selection="range"
  visibleRange={surface === "sheet" ? "continuous" : "twoMonths"}
  autoFocus
  presets={["thisWeek", "thisMonth", "lastMonth", "last3Months", "thisYear"]}
  value={draft}
  onValueChange={setDraft}
/>
<Button variant="neutralWeak" onClick={() => setDraft(undefined)}>초기화</Button>
<Button disabled={!draft?.end} onClick={apply}>완료</Button>

고를 수 있는 범위 — 환불일제목 링크 복사

<DatePicker selection="single" min={transactionDate} max={today} value={draft} onValueChange={setDraft} />

Behavior제목 링크 복사

키보드제목 링크 복사

WAI-ARIA Grid 다 — 날짜 하나만 Tab 순서에 들고 방향키로 옮긴다. 웹 · 앱이 같다 — 앱도 하드웨어 키보드 · 스위치 접근에서 아래 키를 받고, 열 때 초점은 고른 날(없으면 오늘)로 간다. 링은 키보드일 때만 그린다(2026-10-21 사용자 결정 — 03-C 4A).

보이는 달 밖으로 옮기면 달이 따라 넘어가고 "2026년 11월" 을 읽는다(두 달 보기는 "2026년 10월~2026년 11월").

Accessibility제목 링크 복사

Do / Don't제목 링크 복사

✅ Do제목 링크 복사

• 날짜 칸을 누르면 달력이 열리게 — 날짜를 치게 하지 않는다.
• 기간은 칸 하나에 "9월 28일~10월 6일", 달력 하나에서 시작 · 끝을 고른다.
• 최소 · 최대 기간 같은 제약은 고르기 전에 Callout 으로 알린다.
• 빠른 기간은 정해진 이름 · 범위 한 벌에서 고른다.

❌ Don't제목 링크 복사

• 날짜 칸을 치는 칸으로 두기(지금 세 제품 66곳).
• 고른 날 · 오늘을 브랜드 색으로 채우기 — 고른 날은 짙은 회색, 오늘은 옅은 원 + 굵기.
• 막힌 날을 흐림(불투명도)으로만 그리기 — 흐린 색 + 취소선.
• 같은 "이번 달" 을 화면마다 다른 기간으로 쓰기.
• 날짜를 누르는 순간 칸에 넣고 닫기 — "완료" 로 넣는다.

Specification제목 링크 복사