VimeoEmbed

VimeoEmbed component: embed Vimeo videos with privacy controls, custom colors, autoplay options, and responsive sizing

Overview

VimeoEmbed provides a clean, professional way to embed Vimeo videos in your tours and announcements. Vimeo offers ad-free playback, privacy controls, and high-quality video hosting ideal for product demos and tutorials.

Why Use VimeoEmbed?

Ad-free: No pre-roll ads interrupt your onboarding flow
Professional quality: High-quality video playback and encoding
Privacy controls: Password protection and domain-level privacy
Clean player: Minimal, customizable player design
Analytics: Built-in engagement metrics (Vimeo Plus and above)

Basic Usage

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

export function ProductDemo() {
  return (
    <VimeoEmbed
      videoId="123456789"
      title="Product walkthrough"
    />
  )
}

Props

Prop

Type

Examples

Auto-playing Demo Video

<VimeoEmbed
  videoId="123456789"
  title="Feature demonstration"
  autoplay
  muted
  loop
/>

Clean Minimal Player

Hide Vimeo branding and metadata for a focused experience:

<VimeoEmbed
  videoId="123456789"
  title="Product tour"
  showTitle={false}
  showByline={false}
  showPortrait={false}
/>

Custom Player Color

Match your brand colors:

<VimeoEmbed
  videoId="123456789"
  title="Branded demo"
  color="6366f1" // Indigo-500
/>

The color prop expects a hex color without the # symbol. For example, use "ff0000" instead of "#ff0000".

Start at Specific Time

Jump directly to the relevant section:

<VimeoEmbed
  videoId="123456789"
  title="Advanced features walkthrough"
  startTime={120} // Start at 2:00
/>

Vertical Video for Mobile

Perfect for mobile app demos shot in portrait mode:

<VimeoEmbed
  videoId="123456789"
  title="Mobile app onboarding"
  aspectRatio="9/16"
  size="sm"
  rounded="lg"
/>

Use 1:1 aspect ratio for social media style content:

<VimeoEmbed
  videoId="123456789"
  title="Quick tip"
  aspectRatio="1/1"
  size="md"
/>

Full-Width Hero Video

<VimeoEmbed
  videoId="123456789"
  title="Platform overview"
  size="full"
  aspectRatio="21/9"
  autoplay
  muted
  loop
  showTitle={false}
  showByline={false}
  showPortrait={false}
/>

Extracting Video IDs

Vimeo URLs are simple - the ID is the number at the end:

import { extractVimeoId, isVimeoUrl } from '@tour-kit/media'

const url = 'https://vimeo.com/123456789'

if (isVimeoUrl(url)) {
  const videoId = extractVimeoId(url)
  return <VimeoEmbed videoId={videoId} title="Video" />
}

Supported URL formats:

https://vimeo.com/123456789
https://player.vimeo.com/video/123456789
https://vimeo.com/channels/staffpicks/123456789

Privacy Controls

Vimeo offers several privacy options configured at the video level (not in the embed):

Domain-Level Privacy

Restrict where your video can be embedded:

Go to video settings on vimeo.com
Privacy → "Where can this be embedded?"
Add allowed domains

This prevents unauthorized embedding while still allowing your tour embeds.

Password Protection

Protect sensitive training videos:

Set a password in video privacy settings
Share password with authorized users only
Embed still works for users who know the password

Hide from Vimeo.com

Keep videos unlisted but embeddable:

Privacy → "Hide from vimeo.com"
Video won't appear in search or your profile
Embed links still work

Privacy settings are configured on Vimeo's website, not via embed parameters. The VimeoEmbed component respects whatever settings you've configured.

Accessibility

Required Title Prop

Provide descriptive titles for screen reader users:

// Good - describes the content
<VimeoEmbed
  videoId="123456789"
  title="Tutorial: Setting up two-factor authentication"
/>

// Bad - too generic
<VimeoEmbed
  videoId="123456789"
  title="Video"
/>

Captions

Add captions to your Vimeo videos for accessibility:

Upload a caption file (VTT, SRT, SCC, etc.) on vimeo.com
Captions automatically display in the embedded player
Users can toggle captions via the CC button

Vimeo player includes keyboard shortcuts:

Space - Play/Pause
Left/Right arrows - Seek backward/forward 5 seconds
Up/Down arrows - Volume up/down
F - Fullscreen
M - Mute/Unmute

Getting Thumbnails

Fetch video thumbnails for loading states or fallbacks:

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

const thumbnailUrl = await getVimeoThumbnailUrl('123456789')

// Use as poster image
<img src={thumbnailUrl} alt="Video thumbnail" />

getVimeoThumbnailUrl makes an API call to Vimeo's oEmbed endpoint. Consider caching the result or fetching at build time.

Integration with Tours

Embed professional demos in your onboarding flow:

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

<Tour id="product-tour">
  <TourStep id="intro">
    <h2>Welcome to Our Platform</h2>
    <VimeoEmbed
      videoId="123456789"
      title="Platform overview"
      autoplay
      muted
      showTitle={false}
      showByline={false}
    />
  </TourStep>

  <TourStep id="advanced">
    <h2>Power User Features</h2>
    <VimeoEmbed
      videoId="987654321"
      title="Advanced features guide"
      startTime={60}
    />
  </TourStep>
</Tour>

TypeScript

Full type safety with autocompletion:

import type { VimeoEmbedProps } from '@tour-kit/media'

const config: VimeoEmbedProps = {
  videoId: '123456789',
  title: 'Product demo',
  autoplay: true,
  muted: true,
  color: '6366f1',
  showTitle: false
}

<VimeoEmbed {...config} />

Building Custom Embed URLs

For advanced use cases, construct Vimeo embed URLs manually:

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

const embedUrl = buildVimeoEmbedUrl('123456789', {
  autoplay: true,
  muted: true,
  loop: true,
  color: 'ff0000',
  title: false,
  byline: false
})

console.log(embedUrl)
// https://player.vimeo.com/video/123456789?autoplay=1&muted=1&loop=1&color=ff0000&title=0&byline=0

Vimeo vs YouTube

When to choose Vimeo over YouTube:

Choose Vimeo when:

You need ad-free playback
Professional appearance is important
Privacy controls are required
You want detailed analytics (with paid plan)
Hosting internal/training videos

Choose YouTube when:

Content is public marketing material
SEO and discoverability matter
You want to leverage YouTube's audience
Free hosting is essential