Embed providers
The embed provider registry: built-in providers with their link forms and sizes, plus functions to parse links and add your own.
An embed provider turns a pasted page link into a small ref of validated ids, and builds every iframe, canonical and oEmbed URL from that ref alone. A saved document stores the provider name and the ref. It never stores a player URL: the player URL is built at render time from the provider and the validated ids, and the sanitizer re-checks every ref against its provider. That is why a tampered document cannot smuggle in an iframe.
YouTube and Vimeo belong to the video node and have their own functions. The nine other built-in providers belong to the embed node and live in a registry that you can add to.
All functions on this page are exported from post-canvas. registerEmbedProvider and defineEmbedProvider are also exported from post-canvas/server, post-canvas/render, post-canvas/extensions and post-canvas/vanilla (and so the CDN global). getEmbedProvider, listEmbedProviders and builtInEmbedProviderNames are also exported from post-canvas/render, and builtInEmbedProviderNames from post-canvas/server.
Built-in providers
builtInProviders lists all eleven: YouTube and Vimeo (for the video node), then the nine embed providers. builtInEmbedProviderNames lists the nine embed names, which is the default of the embed feature's providers:
const builtInEmbedProviderNames: readonly string[];
// 'spotify', 'soundcloud', 'x', 'instagram', 'tiktok', 'codepen', 'loom', 'figma', 'google-maps'Every link must pass parseEmbedUrl: http or https only, no user name or password, no port, no whitespace, at most 2048 characters. Each provider then checks the host against an exact list and every id against a strict pattern.
| Provider | Links it accepts | Player and size |
|---|---|---|
YouTube (youtube, video node) | youtube.com, www., m. and music.youtube.com, and youtube-nocookie.com: /watch?v=<id>, /shorts/<id>, /embed/<id>, /live/<id>, /v/<id>. Also youtu.be/<id>. The id has 11 characters. A start time comes from t or start in the query: 90, 90s, 1m30s, 1h2m3s, up to 12 hours. | The youtube-nocookie.com player. 16:9, or 9:16 for a Short. Thumbnails come from i.ytimg.com. |
Vimeo (vimeo, video node) | vimeo.com/<id>, vimeo.com/<id>/<hash> or ?h=<hash> for an unlisted video, videos in /channels/, /groups/ and /showcase/, and player.vimeo.com/video/<id>. A start time comes from #t=. | player.vimeo.com with dnt=1. 16:9. |
Spotify (spotify) | open.spotify.com/<type>/<id> for track, album, playlist, episode, show and artist. An intl-xx prefix and /embed are accepted. The id has 22 characters. | Fixed height: 152 px for a track or episode, 352 px for the others. |
SoundCloud (soundcloud) | soundcloud.com, www. and m.soundcloud.com: /<user>/<track> and /<user>/sets/<set>. | Fixed height: 166 px for a track, 450 px for a set. |
X (x) | x.com, twitter.com and their www. and mobile. forms: /<user>/status/<id>, also with /photo/<n> or /video/<n> after the id. | Fixed height: 560 px. |
Instagram (instagram) | instagram.com/p/<code>, /reel/<code> and /tv/<code>, also as /<user>/p/<code> and with /embed. | Fixed height: 640 px. |
TikTok (tiktok) | tiktok.com/@<user>/video/<id>, /embed/v2/<id> and /player/v1/<id>. | 9:16. |
CodePen (codepen) | codepen.io/<user>/pen/<slug>, also embed, full and details instead of pen, and the /team/<team>/pen/<slug> form. | Fixed height: 420 px. |
Loom (loom) | loom.com/share/<id> and loom.com/embed/<id>. The id is 32 hex characters. | 16:9. |
Figma (figma) | figma.com/<kind>/<key>, where <kind> is file, design, proto, board or slides, with an optional file name after the key and ?node-id=. | 16:10. |
Google Maps (google-maps) | google.com/maps?q=<place>, /maps/place/<name>, /maps/search/<query>, /maps/@<lat>,<lng>,<zoom>z, and maps.google.com/?q=<place>. | 4:3. |
Players with a fixed height (Spotify, SoundCloud, X, Instagram and CodePen) cannot size themselves, because a cross-origin player cannot report its height. The others scale from an aspect ratio.
Google Maps short links (maps.app.goo.gl) need a server lookup to find the place, so the google-maps provider does not match them. A pasted short link becomes a link card when adapters.links is set, and a plain link otherwise.
Instagram, Figma and Google Maps have no oEmbed endpoint in Post Canvas, so createEmbedResolver returns no title for them.
Types
EmbedProvider is the contract of a provider. Create one with defineEmbedProvider.
Prop
Type
EmbedFrame says how to load the player. Every field is built from the ref, never from stored HTML or a stored URL.
Prop
Type
Whatever a provider returns, Post Canvas keeps only an absolute https src, cuts sandbox to a short allowlist of tokens (no top navigation) and allow to playback features (no camera, microphone or location), and drops origin lists. The player must live on the provider's own host, never on your app's origin.
EmbedMatch is a pasted URL that a provider recognised.
Prop
Type
EmbedRef is the validated ids that identify one embed, such as { type: "track", id: "4uLU6hMCjMI75M1A2tKUQC" }. It is a flat record of at most 8 short strings. Keys start with a lower-case letter and use letters and digits, up to 20 characters. Values are 1 to 200 characters.
type EmbedRef = Record<string, string>;VideoProvider names the two video providers, and VideoRef is a parsed video link: everything the video node stores about where the video lives.
type VideoProvider = 'youtube' | 'vimeo';Prop
Type
EmbedInputKind is what a paste-a-link field asks for. any tries video, then embed, then link card.
type EmbedInputKind = 'any' | 'video' | 'embed' | 'link';Registry functions
defineEmbedProvider
function defineEmbedProvider(provider: EmbedProvider): EmbedProvider;defineEmbedProvider checks a provider and returns a frozen copy. It throws when name is not lower-case letters, digits and dashes (it must start with a letter, at most 40 characters), or when match(), frame() or canonicalUrl() is missing. See Add a provider below.
registerEmbedProvider
function registerEmbedProvider(provider: EmbedProvider): void;registerEmbedProvider adds a provider to the embed node's registry, so the editor, the sanitizer and the renderers know it. It runs defineEmbedProvider on it first. Register it everywhere that renders or sanitizes documents, including your server. A built-in name, and the names youtube and vimeo, cannot be replaced: it throws.
getEmbedProvider
function getEmbedProvider(name: unknown): EmbedProvider | undefined;getEmbedProvider returns the embed provider registered under name, or undefined. YouTube and Vimeo belong to the video node, so they are not found here.
listEmbedProviders
function listEmbedProviders(): EmbedProvider[];listEmbedProviders returns every registered embed provider, built-in ones first.
parseEmbedUrl
function parseEmbedUrl(input: unknown): URL | null;parseEmbedUrl parses a pasted link for embedding, or returns null. A bare example.com/path is read as https. It refuses anything that is not http or https, carries a user name or password (https://youtube.com@evil.com), names a port, holds whitespace or control characters, or is longer than 2048 characters. The returned URL's host is lower-case and has no trailing dot. Every provider's match() gets a URL that already passed it.
matchEmbedUrl
function matchEmbedUrl(input: string, names?: readonly string[]): EmbedMatch | null;matchEmbedUrl finds the provider for a pasted link among names (default: every registered embed provider), or returns null. The link must pass parseEmbedUrl(), and the returned ref must round-trip through the provider's canonical URL. It does not look at YouTube and Vimeo: use parseVideoUrl for those.
import { matchEmbedUrl } from 'post-canvas';
const match = matchEmbedUrl('https://open.spotify.com/track/4uLU6hMCjMI75M1A2tKUQC');
// match.provider.name === 'spotify'
// match.ref is { type: 'track', id: '4uLU6hMCjMI75M1A2tKUQC' }
// match.url is the canonical page URLparseVideoUrl
function parseVideoUrl(input: string): VideoRef | null;parseVideoUrl reads a YouTube or Vimeo link, or returns null. Lookalike hosts (youtube.com.evil.com), user-name tricks, other protocols and malformed ids are all null. Shorts come back vertical, and an unlisted Vimeo link keeps its hash.
canonicalVideoUrl
function canonicalVideoUrl(video: VideoRef): string;canonicalVideoUrl returns the video's own page: what oEmbed is asked about and what "Watch on" links to.
import { canonicalVideoUrl, parseVideoUrl } from 'post-canvas';
const video = parseVideoUrl('https://youtu.be/aqz-KE-bpKQ?t=1m30s');
// { provider: 'youtube', videoId: 'aqz-KE-bpKQ', hash: null, vertical: false, start: 90 }
if (video) console.log(canonicalVideoUrl(video)); // https://www.youtube.com/watch?v=aqz-KE-bpKQ&t=90sAdd a provider
A provider needs a unique name, a label, and three functions: match() reads a URL and returns the validated ids, frame() builds the player, and canonicalUrl() builds the provider's own page. Check the host against an exact list and every id against a strict pattern. Return null from match() for anything you do not recognise.
import type { EmbedProvider } from 'post-canvas';
export const peertube: EmbedProvider = {
name: 'peertube',
label: 'PeerTube',
aspectRatio: 16 / 9,
match: (url) =>
url.hostname === 'video.example.org' && /^\/w\/[A-Za-z0-9]{22}$/.test(url.pathname)
? { id: url.pathname.slice(3) }
: null,
frame: (ref) => ({
src: `https://video.example.org/videos/embed/${ref.id}`,
title: 'PeerTube video',
allow: 'fullscreen',
sandbox: 'allow-scripts allow-same-origin',
aspectRatio: 16 / 9,
height: null,
}),
canonicalUrl: (ref) => `https://video.example.org/w/${ref.id}`,
};Register it on the client and on the server, and add its name to the embed feature's providers:
'use client';
import { PostCanvas, builtInEmbedProviderNames, registerEmbedProvider } from 'post-canvas';
import 'post-canvas/styles.css';
import { peertube } from '../lib/peertube';
registerEmbedProvider(peertube);
const features = { embed: { providers: [...builtInEmbedProviderNames, 'peertube'] } };
export function Editor() {
return <PostCanvas features={features} />;
}import {
builtInEmbedProviderNames,
registerEmbedProvider,
resolveFeatures,
sanitizeDocument,
} from 'post-canvas/server';
import { peertube } from '../../../lib/peertube';
registerEmbedProvider(peertube);
const features = resolveFeatures('full', { embed: { providers: [...builtInEmbedProviderNames, 'peertube'] } });
export async function POST(request: Request) {
const { content } = (await request.json()) as { content: unknown };
const { doc } = sanitizeDocument(content, { features });
return Response.json(doc);
}sanitizeDocument removes an embed node whose provider is not registered or not in providers, so the server must register the same providers and use the same features as the editor. A provider can also define oembed(ref) (a fixed oEmbed endpoint, used only on the server by createEmbedResolver) and thumbnail(ref) (a thumbnail URL built from the ref).
Extensions entry
The post-canvas/extensions entry: Tiptap kits, schemas, node classes, sanitizers and paste helpers for custom editors and servers.
Helpers and utilities
Helper functions, constants and small components exported from post-canvas: presets, stats, limits, autosave, uploads, URLs and UI parts.