DateField

<caos-date-field>

calendar-date input with a native date affordance

May be placed on a record page, a page inside an app and a step of a guided flow.

Inputs

Name	Attribute	Description	Type	Default	Required
label	label, markup only	The field’s name, drawn above the control and pointed at the input, so clicking it focuses the control. Left unset, no label is drawn.	text	none declared	Optional
value	value, markup only	The date, always as YYYY-MM-DD, whatever order the browser displays it in. Written back to this attribute as the person edits.	date	none declared	Optional
min	min, markup only	The earliest selectable date, as YYYY-MM-DD. Days before it are greyed in the calendar.	date	none declared	Optional
max	max, markup only	The latest selectable date, as YYYY-MM-DD. Days after it are greyed in the calendar.	date	none declared	Optional
step	step, markup only	The stepping interval in DAYS — 7 to allow only one day of the week within the window.	number	none declared	Optional
placeholder	placeholder, markup only	Forwarded to the inner input. A native date control draws its own empty format hint and mostly ignores this; it is honoured here because the shared implementation forwards it, not because a date input has a use for it.	text	none declared	Optional
name	name, markup only	The form name forwarded to the inner input, for a field submitted as part of a form.	text	none declared	Optional
required	required, markup only	This field has to be filled in. Draws the asterisk beside the label and marks the input required.	boolean	false	Optional
disabled	disabled, markup only	You may not change this date. Greys the control and refuses focus.	boolean	false	Optional
invalid	invalid, markup only	The date is wrong. Turns the border and the message red and marks the input invalid for a screen reader.	boolean	false	Optional
message	message, markup only	The line under the control — muted helper text on its own, the red reason when invalid is also set. A greyed-out day in the calendar says a date is not allowed; only this says why.	text	none declared	Optional
format	format, markup only	Which temporal control is drawn: date (the default) for a day, time for a time of day, datetime for both together. One field, three presentations — the same value attribute, label, validity and message in each. The field renderer picks it from the kind being edited: a Time field is a time, a DateTime is a date and a time, a Date is a date. Anything unrecognised reads as date, so a format nothing can draw degrades to a calendar rather than to a control with no affordance at all.	text — one of date, time, datetime	date	Optional
inline	inline, markup only	Draw the record-detail variant instead of the boxed form control: no box, an accent underline, inheriting the surrounding type. The label and the message are hidden.	boolean	false	Optional

Events

Name	When it fires	What it carries
input	As the date is edited, after the value attribute has been written back.	nothing
change	When a complete date is committed — picked from the calendar, or typed and left.	nothing

Slots

Nothing goes inside this piece.

Styling hooks

Design token	What it controls
--caos-font	The typeface of the label, the control and the message.
--caos-text-body	The size of the label and of the date.
--caos-space-1	The gap between the label, the control and the message.
--caos-space-3	The vertical padding inside the control.
--caos-radius	The corner radius of the control.
--caos-color-border	The outline at rest.
--caos-color-border-strong	The outline while the control has focus.
--caos-color-surface-2	The fill of the control.
--caos-color-text	The colour of the date.
--caos-color-text-muted	The label, the empty format hint, the message and disabled text.
--caos-color-accent	The hover outline, and the underline of the inline variant.
--caos-accent-wash	The tint that fills the control while it has focus, in place of a focus ring.
--caos-color-danger	The required asterisk, and the outline and message when invalid.

Methods

Name	Description	Arguments
focus()	Focus the control, on its first date segment. The shared implementation also tries to select the text; a date input does not support selection, and the attempt is swallowed rather than thrown.	options: FocusOptions

Readable state

Nothing on this piece can be read back.

Styling parts

Part	Which piece of it	When it is there
::part(label)	the label above the control	Always
::part(input)	the inner date input	Always
::part(message)	the line under the control	Always

When to use it

A calendar date, where the person is better served by a calendar than by typing. If the value carries a time of day as well, this control cannot hold it — see the note below.

What to use instead

• FieldRenderer — The type is not known until the record is read — hand it the field metadata and it draws the right control.
• TextField — The value is a period rather than a day — “Q3 2026”, “week 14” — which a calendar cannot express.
• NumberField — It is a duration or an age rather than a point on the calendar.
• PicklistField — Only a handful of specific dates are on offer, and the calendar is more choice than the person has.

Accessibility

The control is a real date input with a generated id and a label pointing at it, so it is announced with its name, clicking the label focuses it, and everything the platform gives a date input comes with it: segment-by-segment keyboard entry, up/down stepping, and the calendar opened from the keyboard. required and invalid are forwarded as required and aria-invalid. What is left to the author is the label, and the message — a person using the keyboard cannot see that a day is greyed out.

Examples

A date on a form

The plain case: a labelled calendar date already filled in.

{
  "id": "example",
  "section": "A date on a form",
  "columns": 1,
  "items": [
    {
      "id": "date_field_1",
      "type": "component",
      "key": "date_field",
      "inputs": {
        "label": "Due date",
        "value": "2026-09-15"
      }
    }
  ]
}

<caos-date-field label="Due date" value="2026-09-15"></caos-date-field>

Bounded to a window

The same field with only one quarter selectable — the calendar greys everything outside the bounds, and the message says in words what the greying means.

{
  "id": "example",
  "section": "Bounded to a window",
  "columns": 1,
  "items": [
    {
      "id": "date_field_1",
      "type": "component",
      "key": "date_field",
      "inputs": {
        "label": "Due date",
        "value": "2026-09-15",
        "min": "2026-07-01",
        "max": "2026-09-30",
        "message": "Dates in the current quarter only."
      }
    }
  ]
}

<caos-date-field label="Due date" value="2026-09-15" min="2026-07-01" max="2026-09-30" message="Dates in the current quarter only."></caos-date-field>