DatePicker
A date selector with a YYYY-MM-DD string value.
Usage
Popup, Field, and Inline
v-model:visible controls the popup, variant picks the surface, and popup="false" renders inline.
Loading demo...
Best Practices
- Store dates only as
YYYY-MM-DDstrings; the component has no time zone or time of day. - Use
variant="field"for dense desktop forms andvariant="picker"for mobile-first flows; useadaptiveonly after checking both surfaces in the same layout. - When the surrounding card already handles disclosure and spacing, render the
pickersurface inline withpopup="false". - Set
weekStartsOnexplicitly when locale conventions matter.
Edge and States
The date field matches the input's height and takes its hover, open and disabled colours from the input, without lowering opacity when disabled.
Loading demo...
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
modelValue | string | DateRangeValue | '' | A YYYY-MM-DD date; a [start, end] pair under range. |
visible | boolean | false | Popup visibility, bound with v-model:visible. |
popup | boolean | true | Picker surface only: false renders it inline. |
variant | 'picker' | 'field' | 'adaptive' | 'picker' | picker is the wheel, field the calendar field, adaptive switches by viewport width. |
title | string | 'Select date' | Toolbar title, forwarded to TxPicker. |
placeholder | string | 'Select date' | Placeholder of the empty field calendar. |
min | string | - | Earliest selectable date (YYYY-MM-DD); invalid values are ignored. |
max | string | - | Latest selectable date (YYYY-MM-DD); invalid values are ignored. |
disabled | boolean | false | Blocks interaction. |
showToolbar | boolean | true | Shows the picker toolbar. |
confirmText | string | 'Confirm' | Confirm button label, forwarded to TxPicker. |
cancelText | string | 'Cancel' | Cancel button label, forwarded to TxPicker. |
closeOnClickMask | boolean | true | Closes the popup when the mask is clicked. |
adaptiveBreakpoint | number | 768 | Minimum viewport width at which adaptive shows the field calendar. |
weekStartsOn | 0 | 1 | 0 | First day of the field calendar's week: 0 Sunday, 1 Monday. |
range | boolean | false | Field calendar only: picks a start and an end date; the wheel ignores it. |
rangeSeparator | string | ' → ' | Text between the two dates in the field's display value. |
Events
| Event | Params | Description |
|---|---|---|
update:modelValue | (value: string | DateRangeValue) | Fires with the formatted value when the date changes. |
change | (value: string | DateRangeValue) | Fires together with update:modelValue. |
update:visible | (visible: boolean) | Fires when visibility should change. |
confirm | (value: string) | Fires with the current date when the user confirms. |
cancel | - | Fires when the user cancels. |
open | - | Fires on open. |
close | - | Fires on close. |
CSS Variables
| Variable | Default | Description |
|---|---|---|
--tx-date-picker-selected-shade | #111827 | Dark end of the gradient on the selected day, month or year in the field calendar, mixed into the primary at 28%. |
Types
type DateRangeValue = [string, string] // [start, end], each YYYY-MM-DD
The range value; it is emitted only once both ends are chosen.
Overview
- The value is always emitted as
YYYY-MM-DD; an empty or invalid value starts from local today, clamped tomin/max. - The
pickersurface opens throughv-model:visible; thefieldsurface renders throughTxPopoverand syncsupdate:visible,open, andclosetoo. - Column changes emit
update:modelValueandchangelive;confirmthen closes the way the picker does. - The field calendar is sized to the month grid (280–360px), not the field. Its title zooms out day → month → 12-year block, the arrows step the current view, and closing returns to the day grid.
range: the first click anchors the start and previews the band, the second closes it and emits[start, end]in order. Nothing is emitted before both ends exist, and closing mid-pick abandons it.- The calendar uses
grid/gridcellwitharia-selected; under reduced motion, slides and zooms collapse to a short fade.
Technologies
- Days inside a range carry
is-in-range; the ends carryis-range-start/is-range-end. - Source:
packages/tuffex/packages/components/src/date-picker/.
查看源码
packages/tuffex/packages/components/src/date-picker/index.ts