Quick start
The easiest path is the share dialog. Share a timer, open theEmbed section,
pick a layout and theme, and copy the generated snippet.
You can also write the snippet by hand. The share link ends with the share
token (for example https://your-tickward-origin/share/timer_abc123); the
embed page lives at /embed/<shareToken> on the same origin:
width and
height you set on the iframe define the rendered size. The title attribute
is for accessibility on the host page; use the timer label.
Parameters
All query parameters are optional. Validation happens server-side with safe fallbacks: an invalid value falls back to its default instead of producing an error, so a hand-edited snippet keeps rendering. Unknown parameters are ignored.| Parameter | Values | Default | Notes |
|---|---|---|---|
layout | text, minimal, compact, square, horizontal | compact | See the layout table below for recommended sizes. |
theme | light, dark, auto | light | auto follows the visitor’s prefers-color-scheme. |
accent | 3- or 6-digit hex, no # (for example e85d2a) | timer color, else theme color | Applied to the digits. When the shared timer has a color, that color is the default accent; an explicit accent always wins. |
bg | transparent or 3-/6-digit hex | card background | transparent removes the card background and border so the host page shows through. A hex value sets the page background behind the card. |
font | mono | UI font | Renders the digits in a monospace font. |
labels | off | on | Hides the unit captions (days, hours, min, sec). |
target | off | on | Hides the absolute target-date line on layouts that show it. |
scale | number from 0.5 to 2 | 1 | Size multiplier on the fluid base size. Values outside the range are clamped. |
Layouts and sizes
Each layout has a recommended iframe size and a minimum width below which it stops shrinking. The share dialog uses these sizes for the generated snippet.| Layout | Recommended size | Minimum width |
|---|---|---|
text | 320 × 48 | 220px |
minimal | 360 × 64 | 260px |
compact | 288 × 140 | 200px |
square | 280 × 280 | 180px |
horizontal | 560 × 96 | 360px |
scale multiplies
the rendered size, so compact at scale=2 effectively needs twice the
minimum width.
States
The embed page always responds with HTTP 200 and renders exactly one of these states, so it never shows a browser error page inside your site:| State | Meaning |
|---|---|
| Counting | The target is in the future; the embed counts down. |
| Since | The target is in the past; the embed counts up and shows elapsed time with “since”. |
| Time’s up | A countdown reached zero while the embed was on screen. Shown until the next load, which renders the count-up state. |
| Timer unavailable | The share token is invalid or the share link was revoked. A neutral card with no timer details. |
JSON state endpoint
For consumers that render natively instead of embedding the iframe - code components in site builders, widgets, badges - the embed state is available as JSON:Access-Control-Allow-Origin: *) so
browsers can fetch it from any origin.
stateiscounting,since, orunavailable. Treat unknown states asunavailable; the enum can grow.nowis the server time. Offset your countdown by the difference betweennowand the local clock instead of trusting the visitor’s clock.timeris omitted when the state isunavailable.coloranddescriptionare optional. For recurring timers,targetDateis the resolved next occurrence.
Cache-Control: public, max-age=60, stale-while-revalidate=300), and the
endpoint is rate limited per client and token. Count down client-side from
targetDate and re-fetch opportunistically - on mount and at most every few
minutes. Do not poll the endpoint per second.