Getting started

social-embed turns media URLs into embeddable content. Instead of storing platform-specific iframe HTML, you store one portable tag:

<!-- What you used to store -->
<iframe width="560" height="315"
  src="https://www.youtube.com/embed/Bd8_vO5zrjo"
  frameborder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media"
  allowfullscreen></iframe>

<!-- What you store now -->
<o-embed url="https://www.youtube.com/watch?v=Bd8_vO5zrjo"></o-embed>

The URL is the canonical data. Provider detection, embed URL construction, and rendering happen automatically at render time. See How it works for the full pipeline.

Note: <o-embed> requires JavaScript to render. For resilience in non-JS contexts, add a fallback link:

<o-embed url="https://youtu.be/Bd8_vO5zrjo">
  <a href="https://youtu.be/Bd8_vO5zrjo">Watch on YouTube</a>
</o-embed>

Have 30 seconds?#

Add one script tag and one <o-embed> element — that’s it:

<script type="module" src="https://unpkg.com/@social-embed/wc?module"></script>

<o-embed url="https://youtu.be/Bd8_vO5zrjo"></o-embed>

No build step, no bundler, no framework.

Which package do I need?#

Building something?#

Install the web component for drop-in embedding:

npm i @social-embed/wc

pnpm add @social-embed/wc

yarn add @social-embed/wc

Then import and use:

import "@social-embed/wc";

<o-embed url="https://www.youtube.com/watch?v=Bd8_vO5zrjo"></o-embed>

See the web component docs for attributes and styling, framework setup, and per-provider examples.

Just need URL parsing?#

Use the core library for server-side validation, custom renderers, or programmatic URL handling:

npm i @social-embed/lib

pnpm add @social-embed/lib

yarn add @social-embed/lib

import { convertUrlToEmbedUrl, getProviderFromUrl } from "@social-embed/lib";

const embedUrl = convertUrlToEmbedUrl("https://youtu.be/Bd8_vO5zrjo");
// "https://www.youtube.com/embed/Bd8_vO5zrjo"

const provider = getProviderFromUrl("https://youtu.be/Bd8_vO5zrjo");
// { name: "YouTube", canParseUrl, getIdFromUrl, getEmbedUrlFromId }

See the library docs for examples and the full API.

Good to know#

social-embed is a client-side URL parser, not an oEmbed protocol client. Despite the name similarity, it does not make HTTP requests to oEmbed endpoints. It derives embed URLs locally using static pattern matching — no API keys, no server, no network requests for the URL conversion step.

It is not a security boundary. The generic fallback renders any valid URL as an iframe. If you accept user-submitted URLs, validate them server-side with getProviderFromUrl() to restrict to known providers.

Requires JavaScript to render. <o-embed> is a Web Component — it needs JS to upgrade and display the iframe. Use slot content as a fallback for non-JS contexts (see above).