Media Library - Web Stories for WordPress

The Web Stories editor provides comprehensive media management through WordPress media library integration. Upload, organize, and insert images, videos, and audio files into your stories.

Media Pane

The Media pane is located in the left sidebar library and provides access to all your media assets.

Accessing Media

Open the Media pane by:

Clicking the Media tab in the library panel
Using keyboard shortcuts
The pane ID is PANE_IDS.Media

Reference: packages/story-editor/src/components/library/panes/media/

Media Types

The editor supports multiple media types:

Images
Videos
Audio

Supported formats: JPEG, PNG, GIF, WebPImages can be:

Uploaded from your computer
Selected from WordPress media library
Inserted via hotlink URL
Used as page backgrounds or elements

Images are automatically optimized for web delivery.

Supported formats: MP4, WebMVideo features:

Automatic poster generation
Trim and crop tools
Video optimization prompts
Captions support
Background video option

Reference: packages/story-editor/src/components/videoTrim/

Supported formats: MP3, AACAudio can be:

Page background audio
Audio stickers for decoration
Narration tracks

Reference: packages/story-editor/src/components/panels/design/pageBackgroundAudio/

Uploading Media

Upload Button

Upload media through the Media Upload Button:

<MediaUploadButton
  onInsert={handleInsert}
  buttonInsertText="Upload Media"
  type={allowedTypes}
/>

Reference: packages/story-editor/src/components/library/panes/media/local/mediaPane.js:38-42

Drag and Drop

Drop files directly into the editor:

Prepare files

Select image or video files from your computer.

Drag to editor

Drag files over the canvas or media pane.

Drop to upload

Release to start upload. Files are automatically processed.

Insert to canvas

Uploaded media appears in the library and can be added to pages.

Reference: packages/story-editor/src/components/canvas/canvasUploadDropTarget.js

Hotlink Insertion

Insert media from external URLs:

<LinkInsertion />

Provide a URL to an image or video, and it will be imported into your media library. Reference: packages/story-editor/src/components/library/panes/media/local/hotlink/

WordPress Media Library Integration

The editor integrates with WordPress media library:

Local Media Provider

Media state is managed through the useLocalMedia hook:

const {
  media,
  uploadingMedia,
  isMediaLoading,
  hasMore,
  fetchMedia,
  uploadMedia,
} = useLocalMedia();

Reference: packages/story-editor/src/components/library/panes/media/local/mediaPane.js:96-108

Media Actions

Available media operations:

Upload - Add new media files
Delete - Remove media from library
Update - Modify media metadata
Fetch - Load media with pagination

Reference: packages/story-editor/src/app/media/local/actions.js

Media Gallery

The media gallery displays your uploaded media:

Paginated Gallery

<PaginatedMediaGallery
  resources={media}
  uploadingResources={uploadingMedia}
  isMediaLoading={isMediaLoading}
  hasMore={hasMore}
  onInsert={handleInsert}
/>

Reference: packages/story-editor/src/components/library/panes/media/common/paginatedMediaGallery.js

Gallery Features

Infinite scroll - Load more media as you scroll
Search - Filter media by name or type
Type filtering - Show only images, videos, or all types
Preview - Hover to see larger preview

Media Filters

const FILTERS = [
  { value: FILTER_NONE, label: 'All Types' },
  { value: 'image', label: 'Images' },
  { value: 'video', label: 'Video' },
];

Reference: packages/story-editor/src/components/library/panes/media/local/mediaPane.js:89-93

Media Search

Search your media library:

<SearchInput
  value={searchTerm}
  onChange={setSearchTerm}
  placeholder="Search media"
/>

Reference: packages/story-editor/src/components/library/panes/media/local/mediaPane.js:40

Third-Party Media (Media3P)

Access stock media from integrated providers:

Media3P Integration

The Media3pApiProvider enables stock media:

<Media3pApiProvider>
  {/* Editor components */}
</Media3pApiProvider>

Reference: packages/story-editor/src/storyEditor.js:77

Available Providers

Integrated stock media services (configuration dependent):

Stock photo providers
Video libraries
Icon collections

Reference: packages/story-editor/src/app/media/media3p/

Inserting Media into Stories

Media Element Component

<MediaElement
  resource={media}
  onInsert={handleInsert}
  width={width}
  height={height}
/>

Reference: packages/story-editor/src/components/library/panes/media/common/mediaElement.js

Insertion Methods

Click to Insert
Drag and Drop
Replace Existing

Click any media item in the gallery to add it to the current page.The element is inserted at the center of the canvas with default sizing.

Media Selection Hook

const { insertMedia } = useOnMediaSelect();

insertMedia(resource, position);

Reference: packages/story-editor/src/components/library/panes/media/local/useOnMediaSelect.js

Video-Specific Features

Video Optimization

Prompt users to optimize videos:

<VideoOptimizationDialog
  video={videoResource}
  onOptimize={handleOptimize}
/>

Reference: packages/story-editor/src/components/library/panes/media/local/videoOptimizationDialog/

Video Trimming

Trim videos directly in the editor:

Select video element

Click a video element on the canvas.

Open trim tool

Click the trim button in the toolbar.

Set start/end

Drag handles to select the portion to keep.

Apply trim

Confirm to process the trimmed video.

Reference: packages/story-editor/src/components/videoTrim/

Video Captions

Add captions to videos for accessibility:

// In Design Panel > Captions
<CaptionsPanel selectedElement={video} />

Reference: packages/story-editor/src/components/panels/design/captions/

Media Recording

Record media directly in the editor:

<MediaRecording />

Features:

Camera access for photos/videos
Microphone access for audio
Direct upload to media library

Reference: packages/story-editor/src/components/library/panes/media/local/mediaRecording/

Media Processing

Media undergoes automatic processing:

Image Processing

Resize for optimal dimensions
Generate thumbnails
Optimize file size
Extract dominant colors

Video Processing

Generate poster images
Extract metadata (duration, dimensions)
Optimize for web playback
Create preview thumbnails

Audio Processing

Normalize audio levels
Extract duration
Generate waveform preview

Reference: packages/story-editor/src/app/media/local/reducers/

Page Backgrounds

Use media as page backgrounds:

Background Images

// Set page background in Design Panel
<PageBackgroundPanel />

Options:

Solid colors
Gradient colors
Image backgrounds
Pattern overlays

Reference: packages/story-editor/src/components/panels/design/pageBackground/

Background Videos

Add background videos to pages:

Automatically muted
Loop playback
Optimized for performance
Fallback to poster image

Background Audio

Add audio tracks to pages:

<PageBackgroundAudioPanel />

Reference: packages/story-editor/src/components/panels/design/pageBackgroundAudio/

Media Upload Limits

Upload constraints are configured per WordPress installation:

Maximum file size (typically 64MB for videos)
Allowed file types
Concurrent upload limit

Upload limits are determined by your WordPress and server configuration. Contact your host to increase limits if needed.

Resource Placeholders

While media loads, placeholders are shown:

renderResourcePlaceholder(resource, width, height);

Reference: packages/story-editor/src/components/canvas/renderResourcePlaceholder.js

Media Attribution

For third-party media, attribution is automatically managed:

<Attribution resource={media} />

Reference: packages/story-editor/src/components/library/panes/media/common/attribution.js

Best Practices

Optimize before upload

Compress images and videos before uploading to reduce file sizes.

Use appropriate formats

JPEG for photos, PNG for graphics with transparency, MP4 for videos.

Add alt text

Provide descriptive alt text for all images for accessibility.

Organize with naming

Use descriptive file names to make media easier to find.

Test video playback

Preview stories to ensure videos load and play correctly.

Large video files can significantly impact story performance. Always optimize videos for web delivery.

Next Steps

Text & Styling

Add and style text elements

Animations

Animate your media elements

Page Templates

Use templates with placeholder media

Get Started

Story Editor

Features

Publishing

Developer Guide

​Media Pane

​Accessing Media

​Media Types

​Uploading Media

​Upload Button

​Drag and Drop

​Hotlink Insertion

​WordPress Media Library Integration

​Local Media Provider

​Media Actions

​Media Gallery

​Paginated Gallery

​Gallery Features

​Media Filters

​Media Search

​Third-Party Media (Media3P)

​Media3P Integration

​Available Providers

​Inserting Media into Stories

​Media Element Component

​Insertion Methods

​Media Selection Hook

​Video-Specific Features

​Video Optimization

​Video Trimming

​Video Captions

​Media Recording

​Media Processing

​Image Processing

​Video Processing

​Audio Processing

​Page Backgrounds

​Background Images

​Background Videos

​Background Audio

​Media Upload Limits

​Resource Placeholders

​Media Attribution

​Best Practices

​Next Steps

Text & Styling

Animations

Page Templates

Build docs developers (and LLMs) love

Media Pane

Accessing Media

Media Types

Uploading Media

Upload Button

Drag and Drop

Hotlink Insertion

WordPress Media Library Integration

Local Media Provider

Media Actions

Media Gallery

Paginated Gallery

Gallery Features

Media Filters

Media Search

Third-Party Media (Media3P)

Media3P Integration

Available Providers

Inserting Media into Stories

Media Element Component

Insertion Methods

Media Selection Hook

Video-Specific Features

Video Optimization

Video Trimming

Video Captions

Media Recording

Media Processing

Image Processing

Video Processing

Audio Processing

Page Backgrounds

Background Images

Background Videos

Background Audio

Media Upload Limits

Resource Placeholders

Media Attribution

Best Practices

Next Steps