
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
.cardcontainer with padding and rounded corners. - Apply
display: gridwith 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-sizeon the root, for example16px, then useremeverywhere. - Adjust
letter-spacingfor 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:
- Choose a family and weights on Google Fonts (https://fonts.google.com).
- Copy the
<link>or the CSS@importfrom the Getting Started docs. - 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:
- Vercel (https://vercel.com) is frictionless for static sites.
- Netlify (https://www.netlify.com) has solid, simple deploys.
- Cloudflare Pages (https://pages.cloudflare.com) has a fast CDN and easy setup.
- GitHub Pages (https://pages.github.com) is free and predictable.
Our usual steps:
- Create a repository with
/index.htmland/styles.css. - Push the repository to GitHub.
- Connect the repository to your host.
- Deploy the site.
- 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:
- Type /embed.
- Paste your widget's public URL.
- Resize the block until it fits your layout.
- 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:
DENYnever allows embedding.SAMEORIGINallows embedding only on your own domain.ALLOW-FROMis 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: swapfor 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()orrem. - 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-schememedia 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.
Other articles
- Gamified productivity in Notion
- Notion project management guide
- How to make a pie chart for Notion
- Create a custom flashcard system in Notion
- How to add live data widgets to Notion
Filed under Tutorial
RELATED · 03
Related entries

How to use Notion for project management
Learn how to use Notion for project management with a reusable database schema, board and timeline views, formulas, and Blocky charts and timers.

How to make a pie chart for Notion
Make a pie chart for Notion that people can read: prepare clean data, limit and label the slices, pick colors, then build it in Blocky and embed it.

How to create custom charts in Notion
Build bar, line, pie, area, and radar charts from your Notion database with Blocky, style them for readability, and embed them in a Notion page.
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