Cloaked Design SystemForms
DatePicker
A form trigger that presents bounded month, day, and year wheels and commits one ISO calendar date on confirmation.
Implementation previewCOMPLETE STORYBOOK REFERENCE
8 storiesEvery example. In one place.
Explore every named example, including states, compositions, and theme variants.
Playground selectedOpen canvas
Example source
packages/design-system/src/components/forms/DatePicker/DatePicker.stories.tsxExport PlaygroundImplementation preview Local Storybook build 0.2.0-preview.1. Source specification status does not approve this runtime.
Stories + source JSON ↗Local specification source status: preview. Implementation preview pending sign-off.
A form trigger that presents bounded month, day, and year wheels and commits one ISO calendar date on confirmation.
Design-owned component contract ↗Version 0.2.0-preview.1 · Implementation preview pending sign-off
Implementation API 1 entry point · source-derived preview
Read the actual callable API and preserve its composition constraints. Each union branch is a complete alternative; props marked forbidden cannot be supplied.
import { DatePicker } from '@cloakedinc/design-system';DatePickerDatePickerProps
packages/design-system/src/components/forms/DatePicker/DatePicker.tsx:57
| Prop | Type | Presence | Notes |
|---|---|---|---|
value | string | Required | Selected date as an ISO string, or `''` when unset. |
onChange | ((value: string) => void) | undefined | Optional | Called with the next ISO date when the user confirms a selection. |
min | string | undefined | Optional | Earliest selectable date (ISO). Defaults to `1900-01-01`. |
max | string | undefined | Optional | Latest selectable date (ISO). Defaults to today. |
placeholderValue | string | undefined | Optional | Date the wheels open to when `value` is empty (ISO). Defaults to `max`. |
placeholder | string | undefined | Optional | Trigger text shown when `value` is empty.Source default: DEFAULT_PLACEHOLDER |
icon | React.ReactNode | Optional | Trailing affordance in the trigger, usually a calendar `Icon`/`SFIcon`. |
sheetTitle | string | undefined | Optional | Title shown in the picker sheet. Falls back to `ariaLabel` or placeholder. |
confirmLabel | string | undefined | Optional | Text on the sheet's confirm button. Defaults to `Done`.Source default: 'Done' |
disabled | boolean | undefined | Optional | Blocks the trigger from opening the sheet. |
required | boolean | undefined | Optional | Announces the field as required to assistive tech. The trigger is a button, not a form control, so this cannot block a submit. |
ariaLabel | string | undefined | Optional | Accessible name when no visible label is associated with the field. |
haptic | HapticFeedback | undefined | Optional | Haptic feedback as the wheels cross a value. Defaults to `true` (`selection`).Source default: true |
className | string | undefined | Optional | |
style | React.CSSProperties | undefined | Optional | |
testId | string | undefined | Optional | Test id for the trigger; the sheet, each wheel, and the confirm button derive from it. |
id | string | undefined | Optional | DOM id the control renders, which the Field's label points at. |
invalid | boolean | undefined | Optional | Paints the invalid treatment and announces the control as invalid. A Field supplies this from its own `error`; set it directly only for a control with no Field around it. |
ariaDescribedBy | string | undefined | Optional | Ids of the helper or error copy describing the control, supplied by a parent Field. |
ariaLabelledBy | string | undefined | Optional | Id of the visible label naming the control, supplied by a parent Field. |
Only explicit destructured parameter initializers are extracted. Other runtime defaults remain in implementation source.
Overview
A date field whose trigger opens a mobile bottom sheet of month/day/year scroll wheels. Dates
cross the boundary as ISO "YYYY-MM-DD" strings.
When to use
Reach for DatePicker when the user picks a single calendar date on mobile — a date of birth,
an appointment day — and you want the native-feeling wheel sheet rather than a raw native
<input type="date">. Bound the range with min/max (default 1900-01-01 → today) and set
placeholderValue so empty wheels open somewhere plausible (e.g. a likely birth year).
- Wrap it in
Fieldfor a label and aria wiring. The Field'serrorturns this trigger red on its own;invalidis the escape hatch for a picker with noFieldaround it. - Need a plain, unstyled OS date box with no sheet (a desktop-style form)? A bare
Input/nativetype="date"is lighter — but on this mobile surface the wheel sheet is the house style.
In-app it powers the data-removal date-of-birth field (DobField).
Component specification
$schema
../../../specs/component-spec.schema.jsonParts
- Id
- root
- Label
- Root
- Description
- Carries the caller's class around the trigger.
- Id
- trigger
- Label
- Trigger
- Description
- Displays the placeholder or formatted date and opens the picker dialog.
- Id
- trigger-icon
- Label
- Trigger icon
- Description
- Optional trailing calendar affordance that does not replace the accessible name.
- Id
- sheet
- Label
- Picker sheet
- Description
- Modal surface containing the date wheels and confirm action.
- Id
- wheel-group
- Label
- Wheel group
- Description
- Groups month, day, and year listboxes under the field name.
- Id
- wheel-column
- Label
- Wheel column
- Description
- Scrollable, keyboard-operable listbox for one date part.
- Id
- selection-band
- Label
- Selection band
- Description
- Visually marks the centered row shared by all wheel columns.
- Id
- confirm-action
- Label
- Confirm action
- Description
- Commits the working date and closes the sheet.
Allowed Design Choices
- Variants
- Wheel sheet
- Label
- Wheel sheet
- Description
- The trigger opens three bounded scroll wheels in a modal sheet.
- Sizes
Variants
- Id
- wheel-sheet
- Label
- Wheel sheet
- Description
- Single approved date-picking flow with separate working and committed dates.
- Platforms
- ios
- android
- web
Sizes
None specifiedMeasurements
- Id
- trigger-min-height
- Label
- Trigger minimum height
- Kind
- exact
- Token
- --cds-size-48
- Value
- 48
- Unit
- px
- Applies To
- trigger
- Id
- trigger-horizontal-padding
- Label
- Trigger horizontal padding
- Kind
- exact
- Token
- --cds-space-16
- Value
- 16
- Unit
- px
- Applies To
- trigger
- Id
- wheel-row-height
- Label
- Wheel row height
- Kind
- exact
- Token
- --cds-size-40
- Value
- 40
- Unit
- px
- Applies To
- wheel-column
- selection-band
Layout
- Alignment
- Trigger text fills the available row while the optional icon remains trailing; wheel columns share one centered selection band.
- Flow
- Trigger opens a modal, wheels edit a working date, and the full-width confirm action commits it.
- Notes
- Clamp display and working dates to the inclusive minimum and maximum range.
- Keep the committed value unchanged until confirmation.
Typography And Color
- Typography
- Label
- Trigger and wheel text
- Description
- Use the body ramp for the selected date and wheel options.
- Token
- --cds-type-body-size
- Colors
- Label
- Trigger and selection band
- Description
- Use the semantic input container.
- Token
- --cds-input-container
- Label
- Selected text
- Description
- Use primary text emphasis for dates and active wheel rows.
- Token
- --cds-text-primary
- Label
- Placeholder
- Description
- Use secondary text emphasis while no date is committed.
- Token
- --cds-text-secondary
- Label
- Validation
- Description
- Use the solid danger role for invalid indication and copy.
- Token
- --cds-status-danger-solid
States
- Id
- empty
- Label
- Empty
- Description
- Shows the placeholder and opens wheels at the clamped placeholder date.
- Id
- selected
- Label
- Selected
- Description
- Shows the committed ISO date in human-readable display format.
- Id
- open
- Label
- Open
- Description
- Exposes expanded state and presents the working date in the modal wheels.
- Id
- invalid
- Label
- Invalid
- Description
- Shows the danger border and invalid semantics. The corrective message belongs to the enclosing Field.
- Id
- disabled
- Label
- Disabled
- Description
- Blocks opening the sheet and dims the trigger.
Behavior
- Label
- ISO boundary
- Description
- Accept and emit calendar dates as YYYY-MM-DD strings without time-zone conversion.
- Label
- Bounded wheels
- Description
- Trim month, day, and year options so no visible combination falls outside the range.
- Label
- Confirmation
- Description
- Commit the working date only when the confirm action is pressed; dismissal preserves the prior value.
- Label
- Keyboard wheel input
- Description
- Support ArrowUp, ArrowDown, Home, and End on each wheel column.
Accessibility
- Label
- Trigger name and state
- Description
- Associate a visible Field label or accessible label and expose dialog popup, expanded, required, invalid, and described-by states.
- Label
- Wheel names
- Description
- Expose the date as a group containing independently named Month, Day, and Year listboxes.
- Label
- Active options
- Description
- Expose the centered wheel option through selected and active-descendant semantics.
Content Adaptation
- Label
- Trigger truncation
- Description
- Truncate a long localized display date on one line without displacing the icon.
- Label
- Localized labels
- Description
- Allow product surfaces to provide localized sheet and confirm labels while preserving the ISO data contract.
Motion Haptics
- Motion
- Label
- Sheet presentation
- Description
- Delegate opening and dismissal motion to Modal and keep wheel snapping within each column.
- Haptics
- Label
- Wheel feedback
- Description
- Request the selection haptic once per user-driven wheel row crossed.
Platform Differences
- Platforms
- web
- Description
- The web implementation emulates a native wheel with scroll snapping and keyboard listboxes.
- Rationale
- HTML has no interoperable month/day/year wheel control, so the webview preserves the native interaction contract with explicit semantics.