Skip to content

Calendar

Lab Available in release assets

Evaluate a bounded progressive calendar surface while retaining the native date input and ordinary server request as the canonical, locale-aware path.

Calendar primary example

Show code
<section class="thin-calendar" aria-labelledby="calendar-title">
  <h2 id="calendar-title">Choose a report date</h2>
  <form action="/reports" method="get">
    <label for="report-date">Date</label>
    <input class="thin-input" id="report-date" name="date" type="date" min="2026-08-01" max="2026-08-31" required />
    <small>Dates use your locale; the server interprets this as America/Chicago.</small>
    <button class="thin-button">Continue</button>
  </form>
  <details>
    <summary>Open experimental calendar surface</summary>
    <div role="group" aria-label="August 2026 calendar">
      <p><a href="?date=2026-08-14">Friday, August 14</a></p>
      <p><span aria-disabled="true">Saturday, August 15 unavailable</span></p>
      <p><a href="?date=2026-08-16">Sunday, August 16</a></p>
    </div>
  </details>
</section>

Each authored example uses the production assets and includes copyable markup.

Native date form

The labelled native field is canonical. Its GET query has a real documentation destination; an integrating server owns date availability.

Show code
<section class="thin-calendar"  style="min-inline-size: 0; overflow-wrap: anywhere">
  <form action="/components/forms-and-controls/calendar/" method="get">
    <label for="native-date">Report date</label>
    <input id="native-date" name="date" type="date" min="2026-08-01" max="2026-08-31" value="2026-08-14" required aria-describedby="native-date-help"  style="box-sizing: border-box; inline-size: 100%; min-inline-size: 0">
    <p id="native-date-help">Choose August 1–31, 2026. The report uses America/Chicago calendar dates. Availability is checked by your server.</p>
    <button style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Show date in documentation URL</button>
  </form>
  <p>This demonstration sends a GET query to this documentation page; it does not reserve a date.</p>
</section>

A declarative native popover adds ordinary date links. Keyboard navigation reaches them (Option+Tab in Safari when Tab is restricted by system settings) and Escape returns to the invoker; this is a bounded Lab surface, without a composite calendar grid.

Show code
<section class="thin-calendar"  style="min-inline-size: 0; overflow-wrap: anywhere">
  <form action="/components/forms-and-controls/calendar/" method="get">
    <label for="single-date">Report date</label>
    <input id="single-date" name="date" type="date" min="2026-08-01" max="2026-08-31" value="2026-08-14" required aria-describedby="single-date-help"  style="box-sizing: border-box; inline-size: 100%; min-inline-size: 0">
    <p id="single-date-help">Choose August 1–31, 2026. The report uses America/Chicago calendar dates. Availability is checked by your server.</p>
    <button style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Show date in documentation URL</button>
  </form>
  <p>This demonstration sends a GET query to this documentation page; it does not reserve a date.</p>
  <button type="button" popovertarget="single-surface" style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Open date links</button>
  <div id="single-surface" popover="auto" role="group" aria-label="August date links" style="box-sizing: border-box; max-inline-size: calc(100% - 2rem); overflow-wrap: anywhere; padding: 1rem">
    <p>Server-authored sample availability.</p>
    <ul>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-14">Friday, August 14</a></li>
      <li><span aria-disabled="true">Saturday, August 15 unavailable</span></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-16">Sunday, August 16</a></li>
    </ul>
    <button type="button" popovertarget="single-surface" popovertargetaction="hide" style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Close date links</button>
  </div>
</section>

Server-authored week starts

Two explicit English locale examples order a real August 2026 week differently. The application supplies locale and week start; the component does not infer scheduling rules.

Show code
<section class="thin-calendar"  style="min-inline-size: 0; overflow-wrap: anywhere">
  <form action="/components/forms-and-controls/calendar/" method="get">
    <label for="locale-date">Report date</label>
    <input id="locale-date" name="date" type="date" min="2026-08-01" max="2026-08-31" value="2026-08-14" required aria-describedby="locale-date-help"  style="box-sizing: border-box; inline-size: 100%; min-inline-size: 0">
    <p id="locale-date-help">Choose August 1–31, 2026. The report uses America/Chicago calendar dates. Availability is checked by your server.</p>
    <button style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Show date in documentation URL</button>
  </form>
  <p>This demonstration sends a GET query to this documentation page; it does not reserve a date.</p>
  <section lang="en-GB">
    <h3>en-GB: Monday first</h3>
    <ol>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-03">Monday, August 3</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-04">Tuesday, August 4</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-05">Wednesday, August 5</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-06">Thursday, August 6</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-07">Friday, August 7</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-08">Saturday, August 8</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-09">Sunday, August 9</a></li>
    </ol>
  </section>
  <section lang="en-US">
    <h3>en-US: Sunday first</h3>
    <ol>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-02">Sunday, August 2</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-03">Monday, August 3</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-04">Tuesday, August 4</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-05">Wednesday, August 5</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-06">Thursday, August 6</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-07">Friday, August 7</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-08">Saturday, August 8</a></li>
    </ol>
  </section>
</section>

Anatomy

  • Native date form
  • Explicit server timezone guidance
  • Optional disclosure
  • Durable date links
  • Disabled-date text

Variants and sizes

  • Native only — shown above
  • Single-date experimental surface — shown above
  • Locale-specific week start — shown above

Rendered fixtures exercise authored content and constrained layouts with the same production assets.

Native keyboard path and focus return

Use the native date control and ordinary Tab order. Open date links, Tab to a date (Option+Tab in Safari when its keyboard setting restricts Tab), and press Escape to return focus. The same controls work without JavaScript in browsers supporting declarative popovers; the form remains available elsewhere. Native picker UI varies by browser and needs human review.

Show code
<section class="thin-calendar"  style="min-inline-size: 0; overflow-wrap: anywhere">
  <form action="/components/forms-and-controls/calendar/" method="get">
    <label for="keyboard-date">Report date</label>
    <input id="keyboard-date" name="date" type="date" min="2026-08-01" max="2026-08-31" value="2026-08-14" required aria-describedby="keyboard-date-help"  style="box-sizing: border-box; inline-size: 100%; min-inline-size: 0">
    <p id="keyboard-date-help">Choose August 1–31, 2026. The report uses America/Chicago calendar dates. Availability is checked by your server.</p>
    <button style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Show date in documentation URL</button>
  </form>
  <p>This demonstration sends a GET query to this documentation page; it does not reserve a date.</p>
  <button type="button" popovertarget="keyboard-surface" style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Open date links</button>
  <div id="keyboard-surface" popover="auto" role="group" aria-label="August date links" style="box-sizing: border-box; max-inline-size: calc(100% - 2rem); overflow-wrap: anywhere; padding: 1rem">
    <p>Server-authored sample availability.</p>
    <ul>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-14">Friday, August 14</a></li>
      <li><span aria-disabled="true">Saturday, August 15 unavailable</span></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-16">Sunday, August 16</a></li>
    </ul>
    <button type="button" popovertarget="keyboard-surface" popovertargetaction="hide" style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Close date links</button>
  </div>
</section>

Bounds and unavailable date

Native min/max enforce the August range. HTML date inputs cannot exclude a single in-range day: the unavailable date is nonlinked text and a real application must also validate submissions on the server.

Show code
<section class="thin-calendar"  style="min-inline-size: 0; overflow-wrap: anywhere">
  <form action="/components/forms-and-controls/calendar/" method="get">
    <label for="bounds-date">Report date</label>
    <input id="bounds-date" name="date" type="date" min="2026-08-01" max="2026-08-31" value="2026-08-14" required aria-describedby="bounds-date-help"  style="box-sizing: border-box; inline-size: 100%; min-inline-size: 0">
    <p id="bounds-date-help">Choose August 1–31, 2026. The report uses America/Chicago calendar dates. Availability is checked by your server.</p>
    <button style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Show date in documentation URL</button>
  </form>
  <p>This demonstration sends a GET query to this documentation page; it does not reserve a date.</p>
  <ul>
    <li><a href="/components/forms-and-controls/calendar/?date=2026-08-14">Friday, August 14</a></li>
    <li><span aria-disabled="true">Saturday, August 15 unavailable</span></li>
    <li><a href="/components/forms-and-controls/calendar/?date=2026-08-16">Sunday, August 16</a></li>
  </ul>
</section>

Server validation response

An authored response snapshot retains the submitted value and links a persistent error to the canonical field. It does not simulate a server deciding availability.

Show code
<section class="thin-calendar"  style="min-inline-size: 0; overflow-wrap: anywhere">
  <form action="/components/forms-and-controls/calendar/" method="get">
    <label for="error-date">Report date</label>
    <input id="error-date" name="date" type="date" min="2026-08-01" max="2026-08-31" value="2026-08-15" required aria-describedby="error-date-help error-date-error" aria-invalid="true" style="box-sizing: border-box; inline-size: 100%; min-inline-size: 0">
    <p id="error-date-help">Choose August 1–31, 2026. The report uses America/Chicago calendar dates. Availability is checked by your server.</p>
    <p id="error-date-error">August 15 is unavailable. Choose another date.</p>
    <button style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Show date in documentation URL</button>
  </form>
  <p>This demonstration sends a GET query to this documentation page; it does not reserve a date.</p>
</section>

Locale and date boundary

The ISO field value is a calendar date, not a JavaScript timestamp. Retain 2026-08-01 across browser timezones and let the report server interpret it in America/Chicago. Week labels and start order are explicitly authored.

Show code
<section class="thin-calendar"  style="min-inline-size: 0; overflow-wrap: anywhere">
  <form action="/components/forms-and-controls/calendar/" method="get">
    <label for="boundary-date">Report date</label>
    <input id="boundary-date" name="date" type="date" min="2026-08-01" max="2026-08-31" value="2026-08-01" required aria-describedby="boundary-date-help"  style="box-sizing: border-box; inline-size: 100%; min-inline-size: 0">
    <p id="boundary-date-help">Choose August 1–31, 2026. The report uses America/Chicago calendar dates. Availability is checked by your server.</p>
    <button style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Show date in documentation URL</button>
  </form>
  <p>This demonstration sends a GET query to this documentation page; it does not reserve a date.</p>
  <section lang="en-GB">
    <h3>en-GB: Monday first</h3>
    <ol>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-03">Monday, August 3</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-04">Tuesday, August 4</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-05">Wednesday, August 5</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-06">Thursday, August 6</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-07">Friday, August 7</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-08">Saturday, August 8</a></li>
      <li><a href="/components/forms-and-controls/calendar/?date=2026-08-09">Sunday, August 9</a></li>
    </ol>
  </section>
</section>

Application-owned form replacement

Edit the date, then refresh this sample form. The small application handler carries its value across HTML replacement and deliberately restores focus to the field. Calendar has no reconnect coordinator; a server-morph integration owns this work.

Show code
<section class="thin-calendar"  style="min-inline-size: 0; overflow-wrap: anywhere">
  <div id="replace-form">
    <form action="/components/forms-and-controls/calendar/" method="get">
      <label for="replace-date">Report date</label>
      <input id="replace-date" name="date" type="date" min="2026-08-01" max="2026-08-31" value="2026-08-14" required aria-describedby="replace-date-help"  style="box-sizing: border-box; inline-size: 100%; min-inline-size: 0">
      <p id="replace-date-help">Choose August 1–31, 2026. The report uses America/Chicago calendar dates. Availability is checked by your server.</p>
      <button style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Show date in documentation URL</button>
    </form>
    <p>This demonstration sends a GET query to this documentation page; it does not reserve a date.</p>
  </div>
  <button type="button" id="refresh-form" style="box-sizing: border-box; max-inline-size: 100%; white-space: normal; overflow-wrap: anywhere">Refresh sample form</button>
  <p id="refresh-result" role="status"></p>
  <script type="module">document.getElementById("refresh-form").addEventListener("click", () => { const container = document.getElementById("replace-form"); const input = container.querySelector("input"); const replacement = container.cloneNode(true); replacement.querySelector("input").setAttribute("value", input.value); container.replaceWith(replacement); replacement.querySelector("input").focus(); document.getElementById("refresh-result").textContent = "Sample form replaced; date retained."; });</script>
</section>
  • No JavaScript — shown above
  • Keyboard navigation — shown above
  • Focus return — shown above
  • Disabled date — shown above
  • Range guidance — shown above
  • Server validation error — shown above
  • Locale and week start — shown above
  • Timezone boundary — shown above
  • Reconnect after morph — shown above

Interaction and keyboard behavior

The native input submits normally. Any experimental surface must mirror server-authored dates, preserve keyboard and focus behavior, and refresh after morph; it never invents availability, ranges, or scheduling rules.

Accessibility

Keep the native input labelled and available, state timezone assumptions, expose disabled dates in text, preserve logical focus, and return server validation beside the canonical field.

Contract
NATIVE
Basis
Native date input and links/disclosure; no APG Grid claim while the fixture remains a link-based calendar
Evidence
  • tests/unit/library/calendar.test.ts

API

Use section.thin-calendar around a native input[type=date] form. Optional calendar markup is progressive evidence only and remains Lab.

Behavior tier: dependency-free

Structured host, property, and example tables are not authored for this item yet. Use the summary above and the primary example.

Fallback

The native date input, constraints, guidance, and ordinary form submission remain complete without the experimental surface.

Assets and dependencies

  • /foundation.css
  • /labs.css

Dependencies: None

Source: packages/ui/src/items/calendar/style.ts

Composition

Derived from the examples and style specs, not authored.

Composes