Common incorrect uses of <mds-calendar>. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in agents/anti-patterns.md - they apply here too but are not repeated.

Do Not Toggle Single Mode with a Quoted Boolean String

singlePicker is a boolean prop that defaults to false. The component reads the string "false" as false, but the prop is not reflected, so single-picker="false" stays in the DOM and attribute selectors (mds-calendar[single-picker]) and any code reading the attribute still see it set. Use the bare attribute for single mode and omit it for the default range mode; toggle it at runtime by adding/removing the attribute or setting the property in JavaScript.

<!-- INCORRECT -->
<mds-calendar single-picker="false"></mds-calendar>

<!-- CORRECT -->
<mds-calendar></mds-calendar>
<mds-calendar id="cal" single-picker></mds-calendar>
<script>
  document.querySelector('#cal').singlePicker = false; // back to range mode
</script>

Do Not Set end-date When single-picker Is Set

When singlePicker is set, the component rejects endDate with a console warning and clears it internally. Setting both single-picker and end-date is contradictory and produces no visible selection for the end date.

<!-- INCORRECT -->
<mds-calendar single-picker start-date="2025-06-01" end-date="2025-06-15"></mds-calendar>

<!-- CORRECT -->
<mds-calendar single-picker start-date="2025-06-01"></mds-calendar>

Do Not Provide startDate After endDate

Dates must be chronologically ordered: startDate must precede endDate. The component does not reorder them: set at load, the two ends are marked with no range between them; changed later, it only logs a console warning. Always ensure start-date <= end-date.

<!-- INCORRECT -->
<mds-calendar start-date="2025-12-31" end-date="2025-12-01"></mds-calendar>

<!-- CORRECT -->
<mds-calendar start-date="2025-12-01" end-date="2025-12-31"></mds-calendar>

Do Not Listen for the Native change Event

<mds-calendar> does not bubble a native change event from inside its Shadow DOM. Use the documented mdsCalendarChange custom event so the handler reliably receives the structured { startDate, endDate? } payload.

<!-- INCORRECT -->
<mds-calendar id="cal"></mds-calendar>
<script>
  document.querySelector('#cal').addEventListener('change', (e) => {
    console.log(e.target.value); // undefined - wrong event
  });
</script>

<!-- CORRECT -->
<mds-calendar id="cal"></mds-calendar>
<script>
  document.querySelector('#cal').addEventListener('mdsCalendarChange', (e) => {
    console.log(e.detail.startDate, e.detail.endDate);
  });
</script>

Do Not Use <mds-calendar> as a Drop-In Replacement for mds-input-date

<mds-calendar> is not form-associated and emits no name/value pair for form submission. When you need a date picker tied to a form field, use mds-input-date (single date) or mds-input-date-range (range) instead.

<!-- INCORRECT -->
<form action="/prenota" method="post">
  <mds-calendar name="check-in" single-picker></mds-calendar>
  <mds-button type="submit" label="Prenota"></mds-button>
</form>

<!-- CORRECT -->
<form action="/prenota" method="post">
  <mds-input-field label="Data di arrivo">
    <mds-input-date name="check-in"></mds-input-date>
  </mds-input-field>
  <mds-button type="submit" label="Prenota"></mds-button>
</form>

Do Not Style Internals via Undocumented ::part() Selectors

The only supported customization surface is the set of --mds-calendar-* CSS custom properties. Targeting shadow-DOM internals with ::part() selectors that are not in the documentation couples your code to the implementation and will break on minor releases.

/* INCORRECT */
mds-calendar::part(nav) {
  background: red;
}
mds-calendar::part(cell) {
  border: 1px solid blue;
}

/* CORRECT */
mds-calendar {
  --mds-calendar-background: rgb(var(--magma-surface-muted));
  --mds-calendar-border-radius: var(--magma-radius-xl);
  --mds-calendar-cell-other-month-visibility: hidden;
}