Datepicker

A date, a range, a week, a month, a quarter or a year, picked from a panel or typed into the field.

Preview in Figma LLMs

Overview

Design

Code

DatePicker and RangePicker take the same props as Ant Design's, and the file is yours once it is installed. The kit adds no props beyond a ref on RangePicker's type, and it sets six icon defaults from your icon pack. Both are marked antuikit in the API tables below.

Install

npx antuikit@latest init

npx antuikit@latest add date-picker

The first command sets up AntuikitProvider and the theme tokens. The second adds this component.

Import

Import from @/components/ui/date-picker, not from antd. The path points at the file in your project.

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

RangePicker, and the pickers that are gone

DatePicker is one field. RangePicker is two fields sharing one panel, and many of its props take a pair: value, placeholder, disabled, allowEmpty, and id as { start, end }. It also takes a separator.

You can import it by name or read it off DatePicker. Both are the same component.

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

// The same component, for code written against DatePicker.RangePicker.

const { RangePicker: Same } = DatePicker

MonthPicker, WeekPicker, YearPicker, QuarterPicker and TimePicker are not included. Write <DatePicker picker="month" /> instead, and add the time-picker item for a time on its own.

RangePicker's ref is a RangePickerRef, whose focus takes an index: focus(1) puts the caret in the end field.

The axes

The props that take one of a fixed set of values. They match the properties in the Design tab.

picker: date (the default), week, month, quarter, year, time. Sets which panel opens and what one click picks. The suffix is a clock for time and a calendar for the rest.
variant: outlined (the default), filled, borderless, underlined.
status: error, warning. Set for you inside a Form.Item.
size: small, medium (the default), large. Follows the nearest size context when you leave it out.
placement: bottomLeft (the default), bottomRight, topLeft, topRight. Where the panel opens.

format sets what the field shows. A string formats and parses. An array formats with the first pattern and accepts all of them when typing. A function only formats, and makes the field read-only.

Flags

The booleans. Two of them change their default with the mode.

showTime (false) adds the time columns. A picker with a time is still picker="date".
needConfirm makes a pick wait for an OK button. It defaults to true when the panel has a time and false otherwise. Pass it to override either way.
multiple (false) puts several dates in one field as tags. It does not work with showTime or picker="time", and makes the field read-only.
allowClear (true) and disabled (false). On RangePicker, disabled also takes a pair, [boolean, boolean].
order (true) sorts a range picked backwards.
showNow shows the Today or Now link in the footer. It is on for a single date or time picker and off for RangePicker.
inputReadOnly (false) and preserveInvalidOnBlur (false). A function format or multiple turns on the first one, which leaves no way to type a date. See the Accessibility tab.
hasFeedback is set by Form.Item, not by you, and adds the validation icon after the suffix.

Slots

The props that take a node. Use them before reaching for a selector, since the panel renders in a portal.

suffixIcon, prefix and allowClear.clearIcon in the field, and separator between a RangePicker's two ends.
prevIcon, nextIcon, superPrevIcon and superNextIcon in the panel header.
cellRender draws one cell from (current, info). info carries originNode, today, type and locale. Return info.originNode for the cells you do not change.
panelRender wraps the whole panel. renderExtraFooter adds a line under it, a good place to explain a disabledDate rule.
presets takes a list of { label, value }. value can be a function, which runs on click.

Six of these default to your icon pack: the suffix, the four header arrows and the range separator. Pass your own node to replace one, or null to remove it.

The suffix is a clock when picker is time and a calendar otherwise. The clear icon and the range separator come from AntuikitProvider, and the separator turns around under dir="rtl".

Events

Save on the commit, not on the clicks that lead up to it.

onChange(date, dateString) is the commit. It gives you the date object and the formatted string.
onCalendarChange fires on every click in the panel, before the commit. Its info.range says which end of a range was just picked.
onOk fires on the OK button, so only when needConfirm is on.
onOpenChange, onPanelChange and onPickerValueChange follow the panel, not the value. The last one's info.source is panel for a click and reset for an open or a typed value.
onFocus, onBlur and onClear fire on the field. The first two receive (event, info).