Embed Best Practices Guide

Optimized embeds for Notion and modern web applications

embed.marwanrefaat.com

1. Notion Embed Compatibility
2. Frame.io Requirements
3. General Video Display
4. Responsiveness
5. Supported Embed Types
6. Technical Requirements

1. Notion Embed Compatibility

Embeds must be optimized specifically for Notion's embed container to ensure seamless integration and optimal user experience.

Critical Requirements

Requirement	Specification
Viewport	Must fill 100% of Notion embed container
Aspect Ratio	Preserve content aspect ratio within fluid container
No Scrollbars	Content must not overflow; hide or prevent scrollbars
No Borders/Margins	Zero default browser chrome
HTTPS	Required for Notion embed security
X-Frame-Options	Must allow embedding (Content-Security-Policy: frame-ancestors *)
Load Time	< 1s initial paint

💡 Pro Tip: Use transparent backgrounds and ensure your CSS sets overflow: hidden on both html and body elements.

2. Frame.io Requirements (Primary Use Case)

Frame.io embeds require special handling to strip all UI elements and present only the video content with native aspect ratio.

⚠️ Critical: Video Only

Strip ALL Frame.io UI — no comments, no sidebar, no toolbar, no branding
Container must match the video's actual aspect ratio (4:3, 16:9, 9:16, 1:1, etc.)
Zero letterboxing or pillarboxing — video fills container exactly
Zero padding/margin around video
Minimal controls only if necessary; ideally just the video
Transparent or matched background — never default black

✅ Goal: When embedded in Notion, it should look like a native video — not like a Frame.io review link. Just the footage, nothing else.

3. General Video Display Requirements

Aspect Handling

✓ Respect native aspect ratio
✓ Never force a ratio
✓ Calculate from video dimensions

Object Fit

✓ Use object-fit: contain
✓ Within aspect-matched container
✓ Prevents cropping

Container Sizing

✓ Dynamically sized to video dimensions
✓ Responsive to parent container
✓ Maintains aspect ratio

No Cropping

✓ Video content must never be cut off
✓ Use padding-bottom technique
✓ Absolute positioning for iframe

4. Responsiveness Specification

Breakpoint	Behavior
Mobile (< 480px)	Fluid scaling, maintain native aspect ratio
Tablet (480-1024px)	Fluid scaling, native aspect ratio
Desktop (> 1024px)	Fluid scaling, max-width optional
Notion Default (~700px)	Primary optimization target

5. Supported Embed Types

Priority	Type	Notes
🔴 P0	Frame.io	Primary use case — video only, native aspect ratio
🔴 P0	YouTube	Standard iframe, native aspect ratio
🟡 P1	Loom	Video walkthroughs
🟡 P1	Custom HTML/CSS	Widgets, cards
🟢 P2	Interactive React	Calculators, forms
🟢 P2	Calendly	Scheduling
🟢 P2	Static Images	With optional overlays

6. Technical Requirements

CSS Best Practices

* {
  margin: 0;
  padding: 0;
  box-sizing: border-box;
}

html, body {
  width: 100%;
  height: 100%;
  overflow: hidden;
}

body {
  background: transparent;
}

Aspect Ratio Technique

/* Padding-bottom technique for responsive aspect ratio */
.container {
  width: 100%;
  position: relative;
  padding-bottom: 56.25%; /* 16:9 = 9/16 * 100 */
  height: 0;
}

.iframe {
  position: absolute;
  top: 0;
  left: 0;
  width: 100%;
  height: 100%;
  border: 0;
  object-fit: contain;
}

HTTP Headers

Content-Security-Policy: frame-ancestors *;
X-Frame-Options: (removed or not set)

These headers allow your content to be embedded in any iframe, including Notion.

Built with Next.js • Optimized for Notion •View Demo