Media Library

The Media Library is where all uploaded media files are stored and managed within WordPress. Any time you upload or select an image, document, logo, or other file — whether inside a block, as a featured image, or in the Site Editor — you’re using the Media Library.

Start here: watch the walkthrough (8 minutes)

What the Media Library is used for

The Media Library is not just a storage area. It’s a central system that supports content creation across the entire site. Images in Image blocks, background graphics in layout blocks, the Site Logo in the Header, downloadable PDFs, and more — all of these are pulled from the Media Library.

You’ll use it when:

  • Adding blocks that include media elements (Image, Media and Text, Image Card, Gallery, etc.)
  • Setting a Featured image for a page or post
  • Replacing the Site Logo
  • Uploading PDFs or downloadable documents
  • Selecting background images for sections

While many file types are supported, the following are the most commonly used and appropriate for most sites:

  • Images (jpg, png, gif, svg, webp)
  • Documents (pdf, doc, docx, xls, xlsx, ppt, pptx)
  • Audio files (mp3)
  • Video files (mp4) — uploading video files directly is generally not recommended. See guidance below.

Think of the Media Library as a shared resource. Files uploaded once can be reused anywhere across the site.

Accessing the Media Library

There are two common ways to access it:

From the WordPress Dashboard

  1. Go to Media → Library
  2. View all uploaded files in either Grid view or List view

From here you can upload new files, edit existing files, or delete unused items.

From within the editor

The Media Library is used in numerous locations throughout the editor.
When editing a block or setting field that includes media:

  1. Click Upload or Media Library
  2. Select an existing file or upload a new one

This opens the same Media Library interface within a modal window.

Key sections of the Media Library

Media list view

The main Media Library screen shows all uploaded files.

You can:

  • Switch between Grid and List view
  • Upload new media files
  • Select files to view or edit their details
  • Search by filename
  • Filter by media type (images, documents, etc.)
  • Filter by upload date
  • Use Bulk Select to delete multiple items

Attachment details

When selecting a file, its details and editable metabase will open in a modal or the right panel depending on where the media library is being viewed.

For images, this includes:

  • Alternative Text
  • Title
  • Caption
  • Description
  • File name
  • File type
  • File size
  • Image dimensions

This information helps with accessibility, organization, and search.

Preparing images before uploading

Before uploading an image, prepare it properly. This protects site performance and improves accessibility.

Resize images appropriately

Images should be resized and compressed before uploading.

General guidelines:

  • Maximum recommended size: 1920px × 1080px
  • Aim for file sizes under 200 KB when possible

Use larger dimensions only when necessary (such as full-width hero images). Smaller images — like logos or thumbnails — should be much smaller.

Uploading extremely large images (for example, 5000px wide or multi-megabyte files) can:

  • Slow down page load times
  • Negatively impact performance
  • Reduce user experience

Choose image dimensions based on where the image will appear:

  • Hero images: Larger dimensions (typically 1920px wide)
  • Featured images: Medium-sized (typically 1200px wide)
  • Logos and icons: Small (typically under 600px wide)

Choose the correct file format

Selecting the right file type improves performance.

  • JPEG: Best for most photographs (high compression, smaller file size)
  • PNG: Use when transparency is required (such as logos or graphics)
  • SVG: Ideal for scalable icons and simple graphics with very small file sizes

Alternative text and accessibility

Alternative Text (ALT Text) is required for accessibility and should be added to almost all images. Adding ALT Text is one of the simplest and most important accessibility steps content editors can take.

Alternative Text:

  • Describes the content and purpose of the image
  • Is read by screen readers
  • Displays if an image fails to load

How to write good Alternative Text

  • Describe the image clearly and concisely
  • Focus on meaning, not visual detail
  • Avoid phrases like “image of” or “picture of”
  • Leave ALT Text empty only if the image is purely decorative

Video and audio files

Video files should generally not be uploaded directly to the Media Library. Large, self-hosted, video files take up significant storage, slow down performance, and do not stream as efficiently as dedicated platforms.

Instead, upload videos to platforms like YouTube or Vimeo and embed the video into your page using the provided URL. The same principle applies to large audio files. When possible, host audio on platforms such as Spotify or SoundCloud instead of uploading it directly to the Media Library.

If there is a specific reason to upload a video file directly ensure it is highly compressed and keep file sizes as small as possible.

Documents and downloadable files

The Media Library supports document uploads such as:

  • PDF (.pdf)
  • Word (.doc, .docx)
  • Excel (.xls, .xlsx)
  • PowerPoint (.ppt, .pptx)

These can be linked within content to allow visitors to download files.

When uploading documents:

  • Use clear, descriptive file names
  • Ensure documents are accessible when possible (e.g., tagged PDFs)
  • Keep file sizes reasonable

Best practices

Resize before uploading

Never rely on WordPress to handle extremely large images. Prepare and compress files before uploading.

Use descriptive file names

Before uploading, rename files using lowercase letters, hyphens instead of spaces, and descriptive wording. This improves searchability and organization.

Add metadata consistently

Always fill in Alternative Text (required for accessibility), Title (for organization), Caption and Description when relevant.

Upload files using drag and drop

In addition to the Upload button, files can also be uploaded by dragging and dropping them directly into the Media Library. Simply drag files from your computer onto the Media Library screen or into the upload area inside the editor. This can be a faster way to upload multiple files at once.

Avoid hosting large multimedia files

Do not upload large video or audio files unless absolutely necessary. Use dedicated hosting platforms whenever possible.

Perform regular cleanups

Periodically review unused media to remove outdated and duplicate uploads. A clean Media Library improves performance and usability for editors.

Reuse existing files

Before uploading a new file, search the Media Library to see if it already exists. Duplicate uploads increase storage usage and confusion.