Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

@simpledotstudio/simple-media-preview

simpledotstudio47MIT2.0.0-alpha.4TypeScript support: included

SimpleMediaPreview - A reusable React component

react, component, media-preview, ui

readme

SimpleMediaPreview

A versatile media preview component that supports images, videos, and audio files with custom playback controls.

Installation

npm install @simpledotstudio/simple-media-preview

Usage

import { SimpleMediaPreview } from '@simpledotstudio/simple-media-preview';

// Image preview
<SimpleMediaPreview
  src="image.jpg"
  alt="Mountain landscape"
/>

// Video with controls
<SimpleMediaPreview
  src="video.mp4"
  alt="Demo video"
  thumbnail="poster.jpg"
/>

// Audio with thumbnail
<SimpleMediaPreview
  src="audio.mp3"
  alt="My favorite song"
  thumbnail="album-cover.jpg"
/>

// File upload preview
<SimpleMediaPreview
  src={fileObject}
  alt={fileObject.name}
/>

Props

Prop Type Default Description
src string | File - The media source URL or File object (required)
alt string 'Media preview' Alternative text for images or display name for audio
type 'image' | 'video' | 'audio' | 'unknown' Auto-detected Type of media
controls boolean true Show controls for video/audio
autoplay boolean false Autoplay video/audio (muted for video)
loop boolean false Loop video/audio playback
thumbnail string - Thumbnail URL for video/audio
aspectRatio '16/9' | '4/3' | '1/1' | '9/16' | 'auto' 'auto' Aspect ratio for responsive sizing
width number | string - Width of the media container
height number | string - Height of the media container
loading boolean false Show loading state
className string '' Additional CSS class name
onError (error: Error) => void - Error handler
onClick () => void - Click handler
onPlayStateChange (playing: boolean) => void - Play state change handler

Features

Auto-Detection

The component automatically detects media type from:

  • File extensions (.jpg, .mp4, .mp3, etc.)
  • MIME types for File objects
  • Can be overridden with the type prop

Image Support

  • Displays images with proper aspect ratio
  • Loading and error states
  • Click handling

Video Features

  • Custom play/pause button with SimpleIconButton
  • Time display (current/duration)
  • Thumbnail/poster support
  • Autoplay and loop options
  • Muted autoplay for browser compatibility

Audio Features

  • Custom play/pause controls
  • Album art/thumbnail display
  • Time tracking
  • Compact player design

File Upload

  • Direct support for File objects
  • Automatic cleanup of object URLs
  • Preview before upload

Examples

Basic Image

<SimpleMediaPreview
  src="https://example.com/photo.jpg"
  alt="Vacation photo"
/>

Video with Custom Size

<SimpleMediaPreview
  src="video.mp4"
  aspectRatio="16/9"
  width={800}
/>

Audio Player

<SimpleMediaPreview
  src="podcast.mp3"
  alt="Episode 42: React Patterns"
  thumbnail="podcast-cover.jpg"
/>

File Upload with Preview

const [file, setFile] = useState(null);

<input
  type="file"
  accept="image/*,video/*,audio/*"
  onChange={(e) => setFile(e.target.files[0])}
/>

{file && (
  <SimpleMediaPreview
    src={file}
    alt={file.name}
  />
)}
<div style={{ display: 'grid', gridTemplateColumns: 'repeat(3, 1fr)', gap: '16px' }}>
  <SimpleMediaPreview src="photo1.jpg" aspectRatio="1/1" />
  <SimpleMediaPreview src="video.mp4" aspectRatio="1/1" />
  <SimpleMediaPreview src="audio.mp3" aspectRatio="1/1" />
</div>

With Event Handlers

<SimpleMediaPreview
  src="video.mp4"
  onPlayStateChange={(playing) => {
    console.log(playing ? 'Playing' : 'Paused');
  }}
  onError={(error) => {
    console.error('Media failed to load:', error);
  }}
  onClick={() => {
    console.log('Media clicked');
  }}
/>

Styling

The component uses CSS modules with customizable CSS variables:

/* Available CSS variables */
--color-background: #f5f5f5;
--color-error-light: #fef2f2;
--radius-medium: 8px;
--spacing-small: 8px;
--spacing-medium: 16px;
--spacing-large: 24px;
--font-size-small: 14px;

Browser Support

  • Modern browsers with ES6 support
  • File API for file uploads
  • HTML5 video/audio elements

Dependencies

  • @simpledotstudio/simple-image - For image display
  • @simpledotstudio/simple-icon-button - For playback controls
  • @simpledotstudio/simple-loader - For loading states
  • @simpledotstudio/simple-text - For text display

Development

To run the component in development mode:

npm run storybook

To run tests:

npm run test

To lint the component:

npm run lint