Everything you need to know about adding and optimizing media in the WordPress editor.
Text is important, but media makes your content come alive. Images, galleries, videos, audio – they break up long articles, explain complex ideas, and keep readers engaged.
Gutenberg offers six dedicated media blocks:
- Image
- Gallery
- Cover (text over image/video)
- Audio
- Video
- File (download link)
In this guide, I’ll cover each block in detail: settings, use cases, optimization tips, and common mistakes to avoid.
Let’s dive in.
1. Image Block – The Essential Media Block
What it does: Inserts a single image into your post or page.
When to use: Any time you need one image – screenshots, photos, diagrams, illustrations.
Adding an image:
- Upload new file from your computer
- Select from media library (already uploaded)
- Insert from URL (external image link)
Key settings (right sidebar and toolbar):
| Setting | Options | Best practice |
|---|---|---|
| Alt text | Text description | Describe the image for screen readers and SEO. Never leave empty. |
| Image size | Thumbnail, Medium, Large, Full, Custom | Choose appropriately. Full size only if needed. Custom max 1200px width. |
| Alignment | Left, center, right, wide, full | Left/right for text wrap. Wide/full for hero images. |
| Link to | None, Media file, Attachment page, Custom URL | Usually “None” or “Media file” (for lightbox plugins). |
| Caption | Text below image | Optional – add context or credit. |
| Crop / Zoom | Focal point picker | Set which part of image stays visible on different screen sizes. |
| Border & shadow | Radius, width, color, shadow | Add subtle polish. Avoid heavy borders. |
Pro tips for images:
- Always add alt text. It’s critical for accessibility and SEO. Describe what’s in the image, not the file name (not
IMG_1234.jpg, butWordPress editor showing image block settings). - Compress images before uploading. Use tools like TinyPNG, ShortPixel, or Imagify. Large images slow down your site.
- Set a focal point – when you crop a thumbnail, WordPress will try to keep that area visible. Click the image, then the focal point icon (crosshair) in toolbar.
- Use descriptive file names –
gutenberg-image-settings.jpgnotphoto1.jpg.
Shortcut: Type /image.
2. Gallery Block – Multiple Images in a Grid
What it does: Displays multiple images in a responsive grid or rows.
When to use: Portfolios, product photos, event coverage, before/after sets, any collection of 3+ images.
Creating a gallery:
- Add Gallery block
- Upload or select multiple images from media library
- Arrange by dragging thumbnails
Key settings:
| Setting | Options | Best practice |
|---|---|---|
| Number of columns | 1–8 (or flexible) | 2–4 columns for most galleries |
| Image size | Thumbnail, Medium, Large, Full | Medium or Large for balance |
| Crop images | Yes / No | Yes for uniform square grids, No for original proportions |
| Link to | None, Media file, Attachment page | Media file for lightbox effect |
| Caption | Show/hide per image | Hide if captions are unnecessary |
Pro tips for galleries:
- Use flexible columns (newer option) to make gallery responsive without forcing equal heights.
- Limit to 10-12 images per gallery. More than that slows loading.
- Click and drag to reorder images.
- For advanced galleries with masonry or lightbox, consider a plugin like Modula or Envira Gallery – but start with built-in.
Shortcut: Type /gallery.
3. Cover Block – Text Over Image or Video
What it does: Places a full‑width (or fixed width) block with a background image or video, with text overlaid on top. Think hero sections, banner announcements, or post introductions.
When to use: Page headers, call‑to‑action sections, podcast episode promos, any time you need dramatic visual impact.
Adding media:
- Upload an image
- Select from media library
- Use a video (MP4) as background (advanced)
Key settings:
| Setting | Options | Best practice |
|---|---|---|
| Media | Image or video | Video background is heavy – use sparingly |
| Fixed background | On/Off (parallax) | Creates subtle scroll effect – but can hurt performance |
| Overlay color | Choose color + opacity | Ensures text is readable. Default is black at 50% opacity. |
| Text color | Light or dark | Choose based on overlay |
| Min height | Pixels (e.g., 400px) or cover | Adjust for hero sections |
| Inner blocks | Any text/heading/button | Add multiple blocks inside cover |
| Alignment | Left, center, right | Usually center for hero |
Pro tips for Cover block:
- Always use an overlay – it guarantees text contrast. Even 10‑20% overlay helps.
- Keep text short – one heading, one subheading, one button max.
- Compress background images – they are often large. Aim for 1500px width and under 200KB.
- Test on mobile – text size should be readable without zooming.
Example cover content:
text
[Cover: mountain landscape background]
<h1>Start Your WordPress Journey</h1>
<p>Learn from real experience – no fluff, just action.</p>
[Button: Start Here →]
Shortcut: Type /cover.
4. Audio Block – Embed Podcasts or Music
What it does: Inserts an audio player (MP3 usually) directly into your post.
When to use: Podcast episodes, music samples, interview recordings, audio commentary.
Key settings:
| Setting | Options |
|---|---|
| Audio file | Upload or select from media library |
| Autoplay | On/Off (not recommended) |
| Loop | On/Off |
| Preload | Auto, Metadata, None |
| Caption | Optional text below player |
Pro tips:
- Do not autoplay – users hate unexpected sound. Keep it off.
- Provide transcript for accessibility (and for readers who prefer text).
- Preload “Metadata” – loads file size and duration without downloading whole file. Faster page load.
Shortcut: Type /audio.
5. Video Block – Embed MP4 or YouTube/Vimeo
What it does: Inserts a self‑hosted video (MP4) or embed from YouTube, Vimeo, etc.
When to use: Tutorials, product demos, vlogs, event recordings.
For self‑hosted video (.mp4):
| Setting | Options |
|---|---|
| Video file | Upload from computer or media library |
| Autoplay | On/Off (avoid) |
| Loop | On/Off |
| Muted | Required if autoplay is on (browser policies) |
| Playback controls | Show/hide |
| Poster image | Thumbnail shown before playing |
| Preload | Auto, Metadata, None |
For embedded YouTube/Vimeo:
Simply paste the video URL into a Paragraph block. Gutenberg auto‑converts it to an Embed block. Or use /youtube shortcut.
Pro tips:
- Avoid self‑hosted video for large files – video eats server bandwidth and slows site. Upload to YouTube/Vimeo (free) and embed instead.
- Add a poster image – it looks professional and encourages clicks.
- Never autoplay with sound – autoplay muted is acceptable for background loops.
- Enable “Playback controls” so users can pause, skip, adjust volume.
Shortcut: Type /video or /youtube.
6. File Block – Downloadable Documents
What it does: Creates a download link for PDF, DOCX, ZIP, or any file.
When to use: Offering PDF checklists, white papers, e‑books, software downloads, template files.
Key settings:
| Setting | Options |
|---|---|
| File | Upload or select |
| Link text | Custom text (default is file name) |
| Download button style | Some themes add button styling |
| Show file size | On/Off (recommended on) |
Pro tips:
- Use descriptive link text – not “Click here” but “Download WordPress Launch Checklist (PDF, 2MB)”.
- Show file size so users know what to expect.
- Compress PDFs before uploading – use ilovepdf.com or Adobe compression.
Shortcut: Type /file.
Comparison Table: Which Media Block Should You Use?
| Block | Best for |
|---|---|
| Image | Single photo, screenshot, diagram |
| Gallery | Multiple images in a grid (portfolios, product sets) |
| Cover | Hero sections, banners – text over image/video |
| Audio | Podcast episodes, music clips |
| Video | Tutorials, demos (embed from YouTube/Vimeo recommended) |
| File | Downloadable documents (PDF checklists, e‑books) |
Accessibility & SEO Best Practices for Media
| Block | Critical best practice |
|---|---|
| Image | Always fill Alt text – describe the image meaningfully |
| Gallery | Add Alt text to each image (click individual images inside gallery) |
| Cover | Ensure text contrast – use overlay, test with contrast checker |
| Audio | Provide transcript for spoken content |
| Video | Add captions/subtitles for accessibility (YouTube auto‑captions available) |
| File | Use descriptive link text including file type + size |
Common Mistakes to Avoid
- Missing alt text – This is a common SEO and accessibility failure. Don’t skip it.
- Uncompressed images – Large images slow down your site drastically. Always compress.
- Cover overlays too light – White text on a light image is unreadable. Check contrast.
- Self‑hosted large videos – They eat server resources. Use YouTube/Vimeo embed instead.
- Autoplay audio/video – Users will leave immediately. Keep it off.
What’s Next?
Now you’ve mastered media blocks. Next, we’ll cover Design Blocks – Buttons, Columns, Group, Row, Stack, Spacer, Separator, and Page Break.
👉 Next article in this series: Gutenberg Design Blocks – Buttons, Columns, Groups & Layouts (Complete Guide)
Which media block do you use most? Any questions about image optimization or cover block settings? Ask below.
📌 Key Takeaways (for skimmers)
- 6 media blocks: Image, Gallery, Cover, Audio, Video, File.
- Alt text is non‑negotiable for accessibility and SEO.
- Compress all images before uploading (TinyPNG, ShortPixel).
- Cover block = text over image/video. Use overlay for contrast.
- Avoid self‑hosted videos – embed from YouTube/Vimeo.
- File block = downloadable PDFs. Use descriptive link text + file size.
🔗 Internal Links
- Article #1 – Gutenberg & Blocks: Why This Is the New Standard
- Article #2 – Text Blocks Complete Guide
- Article #4 – Design Blocks (coming soon)