---
title: "Datetime & timezones"
url: "https://twistcal.com/docs/datetime"
description: "Pass datetimes in ISO 8601. Pin events to any IANA timezone — DST-aware via Intl.DateTimeFormat. Explicit offsets win."
---

Pass datetimes in ISO 8601. With a timezone offset (`2026-02-10T14:00:00Z` or `2026-02-10T14:00:00-05:00`) the calendar services get an absolute time. Without one (`2026-02-10T14:00:00`) the browser treats it as local time and converts to UTC — usually what you want for a page visited from multiple time zones.

## Timezone

When the event happens in a specific timezone (not the visitor’s), pass the IANA name:

```
<twist-cal
  title="Oslo Team Sync"
  start="2026-01-15T10:00:00"
  end="2026-01-15T11:00:00"
  timezone="Europe/Oslo">
</twist-cal>
```

A visitor in Miami clicks the button — their Google Calendar gets `20260115T090000Z` (09:00 UTC = 10:00 Oslo = 04:00 Miami). DST is handled via `Intl.DateTimeFormat`, so the offset is correct for the event’s date, not the visitor’s current date.

## IANA timezone examples

| Zone | Example |
| --- | --- |
| Europe/Oslo | CET/CEST, +1/+2 |
| America/New_York | EST/EDT, -5/-4 |
| Asia/Tokyo | JST, +9 (no DST) |
| Australia/Sydney | AEDT/AEST, +11/+10 |
| Pacific/Honolulu | HST, -10 (no DST) |

Full list: any [IANA timezone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones?utm_source=twistcal.com) name works.

## Explicit offsets win

If `start`/`end` already carry an offset (`Z` or `+05:00`), the `timezone` attribute is ignored — the explicit offset wins:

```
<!-- timezone ignored — offset is in the string -->
<twist-cal
  title="Fixed UTC event"
  start="2026-01-15T10:00:00Z"
  end="2026-01-15T11:00:00Z"
  timezone="Europe/Oslo">
</twist-cal>
```

## All-day events

Set `all-day="true"` for date-only formats. Pass dates, not datetimes:

```
<twist-cal
  all-day="true"
  title="Company offsite"
  start="2026-04-20"
  end="2026-04-22">
</twist-cal>
```

Produces date-only `.ics` (`VALUE:DATE`) and Google/Yahoo all-day URLs. `timezone` is irrelevant for all-day events.

## Programmatic timezone handling

The generators export helpers for advanced use:

```
import { parseInTz, tzOffsetMs, normalizeEvent } from '@freshjuice/twistcal/generators';

// Parse a naive datetime as wall-clock in a timezone → UTC Date
parseInTz('2026-01-15T10:00:00', 'Europe/Oslo');  // → 2026-01-15T09:00:00Z (winter)

// Get UTC offset (ms) for a timezone at a UTC instant
tzOffsetMs('Europe/Oslo', Date.parse('2026-01-15T00:00:00Z'));  // → 3600000 (+1h)

// Normalize an event: convert naive start/end to UTC if timezone is set
normalizeEvent({ ...event, timezone: 'Europe/Oslo' });
```

See the [API](/docs/api/) for the full export list.

## Next

-   [Web component](/docs/web-component/) — the `timezone` attribute
-   [API](/docs/api/) — generator helpers