TourMedia

TourMedia component: unified media embed with automatic platform detection from URL — YouTube, Vimeo, Loom, or native video

Overview

TourMedia is the primary component for embedding media in your tours. It automatically detects the platform from the URL and renders the appropriate embed with accessibility features built-in.

Why Use TourMedia?

Auto-detection: Pass any video URL and it figures out the platform
Unified API: Same props work across YouTube, Vimeo, Loom, Wistia, and native video
Accessibility first: Respects prefers-reduced-motion, supports captions
Responsive: Adapts to different screen sizes automatically
Type-safe: Full TypeScript support with intelligent prop validation

Basic Usage

Automatic Platform Detection

Simply pass a URL and TourMedia detects the platform:

import { TourMedia } from '@tour-kit/media'

export function YouTubeExample() {
  return (
    <TourMedia
      src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
      alt="Product walkthrough"
    />
  )
}

export function VimeoExample() {
  return (
    <TourMedia
      src="https://vimeo.com/123456789"
      alt="Feature showcase"
    />
  )
}

export function LoomExample() {
  return (
    <TourMedia
      src="https://www.loom.com/share/abc123"
      alt="Screen recording"
    />
  )
}

Native Video

For self-hosted videos, provide the direct file path:

<TourMedia
  src="/videos/demo.mp4"
  alt="Feature demonstration"
  poster="/thumbnails/demo.jpg"
  controls
/>

Manual Type Override

You can explicitly set the media type if auto-detection fails:

<TourMedia
  src="custom-video-url"
  type="vimeo"
  alt="Custom video"
/>

Props

Prop

Type

Examples

YouTube with Autoplay

Most browsers require videos to be muted for autoplay to work:

<TourMedia
  src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  alt="Welcome to our platform"
  autoplay
  muted
  loop
/>

Vimeo with Custom Aspect Ratio

Use square or vertical aspect ratios for mobile-first designs:

<TourMedia
  src="https://vimeo.com/123456789"
  alt="Mobile app demo"
  aspectRatio="9/16"
  size="sm"
/>

Native Video with Captions

Provide accessibility for hearing-impaired users:

<TourMedia
  src="/videos/tutorial.mp4"
  alt="Feature tutorial"
  poster="/thumbnails/tutorial.jpg"
  captions={[
    {
      src: '/captions/en.vtt',
      srcLang: 'en',
      label: 'English',
      default: true
    },
    {
      src: '/captions/es.vtt',
      srcLang: 'es',
      label: 'Español'
    }
  ]}
  controls
  preload="metadata"
/>

Start at Specific Time

Jump to a specific moment (supported by YouTube, Vimeo, native video):

<TourMedia
  src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  alt="Feature deep dive"
  startTime={90} // Start at 1:30
/>

Responsive Video Sources

Serve optimized videos based on screen size:

<TourMedia
  src="/videos/demo-desktop.mp4"
  alt="Product demo"
  sources={[
    { src: '/videos/demo-mobile.mp4', maxWidth: 640 },
    { src: '/videos/demo-tablet.mp4', maxWidth: 1024 },
    { src: '/videos/demo-desktop.mp4', maxWidth: Infinity }
  ]}
  poster="/thumbnails/demo.jpg"
/>

Reduced Motion Fallback

Respect user motion preferences with a static fallback:

<TourMedia
  src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  alt="Animated feature showcase"
  reducedMotionFallback="/images/feature-screenshot.jpg"
/>

When prefers-reduced-motion: reduce is set, the static image displays instead of the video.

Lottie Animation

Display vector animations (requires lottie-web peer dependency):

<TourMedia
  type="lottie"
  src="/animations/success.json"
  alt="Success celebration animation"
  autoplay
  loop
  lottieOptions={{
    renderer: 'svg',
    loop: true,
    autoplay: true
  }}
/>

GIF with Play/Pause Controls

Show animated GIFs with user-controlled playback:

<TourMedia
  type="gif"
  src="/animations/feature-demo.gif"
  alt="Feature demonstration"
  poster="/images/feature-poster.jpg"
  aspectRatio="16/9"
/>

Accessibility

Required Alt Text

Always provide meaningful alt text describing the media content:

// Good
<TourMedia
  src="video.mp4"
  alt="Walkthrough of creating your first project"
/>

// Bad
<TourMedia
  src="video.mp4"
  alt="Video"
/>

Captions for Native Video

Include captions for all spoken content:

<TourMedia
  src="/videos/tutorial.mp4"
  alt="Account setup tutorial"
  captions={[
    { src: '/captions/en.vtt', srcLang: 'en', label: 'English', default: true }
  ]}
/>

WebVTT (.vtt) is the standard format for captions. Most video editing tools can export to VTT.

Motion Sensitivity

Always provide a static fallback for users who prefer reduced motion:

<TourMedia
  src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  alt="Animated dashboard walkthrough"
  reducedMotionFallback="/images/dashboard-screenshot.jpg"
/>

Platform-Specific Features

YouTube

Automatically uses youtube-nocookie.com for GDPR compliance
Supports: autoplay, muted, loop, controls, startTime
See YouTubeEmbed for YouTube-specific props

Vimeo

Professional video hosting with privacy controls
Supports: autoplay, muted, loop, startTime
See VimeoEmbed for Vimeo-specific props

Loom

Optimized for screen recordings and async video
Supports: autoplay, muted, loop, hideControls, startTime
See LoomEmbed for Loom-specific props

Wistia

Enterprise video hosting with analytics
Supports: autoplay, muted, loop, controlsVisibleOnLoad, startTime
See WistiaEmbed for Wistia-specific props

Integration with Tours

Use inside tour steps for rich onboarding experiences:

import { Tour, TourStep } from '@tour-kit/react'
import { TourMedia } from '@tour-kit/media'

<Tour id="onboarding">
  <TourStep id="welcome">
    <h2>Welcome to Our Platform</h2>
    <TourMedia
      src="https://www.youtube.com/watch?v=intro-video"
      alt="Platform introduction"
      autoplay
      muted
    />
    <p>Watch this 2-minute intro to get started</p>
  </TourStep>
</Tour>

TypeScript

Full type safety with intelligent prop validation:

import type { TourMediaConfig, MediaType } from '@tour-kit/media'

const config: TourMediaConfig = {
  src: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ',
  alt: 'Product demo',
  autoplay: true,
  muted: true,
  aspectRatio: '16/9'
}

<TourMedia {...config} />