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

Minimal Range Picker

The canonical form. Slot one mds-input-date as start and another as end; the host wires them together, drives the shared calendar, and handles range validation automatically.

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

Pre-filling the Range

Use the start-date and end-date attributes to set an initial selection. Both expect ISO YYYY-MM-DD strings. Changing them later re-syncs the slotted inputs and the calendar automatically.

<mds-input-date-range start-date="2026-01-01" end-date="2026-01-31">
  <mds-input-date slot="start"></mds-input-date>
  <mds-input-date slot="end"></mds-input-date>
</mds-input-date-range>

Constraining the Selectable Window

Use min and max to block out-of-window dates in the calendar. Both are ISO YYYY-MM-DD strings. The host passes them to the slotted fields too: a date typed out of the window turns its field to error, stops the submit of the form and is not emitted as a range.

<mds-input-date-range min="2026-01-01" max="2026-12-31">
  <mds-input-date slot="start"></mds-input-date>
  <mds-input-date slot="end"></mds-input-date>
</mds-input-date-range>

Listening to Range Events

mdsInputDateRangeValueChange fires when a full, valid range is committed (calendar pick, preset, or focus-out with two valid dates) and either bound actually changed since the last emit. It delivers { startDate, endDate } in event.detail.

<mds-input-date-range id="periodo">
  <mds-input-date slot="start"></mds-input-date>
  <mds-input-date slot="end"></mds-input-date>
</mds-input-date-range>

<script>
  document.querySelector('#periodo').addEventListener('mdsInputDateRangeValueChange', (e) => {
    console.log('Intervallo selezionato:', e.detail.startDate, '-', e.detail.endDate);
  });
</script>

Form Participation

<mds-input-date-range> is form-associated. Add name and place it inside a <form>; the submitted value is a JSON string { startDate, endDate }. An empty range submits no value. Form reset restores the dates set at first load.

<form action="/filtra" method="get">
  <mds-input-date-range name="periodo" start-date="2026-01-01" end-date="2026-01-31">
    <mds-input-date slot="start"></mds-input-date>
    <mds-input-date slot="end"></mds-input-date>
  </mds-input-date-range>
  <mds-button type="submit" label="Applica filtro" variant="primary" tone="strong"></mds-button>
  <mds-button type="reset" label="Reimposta" variant="dark" tone="outline"></mds-button>
</form>

Quick-Pick Preselections

Slot one or more mds-input-date-range-preselection elements into the component. They appear inside the calendar dropdown and act as one-click range shortcuts. The host marks the matching preset as selected, from load on and whenever the range changes to match it. A preset whose end comes before its start applies its start as both ends.

<mds-input-date-range>
  <mds-input-date slot="start"></mds-input-date>
  <mds-input-date slot="end"></mds-input-date>
  <mds-input-date-range-preselection start="2026-06-02" end="2026-06-08">
    Questa settimana
  </mds-input-date-range-preselection>
  <mds-input-date-range-preselection start="2026-06-01" end="2026-06-30">
    Questo mese
  </mds-input-date-range-preselection>
</mds-input-date-range>

Controlling the Auto-Close Delay

By default the calendar closes 500 ms after a complete range is picked. Set delay="0" to keep it open until the user dismisses it manually, or increase the value for a longer grace period.

<!-- Keep the calendar open after selection -->
<mds-input-date-range delay="0">
  <mds-input-date slot="start"></mds-input-date>
  <mds-input-date slot="end"></mds-input-date>
</mds-input-date-range>

<!-- Longer grace period: 1 second -->
<mds-input-date-range delay="1000">
  <mds-input-date slot="start"></mds-input-date>
  <mds-input-date slot="end"></mds-input-date>
</mds-input-date-range>

Styling Customization

Style the component only through its documented --mds-input-date-range-* CSS custom properties. Set them on the host or a parent selector; use the semantic color roles via rgb(var(--magma-<role>)) (agents/color.md) so dark mode and themes keep working.

.filtro-avanzato mds-input-date-range {
  --mds-input-date-range-background: rgb(var(--magma-surface-sunken));
  --mds-input-date-range-icon-color: rgb(var(--magma-accent-fg));
  --mds-input-date-range-fields-gap: 0 calc(var(--spacing) * 400);
}