skip to content

A Berlin car-rental page posts the date chosen in an Angular Material datepicker using the native adapter, and the server stores the day before; why, and how does the Luxon adapter fix it?

level: seniorimportance: should knowfreq 31%

answer

  1. a calendar day is not an instant
  2. local midnight meets UTC serialisation
  3. the shift runs both ways
  4. send the date, not the timestamp
  5. Luxon adapter options token

basics

~20 s

The native adapter creates local-midnight Date values and JSON serialisation converts them to UTC, so 12 October in Berlin is sent as 2026-10-11T22:00Z. With Luxon, send toISODate(), or set useUtc or, since 22.2, a timeZone in MAT_LUXON_DATE_ADAPTER_OPTIONS.

solid answer

~50 s

`NativeDateAdapter` builds every date at local midnight, so picking 12 October in Berlin (UTC+2 in October) gives an instant that is 22:00 UTC on 11 October. `HttpClient` serialises the body with `JSON.stringify`, which calls `toISOString()`, so the server receives `2026-10-11T22:00:00.000Z`, and a backend that keeps the date part stores the 11th. It bites on the way in too: the native adapter deserialises a date-only `2026-10-12` with `new Date(value)`, which is UTC midnight, so users west of UTC see the 11th. With the Luxon adapter the value is a `DateTime`, so you send the calendar date itself with `toISODate()`, and date-only strings deserialise in the adapter's zone. `MAT_LUXON_DATE_ADAPTER_OPTIONS` adds `useUtc: true`, which creates picked dates at UTC midnight, or, since 22.2.0, `timeZone: 'Europe/Berlin'`, which creates them in the branch's zone whatever the browser's. Setting both throws.

code

ts · 16 lines
ts
import {HttpClient} from '@angular/common/http';
import {inject, Injectable} from '@angular/core';
import {DateTime} from 'luxon';

@Injectable({providedIn: 'root'})
export class ReservationApi {
  private readonly http = inject(HttpClient);

  book(pickUp: DateTime, returnDate: DateTime) {
    // Send calendar days, not instants: "2026-10-12", never "...T22:00:00.000Z"
    return this.http.post('/api/reservations', {
      pickUp: pickUp.toISODate(),
      returnDate: returnDate.toISODate(),
    });
  }
}

go deeper

for a junior

Recall that a JavaScript Date is an instant, so a picked day can change when it is serialised to UTC.

for a middle

Explain the mechanics: local-midnight values from the native adapter, toISOString on the wire, and date-only ISO strings read as UTC on the way back.

for a senior

Fix it deliberately: Luxon values, toISODate() for date-only fields, and MAT_LUXON_DATE_ADAPTER_OPTIONS with useUtc or timeZone, knowing that the two conflict.

for a principal

Define the date contract across client and server, deciding whose zone defines a business day, before choosing adapter options to match it.

## Where the day goes missing A reservation's pick-up date is a **calendar day**, but a JavaScript `Date` is an **instant**: a count of milliseconds since 1970 in UTC. Angular Material's native adapter has to turn one into the other, and the round trip loses a day: 1. The user in Berlin clicks 12 October 2026. `NativeDateAdapter.createDate` builds a `Date` at **local midnight**, using `setFullYear` and `setHours(0, 0, 0, 0)`. 2. Berlin is on UTC+2 until the last Sunday of October, so that instant is `2026-10-11T22:00:00.000Z`. 3. `HttpClient` serialises the request body with `JSON.stringify`, which calls `Date.prototype.toJSON`, which is `toISOString()`, always in UTC. 4. The backend reads the string, keeps the date part and books the car for 11 October. The adapter's own `toIso8601` does not save you either: the native implementation reads the UTC year, month and day, so it also returns `2026-10-11` for that value. ## The same bug on the way in The backend sends the booking back as `"2026-10-12"`. When that string is bound to the datepicker, the native adapter's `deserialize` matches its ISO 8601 pattern and calls `new Date(value)`. JavaScript reads a date-only ISO string as **UTC midnight**, so a customer in a zone west of UTC sees 11 October in the input. The general JavaScript rules behind this belong to the language's own date pitfalls; the Material part is that the native adapter applies them silently. ## Why the native adapter cannot fix it - It has no time-zone option. `NativeDateAdapter.useUtcForDisplay` only ever affected display, and it was **removed in Material 21**. - Its values are always local-midnight `Date` objects, whatever the backend meant. - The only workaround is outside Material: build a `yyyy-MM-dd` string yourself from the local year, month and day before sending. ## Fixing it with the Luxon adapter `provideLuxonDateAdapter()` makes every value a Luxon `DateTime`, which carries its own zone, and its behaviour is tuned through the `MAT_LUXON_DATE_ADAPTER_OPTIONS` token: | Option | Picked 12 October becomes | When to use it | |---|---|---| | default (`useUtc: false`) | midnight in the browser's zone | send `toISODate()`, the day is all that matters | | `useUtc: true` | `2026-10-12T00:00:00.000Z` | the backend stores dates as UTC midnight | | `timeZone: 'Europe/Berlin'` (22.2.0+) | midnight in Berlin, in any browser | the pick-up branch's zone defines the day | Two details from the 22.2.1 source matter here: - **`useUtc` and `timeZone` together throw** `Cannot set timeZone if the useUtc option is set to true.` - **The options go through the token.** The Material guide shows `provideLuxonDateAdapter(undefined, {useUtc: true})`, but in v22.2.1 that function accepts only a formats argument (it is `provideMomentDateAdapter` that takes options as a second argument). The interface also requires `useUtc` and `defaultOutputCalendar` when you provide your own object. ```ts providers: [ provideLuxonDateAdapter(), { provide: MAT_LUXON_DATE_ADAPTER_OPTIONS, useValue: {useUtc: false, timeZone: 'Europe/Berlin', defaultOutputCalendar: 'gregory'}, }, ] ``` The adapter's `deserialize` uses `DateTime.fromISO` in its configured zone, so `"2026-10-12"` comes back as 12 October. ## Choosing the contract - For **date-only fields**, the clearest wire format is the date itself: `toISODate()` gives `"2026-10-12"` and no zone can shift it. - If the **location's zone** defines the day, as with a rental branch, `timeZone` keeps customers abroad on the branch's calendar. - If the backend insists on **instants**, agree on UTC midnight and set `useUtc: true` so both sides mean the same thing. - The date-fns adapter's `toIso8601` returns the local calendar date, which avoids the UTC shift but offers no zone option.

  • Why not just set useUtc: true and also give the Berlin time zone for display?
    Because the Luxon adapter refuses the combination: `setTimeZone` throws `Cannot set timeZone if the useUtc option is set to true.` The two options answer the same question, which zone a picked day's midnight lives in, so you choose one: UTC midnight for a UTC-based backend, or a named zone when a location defines the day.
  • A reservation also has a pick-up time from a timepicker. Does sending toISODate() still work?
    No, once a time matters you are sending an instant again. Send the full `toISO()` string with its offset, or a local date-time plus the branch's zone name, and let the backend store the instant. The `timeZone` option helps here, because the picked time is then created in the branch's zone rather than the browser's.

  • The datepicker returns a calendar date with no time attached, so nothing can shift.
  • NativeDateAdapter's useUtcForDisplay flag fixes the off-by-one day in Material 22.
  • Calling the native adapter's toIso8601 always returns the day the user clicked.
  • provideLuxonDateAdapter takes the useUtc option as its second argument in Material 22.
  • The bug lives in the backend because the browser sent the correct date.

Assumes Angular Material 22.2; the Luxon adapter's timeZone option arrived in 22.2.0, and NativeDateAdapter.useUtcForDisplay was removed in 21.