Skip to main content

How to Add, Resize, and Caption Images in WordPress (with Alt Text)

Using Joomla instead? See How to Add, Resize, and Caption Images in Joomla (with Alt Text).

This covers the WordPress 6.x block editor and the built-in Media Library.

Before you upload: size and format

Large images slow your site down. Before uploading:

  • Width: resize to about the largest size it will display. As a rule of thumb, we recommend about 1920px wide for full-width banners, about 1200px for images that span the main content area, and about 800px or less for images that sit beside text. Your theme may differ, so ask us if you're not sure. WordPress also creates smaller copies automatically and scales down very large uploads (over 2560px).
  • Format: use JPEG or WebP for photos, and PNG for graphics with sharp edges or transparency.
  • Compress: run photos through a compression tool or your photo editor's "export for web" option before uploading. A JPEG quality setting around 70-80% usually looks the same to visitors and is much smaller. Smaller files mean faster pages, especially on phones.
  • File name: use plain, descriptive names like front-office-dalton.jpg, not IMG_4032.jpg.

Upload to the Media Library

  1. Go to Media > Add Media File (labeled Add New Media File or Add New in older versions).
  2. Drag files in or click Select Files.

You can also upload straight from the editor, as below.

Resize or crop in WordPress

  1. Go to Media > Library and click the image.
  2. Click Edit Image.
  3. Use Crop, the rotate and flip buttons, or Scale Image to set new dimensions.
  4. Click Save. WordPress keeps the original so you can restore it later.

Add an image to a page or post

  1. Open the page or post in the editor.
  2. Click + and choose the Image block (or type /image).
  3. Choose Upload, Media Library, or Insert from URL.
  4. With the image selected, open the settings sidebar (top right) and fill in:
    • Alternative text: see below.
    • Resolution: pick Thumbnail, Medium, Large, or Full Size. Pick the smallest that looks good.
    • Width / height or aspect ratio: to fine-tune the displayed size.
  5. To add a caption, click the Add caption button in the block toolbar (or the area under the image) and type.
  6. Use the toolbar's Align button to set alignment.
  7. Click Save.

You can also set alt text, captions, and titles in Media > Library so they're filled in when you reuse the image. Alt text set in the block applies to that spot only.

Featured images

In the Page or Post sidebar tab, click Set featured image. Your theme decides where it shows, often at the top of posts and in blog lists. Fill in its alt text in the Media Library.

Writing good alt text

Alt text is read aloud by screen readers and shown if an image doesn't load. It helps people and search engines understand the image.

  • Describe what matters in the image in a short sentence: "Two technicians installing a heat pump outside a brick house."
  • Don't start with "image of" or "picture of."
  • If the image is a link or button, describe where it goes.
  • If it's purely decorative, leave the alt text empty so screen readers skip it.
  • Don't stuff it with keywords.

Prefer we handle it?

If you'd rather spend your time running your business, our boutique hosting, available to our clients, including sites moved over from another host, takes a proactive approach to security and monitoring, with nightly backups, 24/7 outage monitoring, and ongoing core CMS updates.

Accessibility