digital-svg-clock

This small experiment was spawned during an "I wonder if..." moment while customizing my GitHub profile readme with the github-readme-stats badges.

GitHub can display your local time on your profile page, and I thought maybe you could do something like that with a ticking clock in an SVG within the profile readme.

All JavaScript gets sanitized by the GitHub markdown renderer, even within an SVG. So updating the SVG content using JavaScript embedded within the SVG is not an option. This is a good thing; allowing it would pose a huge security risk.

But it turns out you can do it anyway using SMIL-animation chaining, albeit with some caveats and hard browser limitations that make this method not fully useful.

Limitations

JavaScript-driven SVG clocks don’t work within <img> tags or in JavaScript-sanitized contexts, such as a GitHub readme.

SMIL-animation driven SVG clocks do work, with one major caveat: browsers will pause SMIL animations when a tab is inactive for a period of time and will not resume them until the tab becomes active again.

This means any SMIL-animation driven clock will work upon page load but will drift if the tab containing the SVG becomes inactive for too long. Therefore, SMIL-animation driven clocks are not fully reliable for displaying the correct time.

This is a hard browser limitation, and there is nothing that can be done about it. There is also no way to detect when the animation has been paused using only SMIL-animation chaining.

How it works

The generated SVG clock that uses SMIL animations has <text> elements for all possible values of hours, minutes, and seconds. These elements are shown or hidden using <animate> elements, which adjust the opacity of the <text> elements.

The <animate> elements are chained in loops for hours, minutes, and seconds, respectively. Their durations are generated dynamically based on startTime to ensure the correct start time and to keep the wraparounds of hours, minutes, and seconds synchronized.

Each <animate> element uses a maximum duration of 60 seconds to avoid issues in some browsers that may truncate longer animation durations. The resulting SVG size for a full 24-hour cycle is roughly 164 KB, which is quite reasonable given the number of elements generated.

Usage

To use the npm package in your project run:

npm install digital-svg-clock

Basic example of generating a SMIL-animation driven SVG clock using the npm package:

import { DigitalSvgClock } from "digital-svg-clock";

const clock = new DigitalSvgClock({
    clockFormat: "24h",
    startTime: new Date(2025, 0, 1, 12, 59, 40),
    textColor: "#000000",
    useJavascript: false
});
const svg = clock.render();

Available parameters:

| Option | Type | Default | |-----------------|-------------------------|---------------------------| | width | number | 300 | | height | number | 100 | | centerX | number | width / 2 | | centerY | number | height / 2 | | clockFormat | "12h" \| "24h" | "24h" | | startTime | Date | new Date() | | textFontSize | number | 60 | | textFontFamily | string | "monospace" | | textFontWeight | string | "bold" | | textSpacing | number | 1.0 | | textColor | string | "#333333" | | useJavascript | boolean | true | | extraElements | AnimatedSVGElement[] | [] |

Building

Clone the repository, then run:

npm install

Now you can build it using tsc:

npm run build

Running tests

To run the jest tests that generate the example SVGs:

npm run test

Contributing

Contributions of all kinds are welcome. These could be suggestions, issues, bug fixes, documentation improvements, or new features.

For more details see the contribution guidelines.

License

This project is licensed under the MIT license.