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}
  />
)}

Gallery Layout

<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