VideoPlayer

A professional video player that supports URLs from YouTube, Vimeo, Facebook, Twitch, SoundCloud, Streamable, Wistia, DailyMotion, Mixcloud, as well as direct file URLs. It is fully responsive, offers customizable controls, and allows setting of aspect ratios, making it suitable for any site type.

Use Cases

• Product demos and walkthroughs (software, physical products, services)
• Tutorial and educational content (how-to guides, courses, training)
• Promotional videos (brand stories, commercials, announcements)
• Testimonial and case study videos (customer interviews, success stories)
• Video testimonials (authentic customer feedback)
• Explainer videos (concept explanations, value propositions)
• Course content (e-learning platforms, educational sites)
• Event recordings (webinars, conferences, presentations)
• Portfolio showcases (video production work, creative projects)
• Background videos (hero sections, immersive experiences)
• Video blogs (vlog content, personal narratives)
• Live stream embeds (Twitch broadcasts, live events)

Properties

url

Video URL from supported platforms or direct file URL. react-player supports: YouTube, Vimeo, Facebook, Twitch, SoundCloud, Streamable, Wistia, DailyMotion, Mixcloud, file URLs (.mp4, .webm, .ogv). Type: string. Required.

Tip: youtube: Best for public content. Free, unlimited bandwidth, SEO benefits.; vimeo: Best for professional/business content. Ad-free, customizable player.; self-hosted: Only use for short clips. Hosting video files is expensive and slow.

controls

Show player controls (play/pause, volume, progress bar, fullscreen). Essential for user control. Type: boolean. Default: true.

Visual Impact: true – Shows standard video controls. Users can play, pause, seek, adjust volume, go fullscreen.; false – No controls visible. Video is decorative/ambient only. Poor UX for content videos.

Tip: default: Use true for all content videos (tutorials, demos, testimonials); background: Use false only for ambient background videos (hero sections with muted autoplay).

autoplay

Start playing video automatically when page loads. Must be muted: true for most browsers to allow autoplay. Type: boolean. Default: false.

Visual Impact: true – Video plays immediately (if muted). Can grab attention but may annoy users.; false – User must click play. Better UX, respects user control.

Tip: content-videos: Use false. Let users decide when to watch (demos, tutorials, testimonials).; background-videos: Use true + muted: true for ambient hero backgrounds.; mobile: Many mobile browsers block autoplay even if muted. Don’t rely on it.

loop

Restart video from beginning when it ends. Creates continuous playback. Type: boolean. Default: false.

Visual Impact: true – Video repeats indefinitely. Good for backgrounds, animations, short clips.; false – Video plays once then stops. Standard behavior for content.

Tip: background: Use true for ambient background videos in hero sections; content: Use false for tutorials, demos, testimonials (users want control); short-clips: Use true for brief animations or product showcases (<30s).

muted

Start with audio muted. Required for autoplay to work in most browsers. Type: boolean. Default: false.

Visual Impact: true – No audio initially. User can unmute via controls if controls: true.; false – Audio plays (if autoplay: false). If autoplay: true, most browsers block it.

Tip: autoplay: Use true when autoplay: true (browsers require muted autoplay); background: Use true for decorative background videos; content: Use false for tutorials, demos, interviews where audio is essential.

playsinline

Allow video to play inline on mobile devices instead of forcing fullscreen. Critical for mobile UX. Type: boolean. Default: true.

Visual Impact: true – Video plays within page on mobile. User stays in context, better UX.; false – iOS forces fullscreen video player. Disruptive, pulls user out of page flow.

Tip: default: Always use true. Inline playback is expected modern behavior.; mobile-first: Essential for mobile-friendly sites and background videos.

thumbnail

Thumbnail image URL shown before video loads. Enables lazy loading - video doesn’t load until user clicks play. Improves page load performance. Type: string.

Tip: performance: Always use thumbnail for faster page loads. Video won’t load until clicked.; unsplash: Use search_unsplash to get relevant preview image for the video topic; youtube: YouTube videos automatically use their thumbnail if you don’t specify one; custom: For self-hosted videos, provide custom thumbnail for professional appearance.

aspectRatio

Video player aspect ratio. Determines height based on width. Type: string. Options: 16:9, 4:3, 1:1, 21:9. Default: 16:9.

Visual Impact: 16:9 – Widescreen (1920x1080). Standard for modern videos. Use for most content.; 4:3 – Traditional TV (640x480). Older videos, vintage content. Rarely used today.; 1:1 – Square (1080x1080). Social media videos, Instagram-style content.; 21:9 – Ultrawide cinematic (2560x1080). Dramatic, movie-like presentation.

Tip: default: Use 16:9 for 95% of videos (YouTube, Vimeo default to this); social: Use 1:1 for Instagram/TikTok style vertical or square videos; cinematic: Use 21:9 only for professionally produced cinematic content.

customCss

Custom CSS styles for advanced styling. Parsed as CSS property-value pairs. Applies to outermost Section container. Type: string.

Tip: Use this property to add borders, shadows, margins, or any other CSS needed for visual emphasis.

Best Practices

• Use YouTube or Vimeo for professional hosting (better than self-hosted for performance)
• Always enable controls unless creating ambient background video
• Set playsinline: true for mobile-friendly playback (prevents fullscreen takeover)
• Use 16:9 aspect ratio for most content (standard widescreen)
• Avoid autoplay with sound (poor UX, many browsers block it)
• Use thumbnail (light prop) for lazy loading and faster page load
• Provide descriptive context around video (heading + text explaining what video shows)
• Keep videos under 3-5 minutes for optimal engagement
• Use muted: true with autoplay for background/ambient videos

Common Mistakes

Using autoplay: true without muted: true

Why it's a problem: Modern browsers block autoplay with sound. Video won't play, confusing users.

Fix: Always set muted: true when using autoplay: true. Or avoid autoplay for content videos.

Not providing thumbnail for lazy loading

Why it's a problem: Video loads immediately on page load, slowing down page. Wastes bandwidth if user never watches.

Fix: Always use thumbnail property. Video loads only when user clicks play. Much faster page loads.

Using controls: false for content videos (tutorials, demos)

Why it's a problem: Users can't pause, skip, adjust volume, or go fullscreen. Terrible UX.

Fix: Only use controls: false for ambient background videos. Always true for content.

Setting playsinline: false

Why it's a problem: Forces fullscreen on mobile, pulling user out of page. Disruptive experience.

Fix: Always use playsinline: true for modern, mobile-friendly behavior.

Using self-hosted video files without CDN

Why it's a problem: Hosting video is expensive and slow. Bandwidth costs skyrocket. Poor performance.

Fix: Use YouTube or Vimeo for free, unlimited bandwidth. Reserve self-hosted for short clips only.

Not adding context around video

Why it's a problem: Users don't know what video is about. Low click-through rate, missed engagement.

Fix: Add Heading + Text above video explaining what it shows and why to watch.

Embedding 20+ minute videos on landing pages

Why it's a problem: Users won't commit to long videos on first visit. High bounce rate.

Fix: Keep videos under 3-5 minutes. Use longer videos on dedicated pages with committed audience.