BLOG · TUTORIAL · B.250711

Tutorial

Build your own Notion widget with HTML and CSS

Build a Notion widget in plain HTML and CSS, host it at a public HTTPS URL, and add it with /embed. Covers iframe headers, fonts, and a clock example.

Build your own Notion widget with HTML and CSS
Cover · B.250711

You can build your own Notion widget as one page of plain HTML and CSS. You host the page at a public URL, and Notion shows it inside an Embed block. This guide uses no framework.

This guide explains how Notion embeds work and the minimum HTML and CSS that we use in production. It covers hosting, security headers, and common problems. It also explains when Blocky (https://blocky.so) is the better choice for charts, timers, and study widgets.

At the end, you have a shareable URL for your widget that you can embed in any Notion page.


When to build your own Notion widget

Build your own widget when no general-purpose widget does exactly what you need. For example, you may want a KPI (key performance indicator) badge in your brand colors, a quote card that rotates daily, or an availability banner that your team sees at a glance.

We hand-build widgets when:

  • We want a specific layout or animation.
  • We need our brand's type scale and color tokens.
  • We plan to iterate fast and don't want vendor lock-in.

Build or buy: when Blocky is the better choice

For complex widgets, such as data-bound charts, timers, and study tools, we use Blocky (https://blocky.so). It connects to your Notion workspace in a few clicks, offers polished variants, and handles state and edge cases that we would rather not own. On the Pro plan, it also syncs your Notion data automatically. Other plans update data with Refresh data.

In Blocky, we use these widgets:

  • Charts: Bar, Line, Pie, Area, and Radar, mapped to Notion databases.
  • Timers: countdowns, world clocks, Pomodoro, and stopwatches.
  • Study widgets: habit trackers, flashcards, progress bars, and streaks.
  • Creative widgets: mood trackers, quotes, and more.

Blocky is an official Notion integration (https://www.notion.com/integrations/blocky), so its widgets embed cleanly, load fast, and need less maintenance. It has three plans:

  • Free: up to 2 charts and 5 total widgets. Charts count as widgets.
  • Standard: 5 charts and 10 widgets for $3.59/month.
  • Pro: unlimited widgets and charts, premium widgets, and automatic Notion sync for $5.99/month.

We hand-code the edge cases, where we want pixel-perfect control or a one-off user experience, and use Blocky for everything else. That split lets us move fast.


How Notion embeds work and what your page needs

Notion has an Embed block. You type /embed, paste a public URL, and Notion renders that page inside your Notion page. So you don't paste raw HTML into Notion. You host the widget, then embed its link.

That gives your widget page two requirements:

  • It must be publicly reachable over HTTPS.
  • It must allow itself to be shown inside an iframe, which is a frame that shows one web page inside another.

If your server sends headers that forbid iframes, Notion won't show the widget. Two headers control this: X-Frame-Options and the Content-Security-Policy (CSP) frame-ancestors directive. The section on controlling embedding below explains both.

To embed a YouTube video, use its /embed/ URL, not its watch?v= URL. Many services follow a similar pattern.


HTML essentials for your widget

We keep our HTML small and semantic. It has:

  • A parent <main> or <div role="region"> as the widget shell.
  • A heading, <h2> or <h3>, for screen readers and structure.
  • Content elements such as <p>, <time>, <ul>, and <button>, when you need them.

Notion wraps your page in an <iframe>, so don't add one yourself. Build one clean, self-contained page.

Our baseline document has:

  • A minimal <head> with a title and viewport.
  • One stylesheet in the head, for speed.
  • No blocking scripts unless they are necessary.

Test the widget in a normal browser tab first. If it looks right there, it usually looks right embedded.


CSS fundamentals for your widget

A few CSS patterns cover most of what a widget needs:

  • Reset or normalize default styles lightly. We prefer resets per component.
  • Scale typography with relative units (rem) and a tight line-height.
  • Use CSS variables for color tokens, so you can change the theme in one place.
  • Use Flexbox for micro-layout and Grid for macro layout.

Learn these selectors:

  • Type (h3, p), class (.card), and ID (#cta) selectors.
  • Attribute selectors ([data-state="active"]) for simple component states.
  • Child and descendant combinators for structure.

Organize your stylesheet by component or section. Add clear comments, and avoid clever hacks. Simple CSS fails less often when embedded.


Design your first widget: layout, type, and color

Start with a small card that has:

  • A title line.
  • A value or message.
  • An optional subtitle or status pill.

Layout:

  • Use a single .card container with padding and rounded corners.
  • Apply display: grid with a narrow gap to stack text cleanly.
  • Give the shell a soft shadow and a strict max-width.

Typography:

  • Choose two weights of a single font family.
  • Set font-size on the root, for example 16px, then use rem everywhere.
  • Adjust letter-spacing for UIs that need extra clarity.

Color:

  • Pick a neutral background and high-contrast text.
  • Reserve the accent color for the metric or callout.
  • If the card is clickable, add a light hover state.

Load fonts fast and legally

Good typography improves even a simple widget. We use either system fonts, which load with zero latency, or Google Fonts through its official API.

To load a Google Font:

  1. Choose a family and weights on Google Fonts (https://fonts.google.com).
  2. Copy the <link> or the CSS @import from the Getting Started docs.
  3. Declare a fallback font stack that the browser uses if the web font fails to load.

Avoid loading six weights. Two are plenty for a UI. For fine control over FOIT and FOUT (flash of invisible text and flash of unstyled text), use the WebFont Loader or native font-display rules.

Load fonts from trusted content delivery networks (CDNs), and keep them cached.


Free example: a live digital clock widget

This basic example is a live digital clock that you can host and embed:

<!DOCTYPE html>
<html>
	<head>
 <meta charset="UTF-8" />
 <title>Custom Notion Clock</title>
 <style>
 body {
 margin: 0;
 display: flex;
 justify-content: center;
 align-items: center;
 height: 100vh;
 background: #111827;
 color: #22d3ee;
 font-family: sans-serif;
 font-size: 3rem;
 }
 </style>
	</head>
	<body>
 <div id="clock"></div>
 <script>
 function updateClock() {
 const now = new Date();
 const time = now.toLocaleTimeString([], {
 hour: '2-digit',
 minute: '2-digit',
 });
 document.getElementById('clock').textContent = time;
 }
 setInterval(updateClock, 1000);
 updateClock();
 </script>
	</body>
</html>

Host your widget on a public HTTPS URL

To embed your widget in Notion, you need a public HTTPS URL for it. Any static host works. We use these:

Our usual steps:

  1. Create a repository with /index.html and /styles.css.
  2. Push the repository to GitHub.
  3. Connect the repository to your host.
  4. Deploy the site.
  5. Copy the public URL. You paste it into Notion in the next section.

Disable directory listings, and publish only what the widget needs: one page and one stylesheet.


Embed your widget in Notion

In your Notion page:

  1. Type /embed.
  2. Paste your widget's public URL.
  3. Resize the block until it fits your layout.
  4. If you want extra context, add a caption.

Blocky widgets use the same steps: generate a share URL in Blocky, paste it into Notion, and position it beside your content.

If the embed fails:

  • Confirm that the URL is public.
  • Check that your host allows iframes.
  • Try a different browser to rule out extensions.

Control embedding with X-Frame-Options and CSP frame-ancestors

Notion shows your widget inside an iframe, but your server decides whether embedding is allowed. Two response headers control this.

The X-Frame-Options response header has these values:

  • DENY never allows embedding.
  • SAMEORIGIN allows embedding only on your own domain.
  • ALLOW-FROM is obsolete. Don't use it.

The Content-Security-Policy frame-ancestors directive is the modern way. It controls which parent pages may embed your page.

If you block embedding, Notion can't render your widget. If you allow it too broadly, you risk clickjacking on other sites. In clickjacking, another site loads your page in a frame and tricks people into clicking it. We keep this conservative. For a public widget meant for Notion, we set a narrowly scoped frame-ancestors or rely on the host's defaults.

Your server sends these headers. You can't set them inside your HTML and have them take effect.


Performance and polish: fonts, images, and responsive layout

Aim for an instant render inside the Notion block. Keep the page small:

  • If your critical CSS is under about 5–8 KB, inline it.
  • Defer non-essential scripts.
  • Minify the HTML and CSS to save bytes.

Fonts:

  • Use two weights at most.
  • Prefer font-display: swap for better perceived speed.
  • Cache fonts aggressively.

Images:

  • Use SVG for vector icons.
  • Use modern formats for any small photos.
  • Avoid heavy backgrounds. Notion already frames your content.

Responsive layout:

  • Cap the width with max-width.
  • Scale padding and font sizes with clamp() or rem.
  • Test in Notion's narrow column width and on full-width pages.

Troubleshooting common embed issues

The embed is blank

Your host may be sending X-Frame-Options: DENY or a restrictive frame-ancestors. Check your response headers in your browser's developer tools or with curl -I.

"Refused to connect" error

Some services don't allow other sites to embed them. If the server forbids embedding, you can't fix it on the client side. Host your own page, or use the platform's official embed URL.

The layout looks cramped in Notion

Give your widget a neutral background and generous inner padding. Notion's outer padding is tight, so compensate inside your card.

The font looks different in Notion

Check that the font loads over HTTPS and that CSP doesn't block it. Always define a fallback font stack for when the web font fails to load.


Advanced ideas: states, theming, and interactivity

Plain HTML and CSS can also handle states and themes:

  • Use data attributes, such as data-state="active", to style states.
  • Use CSS variables for light and dark themes that you switch with one class.
  • Use the prefers-color-scheme media query for automatic theming.

To add interactivity:

  • Add a small script that rotates quotes or fetches a status string.
  • Use progressive enhancement: load the script after the first paint.
  • Keep a fallback that works without JavaScript, so your widget degrades gracefully.

If you need complex state, authentication, or data from your Notion databases, use Blocky (https://blocky.so) instead. It already handles the hard parts for timers, charts, and study widgets that talk to Notion.



Filed under Tutorial

RELATED · 03

Studio · CustomizeLive preview

Compose · Preview · Embed

Customize a widget, then embed it anywhere in Notion

Shape one of Blocky’s 60+ widgets to your data and layout, preview the result live, then drop the embed link into any Notion page. Sign in to start customizing.

Start customizing