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