Date Picker

A date selection component with calendar interface.

The Date Picker opens the Calendar component in a popover and adds the field, formatting and form serialization. If you want the grid always visible inline, use the Calendar directly.

Single Date

<c-ui.datepicker mode="single" />

{% cotton ui.datepicker mode="single" /%}

Range

Select a range of dates with a start and end date.

<c-ui.datepicker mode="range" />

{% cotton ui.datepicker mode="range" /%}

Limits

Restrict selectable dates with min_date / max_date (bounds), :disabled_days (weekday numbers, 0 = Sunday) or :disabled_dates (specific dates). Disabled days are greyed out and can't be selected.

Weekends disabled

Bounded (9th to 20th)

Specific dates off

{# Disable weekends (0 = Sunday, 6 = Saturday) #}
<c-ui.datepicker mode="single" :disabled_days="[0, 6]" />

{# Bound the selectable range #}
<c-ui.datepicker mode="single" min_date="2026-06-09" max_date="2026-06-20" />

{# Disable specific dates #}
<c-ui.datepicker mode="single" :disabled_dates="['2026-06-11', '2026-06-12', '2026-06-18']" />

{# Disable weekends (0 = Sunday, 6 = Saturday) #}
{% cotton ui.datepicker mode="single" :disabled_days="[0, 6]" /%}

{# Bound the selectable range #}
{% cotton ui.datepicker mode="single" min_date="2026-06-09" max_date="2026-06-20" /%}

{# Disable specific dates #}
{% cotton ui.datepicker mode="single" :disabled_dates="['2026-06-11', '2026-06-12', '2026-06-18']" /%}

Responsive positioning

The calendar flips and realigns to stay within the viewport. Drag the handles to resize the preview on either axis and watch it reposition.

As a field

Give it any field attribute (label, description, error or badge) and the datepicker wraps itself in a Field component, giving you the label, helper text and error styling with no extra markup.

Date of birth

We'll keep this private.

<c-ui.datepicker
    label="Date of birth"
    description="We'll keep this private."
/>

{% cotton ui.datepicker
    label="Date of birth"
    description="We'll keep this private."
/%}

API Reference

Props

Name	Description	Type	Options	Default
`mode`	Selection mode for single date, date range, or multiple dates.	str	`singlerangemultiple`	single
`:value`	Initial value: a YYYY-MM-DD string (single), or a list of dates (range/multiple).	str\|list	—	None
`name`	Form field name for the submitted value (single/multiple modes).	str	—
`fromName`	Form field name for the range start (range mode).	str	—
`toName`	Form field name for the range end (range mode).	str	—
`size`	Size variant of the trigger, from xs to 2xl.	str	`xssmmdlgxl2xl`	md
`:open`	Render the calendar open on load.	bool	`TrueFalse`	False
`disabled`	Prevents interaction with the datepicker.	bool	`TrueFalse`	False
`format`	Display format. 'auto' (plus 'short' / 'medium' / 'long' / 'full') formats per the user's locale via Intl; any other value is treated as a date-fns format string. Affects display only, not the submitted value.	str	auto \| short \| medium \| long \| full \| date-fns string	auto
`locale`	Locale used when format is 'auto' (e.g. 'en-GB'). Defaults to the browser's locale.	str	Any BCP-47 locale tag
`value_format`	Format of the submitted value (date-fns tokens). Formatted locally, so the date never shifts a day via a UTC round-trip.	str	Any valid date-fns format	yyyy-MM-dd
`min_date`	Earliest selectable date (YYYY-MM-DD); earlier dates are disabled.	str	—
`max_date`	Latest selectable date (YYYY-MM-DD); later dates are disabled.	str	—
`:disabled_days`	Weekday numbers to disable (0 = Sunday … 6 = Saturday).	list	—	None
`:disabled_dates`	Specific dates to disable (list of YYYY-MM-DD).	list	—	None
`:min / :max`	In range mode, the minimum / maximum number of days the range may span.	int	—	None
`:close_on_complete`	Close the calendar once the selection is complete (single: a date is picked; range: both ends set; multiple: never auto-closes).	bool	`TrueFalse`	True
`:trap`	Trap focus inside the calendar while it is open (keyboard accessibility).	bool	`TrueFalse`	True