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 {
getYouTubeIdFromUrl,
getYouTubeEmbedUrlFromId,
} 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#