Getting Started

Install the package

pnpm add embed-card

Not sure which hosts or URL shapes are supported? Read Supported platforms → (YouTube, X, Instagram, Reddit threads, Google Maps, Vimeo, TikTok, link fallback, and invalid input).

React usage

import { EmbedCard } from "embed-card"

export function ArticleEmbed() {
  return (
    <EmbedCard url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" />
  )
}

Interactive playground

You can try links without wiring up a project first:

• Docs: Playground — paste a URL or pick a sample, watch the preview update, then copy the generated snippet from the code block (the same flow as on the site home page under Playground).

The snippet shows the minimal EmbedCard usage with url only. The live preview uses ThemedEmbedCard from embed-card/next-themes so it follows this docs site's light/dark toggle; copy-paste code stays the smallest API. Optional styling and light/dark still use the theme prop, as in the next section (or ThemedEmbedCard when you use next-themes in your app).

Theme the card

theme fields are all optional, including shadow. If you leave shadow out, the package applies no drop shadow; pass a string when you want a custom box-shadow (for example a soft glow in the accent color).

import { EmbedCard } from "embed-card"

export function BrandedArticleEmbed() {
  return (
    <EmbedCard
      url="https://vimeo.com/76979871"
      theme={{
        accentColor: "#e11d48",
        radius: 28,
      }}
    />
  )
}

With an optional drop shadow (you do not need to pass shadow: "none" to disable it—omitting the field is enough):

<EmbedCard
  url="https://vimeo.com/76979871"
  theme={{
    accentColor: "#e11d48",
    radius: 28,
    shadow: "0 28px 100px rgba(225, 29, 72, 0.18)",
  }}
/>

The no-shadow default is also exported as EMBED_CARD_DEFAULT_SHADOW from embed-card if you need it in your own theming code.

Dark mode

Pass appearance to control whether the embed surface uses a light or dark palette:

<EmbedCard
  url="https://vimeo.com/76979871"
  theme={{ appearance: "dark" }}
/>

Match the site theme (next-themes)

If the app already uses next-themes (for example with Fumadocs or Next.js), install it in your project and use the package wrapper instead of reimplementing theme detection:

pnpm add next-themes

import { ThemedEmbedCard } from "embed-card/next-themes"

export function ArticleEmbed() {
  return <ThemedEmbedCard url="https://www.youtube.com/watch?v=dQw4w9WgXcQ" />
}

ThemedEmbedCard accepts the same props as EmbedCard. If you set theme.appearance to "light", "dark", or "system", that value still overrides the site theme from next-themes.

To wire EmbedCard manually with useTheme(), see Custom Rendering → Dark mode and appearance.

Starter projects (full apps)

The repository ships complete minimal apps under examples/, similar in spirit to the Next.js examples collection. Each folder is a standalone project you can copy or clone:

From the monorepo root, after pnpm install, you can run checks that include every example (pnpm build, pnpm typecheck). To run one example’s dev server on its own:

cd examples/next-app   # or another folder
pnpm install
pnpm dev

To copy a single example out of the repo (requires degit):

npx degit 1chooo/embed-card/examples/next-app my-embed-app
cd my-embed-app
pnpm install
pnpm dev

Browse the same paths on GitHub: github.com/1chooo/embed-card/tree/main/examples.

Repo layout

apps/
  web/          -> docs site + playground (URL samples, preview, copy snippet)
packages/
  embed-card/   -> publishable library
  ui/           -> shared UI (internal to this monorepo)
examples/
  next-app/     -> Next.js starter
  vite-react/   -> Vite + React starter
  vue-vite/     -> Vite + Vue starter
  svelte-vite/  -> Vite + Svelte starter
  vanilla-vite/ -> Vite + vanilla TS starter