website·Indexed 32 days ago
https://social-embed.org/A toolset for turning media URLs into embeddable content, consisting of @social-embed/lib, a zero-dependency JavaScript library for URL detection and parsing, and the <o-embed> Web Component for rendering players via a single HTML tag. It supports built-in providers such as YouTube, Vimeo, Spotify, Loom, Wistia, DailyMotion, and Edpuzzle, while allowing for custom provider registration.
<o-embed> tag. Provider detection, embed URL construction, and rendering happen automatically at render time. It is a client-side URL parser that uses static pattern matching rather than the oEmbed protocol, meaning it requires no API keys and makes no network requests for URL conversion.<o-embed> component acts as a universal embed tag. If a URL is provided that does not match any registered provider, the component validates the URL using @social-embed/lib. If it is a valid HTTP or HTTPS URL, it renders the content as a sandboxed <iframe>. This allows the component to be used for platforms that are not explicitly supported as built-in providers.<o-embed url="https://netlify.com/"></o-embed><o-embed> Web Component automatically detects media providers from a URL and renders the appropriate <iframe> player. It supports YouTube, Spotify, Vimeo, DailyMotion, Loom, EdPuzzle, and Wistia. If a URL does not match a known provider, it renders as a generic iframe fallback. The component is reactive, meaning it will re-render the embed automatically if the url attribute is changed.<script type=
@social-embed/lib package to transform a media URL into a platform-specific embed URL. This process involves three internal steps: detecting the provider via regex, extracting the media ID, and constructing the final embed URL. You can perform these steps individually or use the universal convertUrlToEmbedUrl helper.import { convertUrlToEmbedUrl, getProviderFromUrl } from "@social-embed/lib";
// Option 1: All-in-one conversion
const embedUrl = convertUrlToEmbedUrl("https://youtu.be/Bd8_vO5zrjo");
// Result: "https://www.youtube.com/embed/Bd8_vO5zrjo"
// Option 2: Step-by-step control
const provider = getProviderFromUrl("https://youtu.be/Bd8_vO5zrjo");
if (provider) {
const id = provider.getIdFromUrl("https://youtu.be/Bd8_vO5zrjo");
const finalUrl = provider.getEmbedUrlFromId(id);
}EmbedProvider interface and registering it with the defaultRegistry. This allows convertUrlToEmbedUrl to support your custom service.import { defaultRegistry, EmbedProvider } from "@social-embed/lib";
export const MyCustomProvider: EmbedProvider = {
name: "MyCustom",
canParseUrl(url: string): boolean {
return /mycustom\.example\.com\/video\//.test(url);
},
getIdFromUrl(url: string): string {
return url.split("/").pop() || "";
},
getEmbedUrlFromId(id: string): string {
return `https://mycustom.example.com/embed/${id}`;
},
};
// Register the provider
defaultRegistry.register(MyCustomProvider);
// Now it works with the universal converter
console.log(convertUrlToEmbedUrl("https://mycustom.example.com/video/xyz123"));
// "https://mycustom.example.com/embed/xyz123"url attribute is required and accepts URLs from supported providers. The component automatically detects the provider and extracts the media ID. This includes support for standard media URLs and YouTube playlist URLs.<!-- Standard YouTube embed -->
<o-embed url="https://youtu.be/FTQbiNvZqaY"></o-embed>
<!-- YouTube playlist embed -->
<o-embed url="https://youtu.be/FTQbiNvZqaY?list=RDCLAK5uy_lf8okgl2ygD075nhnJVjlfhwp8NsUgEbs"></o-embed>Because <o-embed> is a Web Component, it requires JavaScript to render the iframe. If JavaScript is disabled or has not yet loaded, the element is treated as an unknown HTML element and only the content within the <slot> (child elements) is visible.
There are two primary strategies for fallbacks:
<o-embed> tag. This link is visible before JS loads and remains visible after the embed renders.<noscript> tag alongside the component for static HTML contexts where JS will never load.<!-- Strategy 1: Slot content (visible before and after JS) -->
<o-embed url="https://youtu.be/Bd8_vO5zrjo">
<a href="https://youtu.be/Bd8_vO5zrjo">Watch on YouTube</a>
</o-embed>
<!-- Strategy 2: Noscript block (only visible if JS is disabled) -->
<o-embed url="https://youtu.be/Bd8_vO5zrjo"></o-embed>
<noscript>
<a href="https://youtu.be/Bd8_vO5zrjo">Watch on YouTube (requires JavaScript)</a>
</noscript>getProviderFromUrl utility from @social-embed/lib during server-side validation.import { getProviderFromUrl } from "@social-embed/lib";
function validateEmbedUrl(url: string): boolean {
const provider = getProviderFromUrl(url);
return provider !== undefined; // Only allow recognized providers
}