Correct and idiomatic ways to use the <mds-input-date> component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant ladder documented in agents/variants.md and the shared component rules in agents/conventions.md.

Basic Date Input

The simplest form. Wrap in mds-input-field to attach a visible label. Use name so the value is submitted with the form.

<mds-input-field label="Data di nascita">
  <mds-input-date name="birthdate"></mds-input-date>
</mds-input-field>

Pre-filled Value

Set value to an ISO date string (YYYY-MM-DD) to initialize the picker with a known date. Do not use other date formats.

<mds-input-date name="dataScadenza" value="2026-12-31"></mds-input-date>

Required Field

Add required to make an empty or invalid date fail validation. The component surfaces a tip on focus; the field stops the submit while empty, and turns to 'error' once the user leaves it empty or a stopped submit points at it, until a valid date is entered.

<mds-input-field label="Data di inizio *">
  <mds-input-date name="startDate" required></mds-input-date>
</mds-input-field>

Bounded Date Range

Use min and max (both ISO strings) to restrict the selectable range. Dates outside the range invalidate the field and, once it is touched, emit mdsInputValidation with false. If max is earlier than min at load time, the component snaps max to equal min.

<mds-input-date
  name="dataSopralluogo"
  min="2026-01-01"
  max="2026-12-31"
></mds-input-date>

Listening to Value Changes

Listen to mdsInputDateSelect (fires with the new ISO string) for every value change - whether typed or picked from the calendar. Listen to mdsInputValidation to react to validity changes.

<mds-input-date id="picker" name="dataEvento"></mds-input-date>

<script>
  const picker = document.getElementById('picker');

  picker.addEventListener('mdsInputDateSelect', (e) => {
    console.log('Data selezionata:', e.detail); // "2026-06-15"
  });

  picker.addEventListener('mdsInputValidation', (e) => {
    console.log('Valido:', e.detail); // true | false
  });
</script>

Programmatic Value via setValue

Use the setValue method to set the value from JavaScript; it emits mdsInputDateSelect and checks the value. Unlike a user interaction it does not touch the field: on a pristine field the validity reaches the form, but the variant and mdsInputValidation wait for the user.

<mds-input-date id="datePicker" name="dataConsegna"></mds-input-date>

<script>
  document.getElementById('datePicker').setValue('2026-09-01');
</script>

Controlling Calendar Auto-close Delay

The calendar dropdown closes delay milliseconds after a date is picked (default 500 ms). Set delay="0" to keep it open after selection - useful when the picker is used inside a form where the user might want to confirm before the overlay disappears.

<!-- Default: closes 500 ms after pick -->
<mds-input-date name="dataRiunione" delay="500"></mds-input-date>

<!-- Keep open until the user dismisses manually -->
<mds-input-date name="dataRiunione" delay="0"></mds-input-date>

Disabled and Read-only States

disabled blocks all interaction and removes the field from the tab sequence. readonly keeps the field in the tab sequence and selects its text on focus, but the date cannot be changed: the native input is read-only and the calendar button disabled. Both surface a contextual tip.

<!-- Disabled: no interaction at all -->
<mds-input-date name="dataArchiviazione" disabled value="2025-01-01"></mds-input-date>

<!-- Read-only: focusable, not editable -->
<mds-input-date name="dataCreazione" readonly value="2024-06-01"></mds-input-date>

Form Participation

<mds-input-date> is form-associated and submits its ISO value under name. A missing required date, or one out of the min/max range, stops the submit like a native control. A form reset brings back the date of load, both shown and submitted.

<form action="/prenota" method="post">
  <mds-input-field label="Data prenotazione">
    <mds-input-date name="bookingDate" required></mds-input-date>
  </mds-input-field>
  <mds-button type="submit" label="Conferma" variant="primary" tone="strong"></mds-button>
</form>

Slotted Mode Inside a Compound Field

When the host carries a slot attribute, the component renders only the bare native input - the calendar button, dropdown, and calendar are suppressed. This is the correct way to embed the date input inside mds-input-date-range or a custom compound field.

<mds-input-date-range>
  <mds-input-date slot="start" name="rangeStart"></mds-input-date>
  <mds-input-date slot="end" name="rangeEnd"></mds-input-date>
</mds-input-date-range>

Variant Override for External State Signalling

variant is driven automatically by validation ('error' on invalid, 'primary' on valid) once the field is touched. To communicate an external state, write it in the markup or set it from script: it lasts until the user edits or leaves the field. Values follow the theme input ladder: primary (default), error, success, warning, info, ai.

<mds-input-date id="dataConferma" name="dataConferma" value="2026-03-15"></mds-input-date>

<script>
  // Pre-mark as success when the date was already validated server-side
  const field = document.getElementById('dataConferma');
  field.componentOnReady().then(() => {
    field.variant = 'success';
  });
</script>

Styling Customization

Style the component only through its documented --mds-input-date-* CSS custom properties. Use the semantic color roles via rgb(var(--magma-<role>)) so dark mode and high-contrast work automatically.

.booking-widget mds-input-date {
  --mds-input-date-background: rgb(var(--magma-wash-base));
  --mds-input-date-icon-color: rgb(var(--magma-accent-fg));
  --mds-input-date-ring: 0 0 0 2px rgb(var(--magma-border-focus) / 0.5);
}