Developer Documentation

Everything you need to know about implementing, customizing, and troubleshooting the Calendar Week widget in your applications.

Ultralight Footprint

Less than 2KB (gzipped). It loads asynchronously and won't block your Main Thread or affect your Core Web Vitals.

Privacy First

Zero cookies. We don't want your data, we just want to tell you the date.

Chameleon Engine

Automatically inherits your website's font family and transparency settings. It looks like you built it yourself.

Shadow DOM

Encapsulated styles mean our CSS never leaks out to break your site, and your global styles won't break our widget.

Implementation Guide

The widget requires two elements: a container where the widget renders, and a script that powers it.

Basic Usage

Place the container where you want the widget to appear. Add the script once, ideally before the closing </body> tag.

<!-- Container: Place where you want the widget -->
<div class="tcw-embed" data-terms="accepted"></div>

<!-- Script: Add once before </body> -->
<script src="https://thecalendarweek.com/embed.js" async></script>

Header / Navbar

Ideal for the Minimal design. Place inline with your navigation items.

<nav>
  <a href="/">Home</a>
  <a href="/about">About</a>
  <div class="tcw-embed"
       data-design="minimal"
       data-terms="accepted">
  </div>
</nav>

Sidebar Widget

Dashboard or Analog designs work great in sidebars.

<aside class="sidebar">
  <h3>Calendar</h3>
  <div class="tcw-embed"
       data-design="dashboard"
       data-variant="calendar"
       data-terms="accepted">
  </div>
</aside>

Important:The data-terms="accepted" attribute is required. Without it, the widget will display an error message.

Attribute Reference

Configure the widget by adding data- attributes directly to the container element.

Attribute	Values	Description
data-terms	accepted	REQUIRED. Acknowledges acceptance of Terms of Use.
data-design	minimal \| dashboard \| classic \| analog	Sets the visual theme. Defaults to `minimal`.
data-logic	iso \| us	iso: Weeks start Monday (EU). us: Weeks start Sunday.
data-lang	en \| de	Localizes labels (e.g. "Week" vs "Woche").
data-variant	simple \| iso \| weekdays \| calendar \| range \| stats	Layout variant. simple/iso for Minimal, others for Dashboard.
data-primary	hex code	Accent color for Minimal design. Example: `#FF5500`.
data-size	small \| large	Size variant for Minimal design. large shows calendar icon.
data-scheme	warm \| blue	Color palette for Analog design.
data-bg	CSS color	Background color override. Default: `transparent`.
data-text	CSS color	Text color override. Default: `inherit`.
data-hover	CSS color	Hover effect background color.

iFrame Embed Guide

For SharePoint, Notion, and corporate intranets where external scripts are restricted.

Having Issues?

Check our troubleshooting guide for common problems and solutions.

We continuously enhance our widgets with STRICT backward compatibility in mind.

View Changelog & API Compatibility Strategy →