Component contract
What it must accomplish
Help people enter or choose a valid date without guessing format or availability.
EmptyPartialValidInvalidCalendar openUnavailableDisabled
Usage
Choose the control by behavior
Use it when
- A date affects eligibility, scheduling, or records
- Known constraints can prevent invalid choices
- Typing or calendar selection can improve the task
Use another pattern when
- A relative duration is the real question
- The precise date is unnecessary
- A calendar would force excessive navigation for distant dates
Anatomy
Stable parts create a reliable contract
- 1Label
- 2Day, month, and year input or single field
- 3Format hint
- 4Calendar trigger when useful
- 5Constraint and error message
Explanation
Interaction and keyboard behavior
- Every field remains reachable in reading order
- Calendar grids use documented Arrow-key behavior
- Escape closes the calendar and returns focus
Why this matters
Visual similarity does not guarantee behavioral equivalence. The component contract must preserve state, focus, semantics, and recovery across input methods.
Cross-system baseline
Accessible behavior
- State the expected format before entry
- Do not rely on placeholder text
- Announce unavailable dates and validation errors
- Permit direct text entry when a calendar is inefficient
Responsive considerations
Adapt the decision—not only the dimensions
Avoid wide desktop-only calendars. Keep fields large enough for zoom and software keyboards, and prevent overlays from being obscured by the viewport.
Content considerations
Language is part of the component
- Use locale-appropriate examples
- Explain minimum and maximum dates
- Name timezone implications when relevant
Common mistakes
Patterns that weaken the experience
01
Forcing calendar navigation across decades
02
Rejecting valid localized entry without guidance
03
Auto-correcting ambiguous dates silently
Comparison
What to study across systems
GOV.UK and NHS favor explicit text inputs for memorable dates; enterprise systems add calendar pickers for scheduling and range constraints.
Open comparison