# Date

**`sonic-date`** formats a date or a date range with `Intl.DateTimeFormat`. Pass a Unix timestamp in seconds (`date`) or a parsable string (`date_string`), add `end_date` for a range, and tune each part (`weekday` · `month` · `hour` …) with attributes. With no date and no `now`, it renders nothing.

## Basic example

`date` is in **seconds**, not milliseconds. `date_string` accepts anything `new Date()` parses: prefer ISO 8601 with an explicit offset. `now` shows the current date.

<sonic-code>
  <template>
    <div class="grid gap-2">
      <div>Departure: <sonic-date date="1781514000" language="en"></sonic-date></div>
      <div>Arrival: <sonic-date date_string="2026-06-15T12:45:00Z" language="en"></sonic-date></div>
      <div>Now: <sonic-date now language="en"></sonic-date></div>
    </div>
  </template>
</sonic-code>

## Date range

Set `start_date` and `end_date` (or their `_string` variants). On two different days, only the dates are shown, with the "from … to …" wording. On the same day, the hours are kept. `hide_hours` drops them anyway.

Without a start, the range starts now. If the end is before the start, the two are swapped.

<sonic-code>
  <template>
    <div class="grid gap-2">
      <sonic-date start_date_string="2026-06-15T09:00:00Z" end_date_string="2026-06-22T18:00:00Z" language="en" wording_billet_periode_validite="From %s to %s"></sonic-date>
      <sonic-date start_date_string="2026-06-15T09:00:00Z" end_date_string="2026-06-15T12:45:00Z" language="en"></sonic-date>
      <sonic-date start_date_string="2026-06-15T09:00:00Z" end_date_string="2026-06-15T12:45:00Z" language="en" hide_hours></sonic-date>
    </div>
  </template>
</sonic-code>

## Range wording

`wording_billet_periode_validite` holds the range wording, with one `%s` per date. It defaults to the French `Du %s au %s`, whatever the language: **set it for every non-French page**.

<sonic-code>
  <template>
    <sonic-date start_date_string="2026-06-15" end_date_string="2026-06-22" language="en" wording_billet_periode_validite="Valid from %s until %s"></sonic-date>
  </template>
</sonic-code>

## Format options

Defaults: `weekday="short"` · `day="2-digit"` · `month="short"` · `year="numeric"` · `hour="2-digit"` · `minute="2-digit"`, 24-hour clock, no era. `hidden` removes a part.

<sonic-code>
  <template>
    <div class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1 text-sm">
      <code>default</code><sonic-date date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>weekday="long"</code><sonic-date weekday="long" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>weekday="narrow"</code><sonic-date weekday="narrow" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>weekday="hidden"</code><sonic-date weekday="hidden" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>day="numeric"</code><sonic-date day="numeric" date_string="2026-06-05T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>month="long"</code><sonic-date month="long" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>month="narrow"</code><sonic-date month="narrow" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>month="numeric"</code><sonic-date month="numeric" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>month="2-digit"</code><sonic-date month="2-digit" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>year="2-digit"</code><sonic-date year="2-digit" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>hour="numeric"</code><sonic-date hour="numeric" date_string="2026-06-15T07:05:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>hour12</code><sonic-date hour12 date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>hour="hidden" minute="hidden"</code><sonic-date hour="hidden" minute="hidden" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
      <code>era="short"</code><sonic-date era="short" date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" language="en"></sonic-date>
    </div>
  </template>
</sonic-code>

## Language

With no `language`, the component follows `<html lang>` and updates when it changes. Pass a BCP 47 tag to force one.

<sonic-code>
  <template>
    <div class="grid grid-cols-[auto_1fr] gap-x-4 gap-y-1 text-sm">
      <code>en</code><sonic-date language="en" date_string="2026-06-15T09:00:00Z"></sonic-date>
      <code>fr</code><sonic-date language="fr" date_string="2026-06-15T09:00:00Z"></sonic-date>
      <code>ja</code><sonic-date language="ja" date_string="2026-06-15T09:00:00Z"></sonic-date>
    </div>
  </template>
</sonic-code>

## Time zone

With no `time_zone`, dates use the browser time zone. Pass an IANA name (`Intl.supportedValuesOf("timeZone")` lists them) to show local airport time.

<sonic-code>
  <template>
    <div class="grid gap-2">
      <div>CN 001 departs CDG at <sonic-date date_string="2026-06-15T09:00:00Z" time_zone="Europe/Paris" weekday="hidden" language="en"></sonic-date> (Paris)</div>
      <div>and lands at JFK at <sonic-date date_string="2026-06-15T12:45:00Z" time_zone="America/New_York" weekday="hidden" language="en"></sonic-date> (New York)</div>
    </div>
  </template>
</sonic-code>

## Custom parts

A child `<template data-value="<part>">` wraps a part in your own markup: `weekday` · `day` · `month` · `year` · `hour` · `minute` · `literal`, plus `from` and `to` in ranges. An empty element receives the part value; a non-empty one replaces it. `designMode` drops the leading "from" word and the commas, for stacked layouts. Add `noShadowDom` so page styles reach the parts.

<sonic-code>
  <template>
    <div class="relative max-w-sm rounded-lg overflow-hidden">
      <sonic-date
        designMode
        noShadowDom
        start_date_string="2026-06-15"
        end_date_string="2026-06-22"
        language="en"
        wording_billet_periode_validite="From %s to %s"
        class="absolute top-0 left-0 z-10 p-4 text-center text-sm text-white drop-shadow-lg"
      >
        <template data-value="weekday"><span class="hidden"></span></template>
        <template data-value="day"><span class="block text-4xl font-bold leading-none"></span></template>
        <template data-value="month"><span class="block text-xl font-bold uppercase leading-tight"></span></template>
        <template data-value="year"><span class="block text-lg font-bold leading-tight"></span></template>
        <template data-value="to"><span class="block my-1 text-3xl leading-none">↓</span></template>
      </sonic-date>
      <sonic-image src="/img/concorde/plane_03.jpg" alt="Concorde specifications board" ratio="1/1" cover></sonic-image>
    </div>
  </template>
</sonic-code>

## API reference

| Attribute | Values | Description |
|-----------|--------|-------------|
| `date` | number | Unix timestamp in seconds |
| `date_string` | string | Date parsed with `new Date()`. Overrides `date` |
| `start_date` / `start_date_string` | number / string | Range start. Overrides `date` |
| `end_date` / `end_date_string` | number / string | Range end. Swapped with the start when earlier |
| `now` | boolean | Uses the current date when no start is set |
| `hide_hours` | boolean | Hides hours and minutes in a same-day range |
| `weekday` | `narrow` · `short` · `long` · `hidden` (default `short`) | Weekday format |
| `day` | `numeric` · `2-digit` (default `2-digit`) | Day format |
| `month` | `numeric` · `2-digit` · `narrow` · `short` · `long` (default `short`) | Month format |
| `year` | `numeric` · `2-digit` (default `numeric`) | Year format |
| `hour` | `numeric` · `2-digit` · `hidden` (default `2-digit`) | Hour format |
| `minute` | `numeric` · `2-digit` · `hidden` (default `2-digit`) | Minute format |
| `hour12` | boolean | 12-hour clock. Default is 24-hour |
| `era` | `narrow` · `short` · `long` | Shows the era. Hidden by default |
| `language` | BCP 47 tag | Locale. Defaults to `<html lang>` |
| `time_zone` | IANA name | Time zone. Defaults to the browser one |
| `wording_billet_periode_validite` | string with two `%s` (default `Du %s au %s`) | Wording of a multi-day range |
| `designMode` | boolean | Removes the "from" word and commas |
| `noShadowDom` | boolean | Renders in light DOM so page styles apply to the parts |
| `templates` | `HTMLTemplateElement[]` (property) | Part templates, instead of child `<template>` elements |
| `renderIf` | boolean | Deprecated: wrap the date in [sonic-if](/core/components/functional/if) instead |

No slots. Child `<template data-value>` elements customise the parts.