DateInput
Use CDateInput when one native calendar date is the application value. It preserves browser keyboard, touch picker, autofill, validation, reset, and Form behavior while keeping the submitted value locale-neutral.
Collect one date
Compose the input in CField for a visible label, description, error, and shared state. A standalone input needs an accessible name supplied through attrs or an external native label.
<c-CField required>
<c-fill name="label">Arrival date</c-fill>
<c-fill name="default"><c-CDateInput name="arrival" /></c-fill>
</c-CField>
Show code
from datetime import date
from typing import Any
import citry_ui
from citry import Component, citry
from citry_ui import CDateInput
citry.register_library(citry_ui)
# ruff: noqa: E501 - template and CSS lines stay readable in public source examples
class BasicDateInput(Component):
class Kwargs:
pass
class Slots:
pass
def template_data(self, kwargs: Kwargs, slots: Slots) -> dict[str, Any]: # noqa: ARG002
return {"python_input": CDateInput(value=date(2026, 8, 19), attrs={"aria-label": "Python date"})}
template = """
<section class="date-input-demo-grid">
<c-CField required>
<c-fill name="label">Arrival date</c-fill>
<c-fill name="description">Choose your check-in day.</c-fill>
<c-fill name="default"><c-CDateInput name="arrival" /></c-fill>
</c-CField>
<article><h3>Python composition</h3>{{ python_input }}</article>
</section>
"""
css = ":where(.date-input-demo-grid){display:grid;grid-template-columns:repeat(auto-fit,minmax(15rem,1fr));gap:1.25rem}"
preview = BasicDateInput()
preview # noqa: B018
Python composition accepts an exact datetime.date; a datetime, localized text, or noncanonical string is rejected.
Set exact bounds
min, max, and positive integer step map directly to native date constraints. The server must validate submitted values again.
Show code
from citry import Component
# ruff: noqa: E501 - template lines stay readable in the public source example
class DateInputBounds(Component):
class Kwargs:
pass
class Slots:
pass
template = """
<c-CField required>
<c-fill name="label">Alternating August date</c-fill>
<c-fill name="description">Choose every second day from 1 through 31 August 2026.</c-fill>
<c-fill name="default"><c-CDateInput name="day" value="2026-08-19" min="2026-08-01" max="2026-08-31" c-step="2" /></c-fill>
</c-CField>
"""
preview = DateInputBounds()
preview # noqa: B018
The component does not clamp or round. Browser constraint validity remains observable through the native input.
Use native Forms and reset
name contributes exactly one canonical value. Disabled inputs are omitted; readonly inputs remain submitted. CForm and CField own their shared state.
Show code
from citry import Component
# ruff: noqa: E501 - template expression remains readable as authored HTML
class DateInputForm(Component):
class Kwargs:
pass
class Slots:
pass
template = """
<form class="date-input-demo-stack" x-data="{result:'Submit or reset the Form'}" @submit.prevent="result=JSON.stringify(Array.from(new FormData($event.target).entries()))">
<c-CField required>
<c-fill name="label">Departure date</c-fill>
<c-fill name="default"><c-CDateInput name="departure" value="2026-08-22" /></c-fill>
</c-CField>
<c-CGroup><c-CButton type="submit">Submit</c-CButton><c-CButton type="reset" variant="outline">Reset</c-CButton></c-CGroup>
<output x-text="result">Submit or reset the Form</output>
</form>
"""
css = ":where(.date-input-demo-stack){display:grid;justify-items:start;gap:1rem}"
preview = DateInputForm()
preview # noqa: B018
Control a date in Alpine
Client value accepts a canonical string or null. Native input and change events remain the observation surface; a supplied client value is restored after event listeners run until its owner accepts another value.
Show code
from citry import Component
# ruff: noqa: E501 - Alpine expressions stay readable in the public source example
class ControlledDateInput(Component):
class Kwargs:
pass
class Slots:
pass
template = """
<section class="date-input-demo-stack" x-data="{day:'2026-08-19',last:'No native input yet'}">
<c-CDateInput c-attrs="{'aria-label':'Controlled arrival date'}" value="2026-08-19" $c-props="{value:day}" @input="last=$event.currentTarget.value" />
<c-CGroup><button type="button" @click="day='2026-08-22'">Set 22 August</button><button type="button" @click="day=null">Clear</button></c-CGroup>
<output x-text="last">No native input yet</output>
</section>
"""
css = ":where(.date-input-demo-stack){display:grid;justify-items:start;gap:.75rem}"
preview = ControlledDateInput()
preview # noqa: B018
Omitting client value releases control at the last accepted value.
Hint birthday autofill
The ordinary native autocomplete input can request browser-managed birthday autofill without changing the canonical value contract.
Show code
from citry import Component
class BirthdayDateInput(Component):
class Kwargs:
pass
class Slots:
pass
template = """
<c-CField>
<c-fill name="label">Date of birth</c-fill>
<c-fill name="description">Your browser may offer saved birthday information.</c-fill>
<c-fill name="default"><c-CDateInput name="birthday" autocomplete="bday" max="2026-08-19" /></c-fill>
</c-CField>
"""
preview = BirthdayDateInput()
preview # noqa: B018
Understand locale behavior
The DOM value and FormData stay YYYY-MM-DD; the browser chooses the visible segment spelling and native picker UI. That UI may follow browser or platform locale rather than the nearest Citry i18n provider.
Show code
from citry import Component
# ruff: noqa: E501 - localized template and CSS lines stay readable in the public source example
class DateInputLocales(Component):
class Kwargs:
pass
class Slots:
pass
template = """
<section class="date-input-demo-grid">
<div lang="en"><label for="date-en">English context</label><c-CDateInput id="date-en" value="2026-08-19" /></div>
<div lang="ar" dir="rtl"><label for="date-ar">Ψ³ΩΨ§Ω ΨΉΨ±Ψ¨Ω</label><c-CDateInput id="date-ar" value="2026-08-19" /></div>
<p>The submitted value is 2026-08-19 in both controls; visible native formatting remains browser-owned.</p>
</section>
"""
css = ":where(.date-input-demo-grid){display:grid;grid-template-columns:repeat(auto-fit,minmax(14rem,1fr));gap:1rem}:where(.date-input-demo-grid>div){display:grid;gap:.5rem}"
preview = DateInputLocales()
preview # noqa: B018
Use the custom Calendar/DatePicker family when the active Citry locale must determine the exact calendar UI.
Compare states and styles
Outline, filled, and plain variants combine with sm, md, and lg sizes. Public variables customize the outer native control without hiding its picker indicator or replacing its internal semantics.
Show code
from citry import Component
# ruff: noqa: E501 - template and CSS lines stay readable in the public source example
class DateInputStates(Component):
class Kwargs:
pass
class Slots:
pass
template = """
<section class="date-input-state-grid">
<c-CDateInput c-attrs="{'aria-label':'Small outlined date'}" value="2026-08-19" size="sm" />
<c-CDateInput c-attrs="{'aria-label':'Filled date'}" value="2026-08-20" variant="filled" />
<c-CDateInput c-attrs="{'aria-label':'Large plain date'}" value="2026-08-21" size="lg" variant="plain" />
<c-CDateInput c-attrs="{'aria-label':'Readonly date'}" value="2026-08-22" readonly />
<c-CDateInput c-attrs="{'aria-label':'Disabled date'}" value="2026-08-23" disabled />
<c-CDateInput c-attrs="{'aria-label':'Invalid date'}" value="2026-08-24" invalid />
</section>
"""
css = ":where(.date-input-state-grid){display:grid;grid-template-columns:repeat(auto-fit,minmax(13rem,1fr));gap:1rem}"
preview = DateInputStates()
preview # noqa: B018
Show code
from citry import Component
class StyledDateInput(Component):
class Kwargs:
pass
class Slots:
pass
template = (
'<c-CDateInput c-attrs="{\'aria-label\':\'Brand date\'}" value="2026-08-19" class_="brand-date-input" />'
)
css = """
:where(.brand-date-input){--cui-date-input-background:light-dark(#f0fdf4,#14261d);--cui-date-input-border-color:#16a34a;--cui-date-input-focus-color:#15803d;--cui-date-input-radius:1rem}
"""
preview = StyledDateInput()
preview # noqa: B018
CDateInput owns no translation key: labels and errors belong to the application, while native picker and validation prose belong to the browser.
API reference
Inputs
CDateInput server inputs
Server inputs are passed in a template through <c-CDateInput ... /> or in Python through CDateInput(...).
| Input | Type | Default | Effect |
|---|---|---|---|
value | CDateInputValue | None (CDateInputValue) | None | Sets the initial/reset exact date or empty value. |
name | str | None | None | Sets the native Form field name. |
form | str | None | None | Associates the input with an external native Form ID. |
id | str | None | generated | Sets the public native input ID. |
min | CDateInputValue | None (CDateInputValue) | None | Sets the inclusive native minimum date. |
max | CDateInputValue | None (CDateInputValue) | None | Sets the inclusive native maximum date. |
step | int | 1 | Sets the exact positive native day step. |
required | bool | None | None | Enables native empty-value validity outside Field; Field owns it inside Field. |
disabled | bool | None | None | Blocks interaction and Form participation outside Field; Form disabledness also wins. |
readonly | bool | None | None | Keeps a focusable submitted value while blocking native edits. |
invalid | bool | None | None | Adds application invalid state to revealed native validity. |
autocomplete | str | None | None | Sets a native autofill hint such as bday. |
variant | "outline" | "filled" | "plain" (CDateInputVariant) | "outline" | Selects outer native-control treatment. |
size | "sm" | "md" | "lg" (CDateInputSize) | "md" | Selects coordinated sizing. |
class_ | CClassValue | None (CClassValue) | None | Adds classes to the native root and merges with attrs. |
style | CStyleValue | None (CStyleValue) | None | Adds styles to the native root and merges with attrs. |
attrs | Mapping[str, object] | None | None | Adds copied allowed native attributes without replacing owned identity state constraints or runtime markers. |
CDateInput client inputs
Client inputs are passed in the browser through the $c-props="{ ... }" attribute on <c-CDateInput />.
| Input | Type | Omitted behavior | Effect |
|---|---|---|---|
value | canonical string | null | Releases control at the latest accepted value. | Controls the exact native value while supplied. |
min | canonical string | null | Uses the server minimum. | Replaces or removes the inclusive minimum. |
max | canonical string | null | Uses the server maximum. | Replaces or removes the inclusive maximum. |
step | positive integer | Uses the server step. | Replaces the native day step. |
required | boolean | Uses server or Field state. | Controls standalone required validity. |
disabled | boolean | Uses server or owner state. | Controls interaction and Form participation. |
readonly | boolean | Uses server or owner state. | Controls focusable nonmutable state. |
invalid | boolean | Uses server or Field state. | Controls application invalid state. |
variant | "outline" | "filled" | "plain" (CDateInputVariant) | Uses the server input. | Controls presentation. |
size | "sm" | "md" | "lg" (CDateInputSize) | Uses the server input. | Controls coordinated sizing. |
Slots
-
Events
-
Methods
-
CSS
CSS variables to theme the components. Set them on an ancestor or the component itself.
CDateInput CSS variables
Apply these variables to CDateInput or one of its ancestors.
| Variable | Type | Purpose | Default |
|---|---|---|---|
--cui-date-input-background | color | Native control background. | Canvas |
--cui-date-input-foreground | color | Native date text and indicator foreground. | CanvasText |
--cui-date-input-border-color | color | Resting border. | Mixed CanvasText. |
--cui-date-input-hover-border-color | color | Hover border. | Stronger mixed CanvasText. |
--cui-date-input-focus-color | color | Focus border and outline. | Highlight |
--cui-date-input-invalid-border-color | color | Invalid border. | Theme error. |
--cui-date-input-disabled-background | color | Disabled background. | Muted Canvas. |
--cui-date-input-radius | length | Outer corner radius. | 0.5rem |
--cui-date-input-height | length | Minimum block size. | 2.5rem |
--cui-date-input-inline-padding | length | Logical inline inset. | 0.75rem |
--cui-date-input-block-padding | length | Logical block inset. | 0.5rem |
--cui-date-input-font-size | length | Date text size. | 1rem |
--cui-date-input-min-inline-size | length | Preferred minimum width before container clamping. | 10rem |
Attributes
HTML attributes defined on the components that you can refer to for CSS, inspection, and testing. Read-only.
CDateInput attributes
| Attribute | Element | Type | Meaning |
|---|---|---|---|
type | Native root input | "date" | Selects browser-owned calendar-date editing and picker behavior. |
value | Native root input | canonical date | absent | Carries the initial/reset date. |
min | Native root input | canonical date | absent | Sets inclusive native minimum validity. |
max | Native root input | canonical date | absent | Sets inclusive native maximum validity. |
step | Native root input | positive integer | Sets the day step grid. |
aria-invalid | Native root input | "true" | absent | Mirrors application or revealed native invalidity. |
data-empty | Native root input | present | absent | Mirrors an empty canonical value. |
data-required | Native root input | present | absent | Mirrors effective requiredness. |
data-disabled | Native root input | present | absent | Mirrors effective disabledness. |
data-readonly | Native root input | present | absent | Mirrors effective readonly state. |
data-invalid | Native root input | present | absent | Mirrors application or revealed native invalidity. |
data-variant | Native root input | CDateInputVariant (CDateInputVariant) | Mirrors visual treatment. |
data-size | Native root input | CDateInputSize (CDateInputSize) | Mirrors coordinated sizing. |
Selectors
Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.
CDateInput selectors
| Selector | Element | Purpose |
|---|---|---|
[data-citry-ui-part="date-input"] | Native root input | Stable styling state Form focus event and attrs destination. |
Interfaces
Aliases and data shapes referenced above.
Input type aliases
| Interface | Definition |
|---|---|
CDateInputValue | date | str |
CDateInputVariant | Literal["outline", "filled", "plain"] |
CDateInputSize | Literal["sm", "md", "lg"] |
CClassValue | str | Mapping[str, bool] | Sequence[CClassValue] |
CStyleValue | str | Mapping[str, object] | Sequence[CStyleValue] |
Translation keys
-