TourKit
API Reference

@tour-kit/media API

API reference for @tour-kit/media: YouTubeEmbed, VimeoEmbed, LoomEmbed, GifPlayer, LottiePlayer, and TourMedia

@tour-kit/media API Reference

Complete API reference for the media package. This package provides video, GIF, and Lottie animation embeds.


Main Component

TourMedia

Auto-detecting media component.

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

<TourMedia
  src="https://youtube.com/watch?v=abc123"
  alt="Tutorial video"
  aspectRatio="16/9"
  autoplay={false}
  muted={true}
  controls={true}
  poster="/images/poster.jpg"
/>
PropTypeDescription
srcstringMedia source URL
altstringAlt text (required)
typeMediaTypeMedia type (auto-detected if omitted)
aspectRatiostringAspect ratio
autoplaybooleanAuto-play media
mutedbooleanMute audio
controlsbooleanShow controls
loopbooleanLoop media
playsInlinebooleanPlay inline on mobile
posterstringPoster image for video
startTimenumberStart time in seconds
captionsCaptionTrack[]Caption tracks
sourcesResponsiveSource[]Responsive sources
reducedMotionFallbackstringStatic image for reduced motion
loading'eager' | 'lazy'Loading strategy
preloadstringVideo preload strategy

Embed Components

YouTubeEmbed

YouTube iframe embed.

import { YouTubeEmbed } from '@tour-kit/media';

<YouTubeEmbed
  videoId="abc123"
  autoplay
  muted
  startTime={30}
/>
PropTypeDescription
videoIdstringYouTube video ID
autoplaybooleanAuto-play
mutedbooleanMute audio
startTimenumberStart time (seconds)
controlsbooleanShow controls

VimeoEmbed

Vimeo iframe embed.

import { VimeoEmbed } from '@tour-kit/media';

<VimeoEmbed
  videoId="123456"
  autoplay
  muted
/>

LoomEmbed

Loom iframe embed.

import { LoomEmbed } from '@tour-kit/media';

<LoomEmbed
  videoId="abc123"
  hideOwner
  hideTitle
/>

WistiaEmbed

Wistia iframe embed.

import { WistiaEmbed } from '@tour-kit/media';

<WistiaEmbed
  videoId="abc123"
  autoplay
/>

NativeVideo

HTML5 video element.

import { NativeVideo } from '@tour-kit/media';

<NativeVideo
  src="/videos/intro.mp4"
  poster="/images/poster.jpg"
  controls
  captions={[
    { src: '/captions/en.vtt', srclang: 'en', label: 'English', default: true }
  ]}
/>

GifPlayer

GIF with play/pause controls.

import { GifPlayer } from '@tour-kit/media';

<GifPlayer
  src="/images/demo.gif"
  alt="Demo animation"
  playOnHover
  showControls
/>
PropTypeDescription
srcstringGIF source URL
altstringAlt text
playOnHoverbooleanPlay on hover
showControlsbooleanShow play/pause

LottiePlayer

Lottie animation player.

import { LottiePlayer } from '@tour-kit/media';

<LottiePlayer
  src="/animations/success.json"
  loop
  autoplay
  speed={1.5}
/>
PropTypeDescription
srcstringLottie JSON URL
loopbooleanLoop animation
autoplaybooleanAuto-play
speednumberPlayback speed

Lottie requires optional peer dependency: @lottiefiles/react-lottie-player


Headless Components

import { MediaHeadless } from '@tour-kit/media/headless';

<MediaHeadless src={src} alt={alt}>
  {({
    mediaType,
    src,
    embedUrl,
    videoId,
    isPlaying,
    isLoaded,
    hasError,
    currentTime,
    duration,
    play,
    pause,
    seek,
    prefersReducedMotion,
    containerRef,
  }) => (
    <CustomMediaPlayer />
  )}
</MediaHeadless>

Hooks

useMediaEvents

Hook for media event handling.

import { useMediaEvents } from '@tour-kit/media';

const {
  ref,
  isPlaying,
  currentTime,
  duration,
} = useMediaEvents({
  onPlay: () => {},
  onPause: () => {},
  onEnded: () => {},
  onError: (error) => {},
  onTimeUpdate: (time) => {},
  onLoadedMetadata: (duration) => {},
});

usePrefersReducedMotion

Hook for motion preference.

import { usePrefersReducedMotion } from '@tour-kit/media';

const prefersReducedMotion = usePrefersReducedMotion();

useResponsiveSource

Hook for responsive source selection.

import { useResponsiveSource } from '@tour-kit/media';

const source = useResponsiveSource([
  { src: '/video-mobile.mp4', media: '(max-width: 768px)' },
  { src: '/video-desktop.mp4' },
]);

Utilities

URL Detection

import {
  parseMediaUrl,
  detectMediaType,
  isSupportedMediaUrl,
  isYouTubeUrl,
  isVimeoUrl,
  isLoomUrl,
  isWistiaUrl,
} from '@tour-kit/media';

const { type, id } = parseMediaUrl('https://youtube.com/watch?v=abc');
// { type: 'youtube', id: 'abc' }

const type = detectMediaType('/video.mp4');
// 'video'

const isSupported = isSupportedMediaUrl(url);

ID Extraction

import {
  extractYouTubeId,
  extractVimeoId,
  extractLoomId,
  extractWistiaId,
} from '@tour-kit/media';

const id = extractYouTubeId('https://youtu.be/abc123');
// 'abc123'

Embed URL Builders

import {
  buildYouTubeEmbedUrl,
  buildVimeoEmbedUrl,
  buildLoomEmbedUrl,
  buildWistiaEmbedUrl,
} from '@tour-kit/media';

const embedUrl = buildYouTubeEmbedUrl('abc123', {
  autoplay: true,
  muted: true,
  startTime: 30,
});

Thumbnail URLs

import {
  getYouTubeThumbnailUrl,
  getVimeoThumbnailUrl,
} from '@tour-kit/media';

const thumbnail = getYouTubeThumbnailUrl('abc123');
// https://img.youtube.com/vi/abc123/maxresdefault.jpg

Responsive Source

import { selectResponsiveSource } from '@tour-kit/media';

const source = selectResponsiveSource(sources, window.innerWidth);

Supported Media Types

TypeExtensions/Patterns
youtubeyoutube.com, youtu.be
vimeovimeo.com, player.vimeo.com
loomloom.com
wistiawistia.com, fast.wistia.net
video.mp4, .webm, .ogg
gif.gif
lottie.json (Lottie animations)
image.jpg, .png, .webp, etc.

Types

MediaType

type MediaType =
  | 'youtube'
  | 'vimeo'
  | 'loom'
  | 'wistia'
  | 'video'
  | 'gif'
  | 'lottie'
  | 'image';

TourMediaConfig

interface TourMediaConfig {
  src: string;
  type?: MediaType;
  alt: string;
  poster?: string;
  aspectRatio?: '16/9' | '4/3' | '1/1' | '9/16' | '21/9' | 'auto';
  autoplay?: boolean;
  muted?: boolean;
  controls?: boolean;
  loop?: boolean;
  playsInline?: boolean;
  startTime?: number;
  captions?: CaptionTrack[];
  sources?: ResponsiveSource[];
  lottieOptions?: LottieOptions;
  reducedMotionFallback?: string;
  loading?: 'eager' | 'lazy';
  preload?: 'none' | 'metadata' | 'auto';
}

CaptionTrack

interface CaptionTrack {
  src: string;
  srclang: string;
  label: string;
  default?: boolean;
}

ResponsiveSource

interface ResponsiveSource {
  src: string;
  media?: string;
  type?: string;
}

On this page