Theme
Version
GitHub PyPI Discord
On this page

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>
Collect one date
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.

Constrain a native date
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.

Submit and reset a date
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.

Control a date
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.

Request birthday autofill
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.

Compare native locale contexts
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.

Compare DateInput states
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
Customize DateInput
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(...).

InputTypeDefaultEffect
valueCDateInputValue | None (CDateInputValue)NoneSets the initial/reset exact date or empty value.
namestr | NoneNoneSets the native Form field name.
formstr | NoneNoneAssociates the input with an external native Form ID.
idstr | NonegeneratedSets the public native input ID.
minCDateInputValue | None (CDateInputValue)NoneSets the inclusive native minimum date.
maxCDateInputValue | None (CDateInputValue)NoneSets the inclusive native maximum date.
stepint1Sets the exact positive native day step.
requiredbool | NoneNoneEnables native empty-value validity outside Field; Field owns it inside Field.
disabledbool | NoneNoneBlocks interaction and Form participation outside Field; Form disabledness also wins.
readonlybool | NoneNoneKeeps a focusable submitted value while blocking native edits.
invalidbool | NoneNoneAdds application invalid state to revealed native validity.
autocompletestr | NoneNoneSets 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)NoneAdds classes to the native root and merges with attrs.
styleCStyleValue | None (CStyleValue)NoneAdds styles to the native root and merges with attrs.
attrsMapping[str, object] | NoneNoneAdds 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 />.

InputTypeOmitted behaviorEffect
valuecanonical string | nullReleases control at the latest accepted value.Controls the exact native value while supplied.
mincanonical string | nullUses the server minimum.Replaces or removes the inclusive minimum.
maxcanonical string | nullUses the server maximum.Replaces or removes the inclusive maximum.
steppositive integerUses the server step.Replaces the native day step.
requiredbooleanUses server or Field state.Controls standalone required validity.
disabledbooleanUses server or owner state.Controls interaction and Form participation.
readonlybooleanUses server or owner state.Controls focusable nonmutable state.
invalidbooleanUses 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.

VariableTypePurposeDefault
--cui-date-input-backgroundcolorNative control background.Canvas
--cui-date-input-foregroundcolorNative date text and indicator foreground.CanvasText
--cui-date-input-border-colorcolorResting border.Mixed CanvasText.
--cui-date-input-hover-border-colorcolorHover border.Stronger mixed CanvasText.
--cui-date-input-focus-colorcolorFocus border and outline.Highlight
--cui-date-input-invalid-border-colorcolorInvalid border.Theme error.
--cui-date-input-disabled-backgroundcolorDisabled background.Muted Canvas.
--cui-date-input-radiuslengthOuter corner radius.0.5rem
--cui-date-input-heightlengthMinimum block size.2.5rem
--cui-date-input-inline-paddinglengthLogical inline inset.0.75rem
--cui-date-input-block-paddinglengthLogical block inset.0.5rem
--cui-date-input-font-sizelengthDate text size.1rem
--cui-date-input-min-inline-sizelengthPreferred 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

AttributeElementTypeMeaning
typeNative root input"date"Selects browser-owned calendar-date editing and picker behavior.
valueNative root inputcanonical date | absentCarries the initial/reset date.
minNative root inputcanonical date | absentSets inclusive native minimum validity.
maxNative root inputcanonical date | absentSets inclusive native maximum validity.
stepNative root inputpositive integerSets the day step grid.
aria-invalidNative root input"true" | absentMirrors application or revealed native invalidity.
data-emptyNative root inputpresent | absentMirrors an empty canonical value.
data-requiredNative root inputpresent | absentMirrors effective requiredness.
data-disabledNative root inputpresent | absentMirrors effective disabledness.
data-readonlyNative root inputpresent | absentMirrors effective readonly state.
data-invalidNative root inputpresent | absentMirrors application or revealed native invalidity.
data-variantNative root inputCDateInputVariant (CDateInputVariant)Mirrors visual treatment.
data-sizeNative root inputCDateInputSize (CDateInputSize)Mirrors coordinated sizing.

Selectors

Selectors for the DOM nodes in the components that you can use for CSS, inspection, and testing.

CDateInput selectors

SelectorElementPurpose
[data-citry-ui-part="date-input"]Native root inputStable styling state Form focus event and attrs destination.

Interfaces

Aliases and data shapes referenced above.

Input type aliases

InterfaceDefinition
CDateInputValuedate | str
CDateInputVariantLiteral["outline", "filled", "plain"]
CDateInputSizeLiteral["sm", "md", "lg"]
CClassValuestr | Mapping[str, bool] | Sequence[CClassValue]
CStyleValuestr | Mapping[str, object] | Sequence[CStyleValue]

Translation keys

-