Skip to main content

TikTokPlayer

Embeds a TikTok video in a 9:16 player with basic fullscreen handling and robust URL parsing.

Example structures​

Basic​

{
  "type": "TikTokPlayer",
  "data": {
    "headline": "Check this out!",
    "url": "https://www.tiktok.com/...."
  }
}

With host notes​

{
  "type": "TikTokPlayer",
  "data": {
    "url": "https://www.tiktok.com/...."
  },
  "hostdata": {
    "notes": "🎬 After the video, show the discussion slide."
  }
}

Properties​

data.url (string, required) A TikTok URL containing the numeric post ID. The component extracts the ID and builds a player URL.

data.headline (string, optional) Title text for higher-level slide wrappers. The component itself does not render it.

hostdata.notes (string, optional) Facilitator notes visible only to the host UI. Not consumed by the component.

Supported URL forms​

The component attempts to extract the numeric post ID from these patterns:

  • https://www.tiktok.com/@user/video/123...
  • https://www.tiktok.com/video/123...
  • https://www.tiktok.com/embed/123...
  • https://www.tiktok.com/player/v1/123...
  • Fallback: the last numeric chunk of the path (\d{8,})

Short links like vt.tiktok.com/... or vm.tiktok.com/... do not contain the ID. Resolve them server-side or paste the canonical URL.

Visual design​

  • Centered player in a 9:16 aspect-[9/16] container.
  • Black background filling the remaining space.
  • Optional “fake fullscreen” sizing via a CSS class (coverFullscreen) when native fullscreen is active.

Behavior​

Player source​

  • The iframe src is built as: https://www.tiktok.com/player/v1/{VIDEO_ID}?controls=1
  • The component does not add start time or other player parameters.

Fullscreen handling​

  • Listens to the fullscreenchange event and mirrors it to internal state.
  • Displays a subtle clickable square in the bottom-right when the document is in native fullscreen; clicking toggles the component’s coverFullscreen class (layout-only) and does not exit OS/browser fullscreen.
  • F11 toggling is not reliably detectable across browsers.

Fallback​

  • If the ID cannot be parsed, the component renders a direct link button (“Open on TikTok”) that opens the provided URL in a new tab.

Permissions​

  • The iframe includes allow="autoplay; clipboard-write; encrypted-media; picture-in-picture; web-share; fullscreen" and allowFullScreen.

Use cases​

  • Show a short, vertical-format clip during a workshop segment.
  • Insert a TikTok example between activities with facilitator notes in hostdata.
  • Curate multiple TikTok nodes in sequence for media analysis.

Technical notes​

  • Props:

    interface Props {
      workshop: WorkshopPayload;
      node: NodePayload; // node.nodeData: { url: string; headline?: string }
    }

  • ID extraction (simplified overview):

    1. /@user/video/(\d+) or /video/(\d+)
    2. /embed/(\d+) or /player/v1/(\d+)
    3. Fallback: last \d{8,} in the path

  • The component does not use data.headline itself; render it in your surrounding slide layout if needed.

  • No special host/participant branching inside the component; navigation is handled by the standard node controls.

tip
  • Private, region-locked, or removed videos will not play in the embedded player.
  • Short links must be resolved to a canonical URL that includes the numeric post ID.
  • Only controls=1 is set; features like autoplay, mute, or custom controls would require extending the implementation.