Skip to main content

Overview

@social-embed/lib is a repository of patterns and parsers for embed-friendly websites. You can use it in your web apps and scripts. It also powers the project's <o-embed> web component.

Supported embeds​

See src/providers for the full manifest of supported content. As of 2021-04-21, it includes at least:

  • DailyMotion
  • Spotify
  • Vimeo
  • YouTube

Usecases​

  • Detecting if a URL is embeddable

    • Detecting subtle variations: https://youtu.be/watch?v=Bd8_vO5zrjo, https://www.youtube.com/watch?v=Bd8_vO5zrjo

  • Extracting IDs from embed-friendly sites, e.g. Bd8_vO5zrjo out of https://youtu.be/watch?v=Bd8_vO5zrjo

  • Creating embed friendly URLs: https://youtu.be/watch?v=Bd8_vO5zrjo -> https://www.youtube.com/embed/Bd8_vO5zrjo

    To see this concept in action see Wistia's Construct a Wistia Embed Code page.

  • Avoid the repetition. StackOverflow, Regex websites detecting embed URLs

    (google search: youtube regex site:stackoverflow.com)

Similar projects: js-video-url-parser

Usage​

Internal API naming​

warning

These naming conventions aren't stable yet and are subject to change

  • Provider: String enum of supported embeds.
  • ${providerName}Regex: Name for JS regular expressions
  • get${providerName}IdFromUrl: Extracts ID from URLs (various formats), e.g.
    • 'https://youtu.be/watch?v=Bd8_vO5zrjo' -> 'Bd8_vO5zrjo'
    • 'https://www.youtube.com/watch?v=Bd8_vO5zrjo' -> 'Bd8_vO5zrjo'
  • get${providerName}EmbedUrlFromId: Turns ID into embed-friendly URL, e.g.
    • 'Bd8_vO5zrjo' -> "https://www.youtube.com/embed/Bd8_vO5zrjo"

Regular expressions​

import { getYouTubeIdFromUrl, youTubeUrlRegex } from "@social-embed/lib";

"https://youtu.be/watch?v=Bd8_vO5zrjo".match(youTubeUrlRegex);
// ["https://youtu.be/watch?v=Bd8_vO5zrjo","Bd8_vO5zrjo"]

Detect provider (e.g. YouTube) from URL​

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

const provider = getProviderFromUrl("https://youtu.be/watch?v=Bd8_vO5zrjo");
// YouTube

Get IDs from URLs​

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

const provider = getProviderFromUrl("https://youtu.be/watch?v=Bd8_vO5zrjo"); // YouTube

if (provider) {
  const getId = ProviderIdFunctionMap[provider];
  getId("https://youtu.be/watch?v=Bd8_vO5zrjo");
  // "Bd8_vO5zrjo"
}

Get iframe friendly URL​

import {
  getYouTubeEmbedUrlFromId,
  getYouTubeIdFromUrl,
} from "@social-embed/lib";

const embedId = getYouTubeIdFromUrl("https://youtu.be/watch?v=Bd8_vO5zrjo"); // "Bd8_vO5zrjo"

const embedFriendlyUrl = getYouTubeEmbedUrlFromId(
  "https://youtu.be/watch?v=Bd8_vO5zrjo",
); // "https://www.youtube.com/embed/Bd8_vO5zrjo"

The above embed URL can fit right into an <iframe>:

<iframe src="https://www.youtube.com/embed/Bd8_vO5zrjo"></iframe>

This is what the <o-embed> web component uses under the hood to render embeds.

Try​

See also​

  • Installation

    npm i @social-embed/lib
    yarn add @social-embed/lib