webdelta.js

Description

webdelta.js is a versatile JavaScript utility that allows you to easily convert UNIX timestamps and ISO 8601 date/time strings into human-readable dates, times, and relative time descriptions directly on your webpages. This script dynamically displays time information with customisable tooltips and formats.

Simply include the script, and any element with the webDelta class will be displayed as a time/date string with a tooltip showing the time until (or since) the given moment. The element's contents can be a UNIX timestamp or an ISO 8601 wall-clock string (see the Wall-clock & AoE section), including an aoe mode for "Anywhere on Earth" conference deadlines. See below for examples.

Features

Flexible Input: Accepts UNIX timestamps or ISO 8601 wall-clock strings, including an aoe ("Anywhere on Earth", UTC−12) mode for conference deadlines.
Automatic Conversion: Converts UNIX timestamps and ISO 8601 strings to readable date and time formats.
Time Zone Support: Automatically displays times in the user's local time zone or a custom time zone of your choice.
Localised: Makes use of the JavaScript Intl API to support multiple locales.
Relative Time Descriptions: Displays relative time (e.g., "2 minutes ago" or "in 3 days") with live updating tooltips.
Custom Formatting: Choose from various formatting options like short, medium, long, and full for dates and times.
Tooltip Customisation: Fully customisable tooltips with adjustable styles and behaviours, including support for dynamic updates every second.
Synchronisation: Ensures that all time updates are perfectly synchronised with the real-time clock.
Easy Integration: Just include the script on your webpage and add the appropriate classes to your tags.
Multiple Display Modes: Display only the date, only the time, or both, with or without time zones.

Installation

CDN:

Include the Script: Add the following line in your HTML to include the script.

<script src="https://cdn.jsdelivr.net/gh/thunderpoot/webdelta@1.2.0/dist/webdelta.min.js"></script>

Download:

Download the Script: Download the webdelta.js file and include it in your project.
Include the Script: Add the following line in your HTML to include the script.
```
<script src="path/to/webdelta.js"></script>
```

Demo

Enter a UNIX Timestamp or ISO 8601 wall-clock string to update the examples below:

Please enter a valid UNIX timestamp.

Examples

Hover your cursor over the timestamps below to display tooltips (unless the noTooltip class is present):

119731017

<span class="webDelta">119731017</span>

119731017

<span class="webDelta raw">119731017</span>

119731017

<span class="webDelta weekday noTooltip">119731017</span>

119731017

<span class="webDelta dateOnly">119731017</span>

119731017

<span class="webDelta timeOnly">119731017</span>

119731017

<span class="webDelta iso8601">119731017</span>

119731017

<span class="webDelta short">119731017</span>

119731017

<span class="webDelta medium">119731017</span>

119731017

<span class="webDelta long">119731017</span>

119731017

<span class="webDelta full">119731017</span>

119731017

<span class="webDelta timeOnly weekday noTZ">119731017</span>

119731017

<span class="webDelta noTZ">119731017</span>

119731017

<span class="webDelta swap">119731017</span>

Wall-clock & AoE

As well as UNIX timestamps, webdelta.js accepts ISO 8601 wall-clock strings. The source zone must be explicit: either an offset baked into the string (e.g. 2026-06-09T23:59:00+01:00), or the aoe class, which interprets the time as Anywhere on Earth (UTC−12), the standard for conference and CFP deadlines. A bare wall-clock with no zone is rejected rather than silently assumed to be your local time. With aoe, a missing component defaults to the end of the stated precision (T23:59 → :59, a bare date → end of day), so a deadline is never moved earlier. Each example below is shown converted to your local time.

2026-06-09T23:59

<span class="webDelta aoe swap">2026-06-09T23:59</span>

2026-12-01T23:59

<span class="webDelta aoe">2026-12-01T23:59</span>

2026-09-15

<span class="webDelta aoe dateOnly">2026-09-15</span>

2026-06-09T23:59:00+01:00

<span class="webDelta">2026-06-09T23:59:00+01:00</span>

Available Options

The following class attributes may be used to specify parameters for webdelta.js. Some are mutually exclusive.

Class	Description
`raw`	Don't format the date, preserve the UNIX timestamp.
`dateOnly`	Display only the date (with time zone unless `noTZ` is present).
`timeOnly`	Display only the time (with time zone unless `noTZ` is present).
`iso8601`	Display the date and time in ISO 8601 format.
`short`	Display the date and time in a short format.
`medium`	Display the date and time in a medium format.
`long`	Display the date and time in a long format.
`full`	Display the date and time in a full format.
`weekday`	Include the full weekday name in the date and time string.
`utc`	Force the date and time to be displayed in UTC.
`noTZ`	Disable the time zone display.
`noTooltip`	Disable the tooltip display.
`swap`	Show the live relative delta inline and move the date/time string into the tooltip.
`aoe`	Interpret an ISO 8601 wall-clock string as Anywhere on Earth (UTC−12). A missing seconds/time component defaults to the end of the stated precision (e.g. `T23:59` → `:59`, a bare date → end of day), so a deadline is never moved earlier.

Example Configuration Code

To customise the behaviour and appearance of webdelta.js you can embed the following JavaScript on your page:

<script>
    window.webDeltaConfig = {
        tooltipBorderRadius: '8px',
        tooltipFont: 'Helvetica, sans-serif',
        tooltipFontSize: '16px',
        tooltipXOffset: 20,
        tooltipYOffset: 20,
        timeZone: 'Europe/Madrid',
        lang: 'es', // Supports BCP47 values such as sv-SE or en-GB
        numeric: 'auto', // 'auto' for "tomorrow"/"last week", 'always' for "in 1 day"
        tooltipBackgroundColor: '#333333',
        tooltipForegroundColor: '#ffcc00'
    };
</script>

The numeric option controls how relative deltas are worded. The default 'auto' renders a difference of exactly one unit as a word (tomorrow, yesterday, last week), while 'always' keeps it numeric (in 1 day, 1 day ago).