Date picker

When to use it

Use it when the format matters, when you need a range, or when the reader benefits from seeing a month at once. <input type="date"> is otherwise the better answer — it is free, it is accessible, and it gives a phone the platform's own picker.

The trade is explicit: the native control renders differently in every browser and cannot be styled, and it has no range mode. If neither matters to you, use it.

Here is a working one. Click the field — or focus it and press Enter, Space or Down — and the calendar opens.

<div class="field" style="max-inline-size:22rem">
  <label class="label" for="dx-date-live">Ship date</label>
  <div class="datefield" data-deck-datepicker data-format="iso">
    <input class="input" id="dx-date-live" name="ship_date">
  </div>
</div>

That really is all of it. DatePicker.build() inserts the calendar icon and the .datefield-clear button if they are not already there, sets readonly and cursor: pointer on the input, creates the popover panel and appends it to the body. Write the icon yourself only if you want a different one — the script skips anything already present.

The attributes, all optional:

The trigger field

.datefield positions an icon inside the input's starting edge — the same technique as .search, with pointer-events: none so clicking the icon focuses the field. The input is readonly and cursor: pointer, because the value comes from the calendar rather than the keyboard.

.datefield-clear is hidden until the field has a value: .datefield:not(.has-value) .datefield-clear { display: none }. .has-value is set by deck.js and is the one state here an author never writes.

<div class="field" style="max-inline-size:22rem">
  <label class="label" for="dx-date">Ship date</label>
  <div class="datefield has-value">
    <svg class="icon" aria-hidden="true"><use href="/assets/deck/deck-icons.svg#calendar"></use></svg>
    <input class="input" id="dx-date" value="2026-03-11" readonly>
    <button class="datefield-clear" aria-label="Clear date">
      <svg class="icon icon-sm" aria-hidden="true"><use href="/assets/deck/deck-icons.svg#x"></use></svg>
    </button>
  </div>
</div>

Opening and closing

The panel is a native popover, so most of its behaviour is the platform's. What deck.js adds is the ways in:

That last row is a wart rather than a bug. The handler calls showPopover() rather than togglePopover(), so the field opens the panel and never closes it. Escape and an outside click both work, so nothing is unreachable — but a reader who clicks the field expecting it to close will be surprised. Recorded in FINDINGS.md.

deck.js also sets popovertarget on the input, which does nothing: the attribute is only honoured on buttons. The click handler is what actually opens the panel. aria-haspopup="dialog", set alongside it, is meaningful and is what tells a screen reader the field opens something.

Eight day states

.datepicker-day is a 38px square — 42px on a coarse pointer, so it clears the touch target on a phone. Eight classes compose on it, and the way they compose is what makes a range selection read correctly.

The band is the fiddly part. A range that spans a week boundary has to look continuous within each row and rounded where it stops, so the source uses :has() to round the first and last cell of every row:

.datepicker-grid:has(.is-in-range) .datepicker-day.is-in-range:first-child { … }
.datepicker-grid:has(.is-in-range) .datepicker-day.is-in-range:nth-child(7n) { … }

.is-range-start.is-range-end — a single-day range — gets the full radius back, so selecting one day twice does not leave a half-rounded pill.

All eight are set by deck.js at runtime and are internal. They are documented because you may want to restyle them, not because you should write them.

Positioning

The panel is a native popover — light dismiss, Escape and the top layer from the platform — and src/25-anchor.css anchors it to its field with the same position-area and fallback chain as a .menu. Near the bottom of a window it opens upward, and position-try-order: most-block-size picks the direction with the most room rather than the first that fits.

That matters more for a calendar than for a menu: a picker that opens downward with four rows visible and the rest cut off is unusable, whereas a menu merely scrolls.

Presets and the month jump

.datepicker-presets is a rail of shortcuts — "Last 7 days", "This month". Below 40rem it is a horizontal scroller above the calendar; from 40rem up, .datepicker-layout:has(.datepicker-presets) turns the whole panel into a row and the rail becomes a column beside it.

.datepicker-jump opens .datepicker-months, a grid of twelve months, so a reader choosing a date two years out does not press the next-month arrow twenty-four times.

A picker without a jump is the most common date-picker complaint there is. If you are accepting dates more than a few months away, turn it on.

Classes

Generated from src/10-datepicker.css by tools/docs/extract.mjs.

Tokens

Accessibility

• Consider <input type="date"> first. It is fully accessible, gives a phone the platform picker, and needs nothing from you. A custom picker is a large accessibility surface to take on, and it should be taken on for a reason — a range, a format, a preset rail.
• The input is readonly, not disabled, so it stays focusable and its value is still submitted. That is the right choice, but it also means a reader cannot type a date — which is faster than clicking for anyone who knows the date they want. Consider allowing typed input for single-date fields.
• Days are 38px, below the 44px target — but @media (pointer: coarse) raises them to 42px, which is close. This is the only place in Deck where a target is adjusted by pointer type rather than left at one value.
• A calendar grid needs keyboard navigation. Arrow keys between days, Page Up and Down between months, Home and End for the week. The behaviour is in deck.js; if you build your own panel with these classes, the keys are your responsibility.
• State is conveyed by more than colour. Today is a dot, selected is a filled square, blocked is faded and gets the disabled attribute. A range is a band, which is colour alone — so the selected ends carry the fill as well.
• Announce the chosen value. .datepicker-readout shows the current selection in the panel; put it in an aria-live region so a range being built is announced as it changes.
• The clear button needs a label. It is icon-only — aria-label="Clear date", as in the example above.
• .is-preview is hover-only and therefore invisible to keyboard and touch. It is a nicety for pointer users, not a state anyone else relies on.

Right to left

The field's icon and clear button use inset-inline-start and inset-inline-end, and the range ends use border-start-start-radius and friends — logical corners — so a range rounds on the correct side in either direction.

The calendar grid itself is a CSS grid, so the days of the week fill from the right under dir="rtl". The week still starts where the locale says it does, which is the picker's job rather than the stylesheet's.

Reduced motion

The panel fades and rises six pixels over 190ms, with overlay and display in the transition so it stays rendered while it closes. The global reset collapses it to .01ms under prefers-reduced-motion: reduce. Nothing inside the calendar animates.

Printing

src/99-print.css lists .datepicker among the chrome that never prints. The panel is a control for choosing a value; what prints is the value in the field, which is an ordinary input and gets the standard print treatment.

Overriding it

@layer app.components {
  /* Larger days everywhere, not only on touch */
  .datepicker-day { inline-size: 44px; block-size: 44px; }

  /* A weekend tint */
  .datepicker-day:nth-child(7n), .datepicker-day:nth-child(7n-6) {
    color: var(--text-muted);
  }

  /* Keep the preset rail beside the calendar at every width */
  .datepicker-layout:has(.datepicker-presets) { flex-direction: row; }
}

The :nth-child(7n) selectors assume a Sunday-first week. Which day starts the week is a locale question, so a weekend tint that is correct everywhere needs the picker to mark the cells rather than the stylesheet to count them.

When not to use it

• Not when <input type="date"> would do. A single date with no format requirement is a solved problem, and the native control is better at it than any custom panel.
• Not for a date the reader knows. A birth date is faster typed than navigated. If your picker is readonly, a reader entering 1974 has to press the year jump and scroll.
• Not for a time. .datepicker-time exists for a time row inside the panel, but a standalone time is <input type="time">.
• Not for a month or a quarter. Use a select — a calendar grid for twelve options is a lot of panel for a short list.
• Not without data-min and data-max when the valid range is known. .is-blocked exists so the picker can say no before the server does.