Skip to Content
Post Canvas
Guides

Custom embed providers

Add your own embed provider with defineEmbedProvider and registerEmbedProvider, with a full example, the validation rules and where to register it.

Post Canvas embeds nine sites besides YouTube and Vimeo (see Embeds and link previews). If you need another site, such as a self-hosted video server, you can add an embed provider. A provider is a small object that does three jobs:

  1. Recognise a pasted link and pull out validated ids (match).
  2. Build the player from those ids (frame).
  3. Build the provider's own page from those ids (canonicalUrl).

The document stores only the provider's name and the ids. It never stores a player URL, an iframe or HTML. The player is built from the ids each time the document is shown, which is why a stored document cannot smuggle in a different iframe.

The provider shape

Prop

Type

frame() returns an EmbedFrame:

Prop

Type

A complete example

This provider embeds videos from a self-hosted PeerTube server at video.example.org. A link looks like https://video.example.org/w/<22 characters>.

lib/embed-providers.ts
import {
  builtInEmbedProviderNames,
  defineEmbedProvider,
  registerEmbedProvider,
  resolveFeatures,
} from 'post-canvas/render';

const host = 'video.example.org';
const videoId = /^[1-9A-HJ-NP-Za-km-z]{22}$/;

export const peertube = defineEmbedProvider({
  name: 'peertube',
  label: 'PeerTube',
  aspectRatio: 16 / 9,

  // Return the ids, or null when the link is not ours. Check the host exactly and every id strictly.
  match(url) {
    if (url.hostname !== host) return null;
    const found = /^\/w\/([^/]+)\/?$/.exec(url.pathname);
    return found?.[1] && videoId.test(found[1]) ? { id: found[1] } : null;
  },

  // Build the player from the ids alone.
  frame(ref) {
    return {
      src: `https://${host}/videos/embed/${ref.id}`,
      title: 'PeerTube video',
      allow: 'fullscreen; picture-in-picture',
      sandbox: 'allow-scripts allow-same-origin allow-presentation allow-popups',
      aspectRatio: 16 / 9,
      height: null,
    };
  },

  // The provider's own page. It must match() back to the same ids.
  canonicalUrl: (ref) => `https://${host}/w/${ref.id}`,

  // Optional: lets createEmbedResolver() find the title. Server only.
  oembed: (ref) => `https://${host}/services/oembed?format=json&url=${encodeURIComponent(`https://${host}/w/${ref.id}`)}`,
});

// Register it, so the editor, the sanitizer and the renderers know it. `post-canvas/render` runs in the browser and
// on the server, so this one module serves the editor page and your server routes.
registerEmbedProvider(peertube);

// The embed providers to allow: every built-in one, plus yours.
export const embedProviders = [...builtInEmbedProviderNames, 'peertube'];

// A full feature set for the server, which needs one to sanitize and render (see below).
export const features = resolveFeatures('full', { embed: { providers: embedProviders } });

Writers can now paste a PeerTube link into an empty paragraph, or use the Embed item in the Insert menu, and get a player.

The rules

defineEmbedProvider() checks the provider when you create it, and the editor checks every embed again each time it matches or renders one.

The name. It must be lower-case letters, digits and dashes, start with a letter and be at most 40 characters. It is stored in the provider attribute. You cannot reuse a built-in name (spotify, soundcloud, x, instagram, tiktok, codepen, loom, figma, google-maps, youtube, vimeo): registerEmbedProvider() throws.

What reaches match(). The link has already been parsed for you. It is http or https, has no user name or password, names no port, holds no spaces or control characters, is at most 2048 characters, and has a lower-case host. Do the rest yourself: compare the host against an exact list (not endsWith, which evil-example.org would pass) and test every id against a strict pattern.

The ids (the ref). match() returns a flat object of strings. At most 8 keys. Each key starts with a lower-case letter and is at most 20 letters or digits. Each value is 1 to 200 characters. Anything else, including a thrown error, counts as no match.

The round trip. After match(), the editor builds canonicalUrl(ref), parses that URL, runs match() on it, and accepts the embed only if the ids come out identical. An id with a slash or a query string in it fails. So canonicalUrl() and match() must agree with each other.

The frame.

  • src must be an absolute https URL. If it is not, the embed is not shown.
  • sandbox is the list of sandbox tokens for the iframe. Give the smallest set the player needs. Post Canvas cuts the list to a short allowlist (allow-scripts, allow-same-origin, allow-popups, allow-popups-to-escape-sandbox, allow-presentation, allow-forms, allow-modals, allow-orientation-lock and allow-pointer-lock), so a token such as allow-top-navigation is dropped. Do not combine allow-scripts and allow-same-origin for a page on your own origin, because that lets the framed page remove its own sandbox. For another origin, as here, the combination is what most players need.
  • The player must never live on your app's own origin. Host it on the provider's own domain. A frame on your own origin with allow-scripts allow-same-origin could lift its own sandbox.
  • allow is the iframe's permission list, written as bare feature names (fullscreen, autoplay and so on). List only what the player uses. Only playback features are kept: autoplay, clipboard-write, encrypted-media, fullscreen, picture-in-picture, web-share, accelerometer and gyroscope. The camera, the microphone and the location are never granted, and origin lists are dropped.
  • Use aspectRatio for a player that scales (width divided by height, between 0.2 and 5), and height (in pixels, up to 2000) for one that has a fixed height. Set the other one to null. A ratio outside the range falls back to 16:9.
  • Every iframe also gets referrerpolicy="strict-origin-when-cross-origin".

What the server fetches. oembed() is optional and used only by createEmbedResolver(). It must return a fixed https endpoint built from the ref, never from the pasted link. The resolver stores only the title and the aspect ratio from the answer.

Register it everywhere

A provider is registered in memory, in each JavaScript runtime that uses it. Register it in every place that edits, sanitizes or renders documents, and let each place allow its name:

PlaceImport registerEmbedProvider fromAlso pass the provider name in
The editor pagepost-canvas, post-canvas/render or post-canvas/vanillafeatures.embed.providers
The render page or routepost-canvas/server or post-canvas/renderfeatures of renderToHTML()
The save routepost-canvas/serverfeatures of validateDocument() or sanitizeDocument()
The embed resolver routepost-canvas/serverproviders of createEmbedResolver(), if you set it

A module that registers the provider and exports the list, like the one above, keeps this in one place. Import it in the editor and on the server:

app/editor.tsx
'use client';
import { PostCanvas } from 'post-canvas';
import { embedProviders } from '@/lib/embed-providers';

const features = { embed: { providers: embedProviders } };

export function Editor() {
  return <PostCanvas features={features} />;
}

Pass only the embed key to the editor, as above. features on PostCanvas changes the preset's features, and a complete feature set would also switch on media features that need an upload adapter.

app/api/posts/route.ts
import { validateDocument } from 'post-canvas/server';
import { features } from '@/lib/embed-providers';

export async function POST(request: Request) {
  const { content } = await request.json();
  const { ok, errors } = validateDocument(content, { features });
  if (!ok) return Response.json({ errors }, { status: 422 });
  // Store content.
  return Response.json({ saved: true });
}
lib/render-post.ts
import type { JSONContent } from 'post-canvas';
import { renderToHTML } from 'post-canvas/server';
import { features } from '@/lib/embed-providers';

export const renderPost = (content: JSONContent) => renderToHTML(content, { features });

Without the provider's name in features.embed.providers, the sanitizer removes the embed, on the server and in the editor. If you use a preset other than full, pass the same preset to resolveFeatures() that you pass to PostCanvas, so both sides allow the same blocks.

resolveFeatures and builtInEmbedProviderNames are exported from post-canvas, post-canvas/server and post-canvas/render, so a server file builds its features from the entry it already imports.

From a CDN page

post-canvas/vanilla and the CDN global export defineEmbedProvider and registerEmbedProvider. Register the provider before you create the editor, and list the built-in names you want next to yours (the CDN global has no builtInEmbedProviderNames):

<script>
  const peertube = PostCanvas.defineEmbedProvider({
    name: 'peertube',
    label: 'PeerTube',
    aspectRatio: 16 / 9,
    match: (url) => {
      const found = /^\/w\/([1-9A-HJ-NP-Za-km-z]{22})\/?$/.exec(url.pathname);
      return url.hostname === 'video.example.org' && found ? { id: found[1] } : null;
    },
    frame: (ref) => ({
      src: 'https://video.example.org/videos/embed/' + ref.id,
      title: 'PeerTube video',
      allow: 'fullscreen',
      sandbox: 'allow-scripts allow-same-origin allow-presentation',
      aspectRatio: 16 / 9,
      height: null,
    }),
    canonicalUrl: (ref) => 'https://video.example.org/w/' + ref.id,
  });
  PostCanvas.registerEmbedProvider(peertube);

  PostCanvas.create(document.getElementById('editor'), {
    features: { embed: { providers: ['spotify', 'soundcloud', 'peertube'] } },
  });
</script>

On a page that only shows saved posts, register the provider before you call PostCanvas.activateEmbeds(container), so its facades can become players.

Limits

  • A custom provider has no thumbnail in the facade unless you define thumbnail(ref). It must return a URL built from the ref. That host then gets an image request from any page that shows the facade.
  • Providers that need a server lookup to find the real address, like Google Maps short links, cannot be matched, because match() has no network access. Those links become link cards.

On this page