How to add images to a page or post
Step-by-step instructions for adding, positioning, and captioning images in WordPress pages and posts using the block editor.
Images make your content more engaging and easier to understand. WordPress makes it straightforward to add photos and graphics anywhere on a page or post. This guide walks you through every way to do it.
Quick summary
Add an Image block using the + button, then upload a new image from your computer or choose one from your media library. Always fill in the alt text field in the right-hand panel — it's essential for accessibility and SEO.
What you'll need
Beginner 3–5 minutes- A page or post open for editing. See how to edit a page if you need a refresher.
- An image file on your computer (JPG, PNG, WebP, or GIF). Aim for images under 500 KB for fast page loading. For help with sizes, see image sizes for the web.
Add an image using the Image block
Click the + button where you want the image to appear, or click in an empty paragraph block and type /image to bring up the Image block.
Click "Image" from the block picker. An image placeholder appears with three options: Upload, Media Library, and URL.
Choose how to add the image — see the options below.
Add alt text. After the image loads, click on it and look at the right-hand panel. Find the Alt text field and describe what the image shows. See below for how to write good alt text.
Three ways to add an image
Click Upload in the image block placeholder. A file picker opens. Choose the image file from your computer and click Open. The image uploads and appears in the block.
The uploaded image is also saved to your media library for future use.
Click Media Library in the placeholder. A window opens showing all the images already uploaded to your site. Click the image you want to use, then click Select. The image appears in the block.
This is the best option when you want to reuse an image that's already been uploaded.
Click Insert from URL and paste the direct image address. This embeds the image from its current web location without uploading it to your site. Use this option carefully — if the source image is removed or moved, your image will disappear.
Writing good alt text
Alt text (alternative text) is a written description of an image. It serves two important purposes:
- Screen readers read it aloud for visitors who are blind or have low vision.
- Search engines use it to understand what the image shows.
How to write alt text:
| Image type | Good alt text example |
|---|---|
| A photo of your product | "Blue ceramic coffee mug with a wooden handle" |
| A team headshot | "Jane Smith, Marketing Manager, smiling in a blue blazer" |
| An infographic | A short summary of the key information it contains |
| A purely decorative image (like a divider line) | Leave it empty — screen readers will skip it |
Keep alt text concise: 1–2 sentences is usually enough. Don't start with "Image of…" or "Photo of…" — just describe what it shows.
Don't skip alt text
Missing alt text makes your site inaccessible for visitors using screen readers and hurts your SEO. Every meaningful image should have a description.
Adjusting image alignment and size
After adding an image, you can change how it sits on the page using the toolbar above the block.
| Option | What it does |
|---|---|
| Align left / right | Wraps text around the image on the opposite side |
| Center | Centers the image with no text wrapping |
| Wide width | Makes the image wider than the content column |
| Full width | Stretches the image edge to edge |
You can also drag the corner handles of the image to resize it, or enter exact dimensions in the right-hand panel under Image size.
Add a caption
Click on the image block. Below the image you'll see a text area that says Add caption. Click it and type your caption. Captions appear beneath the image and can include links, bold text, or other inline formatting.
Adding multiple images as a gallery
To display a grid of images, use the Gallery block instead of individual Image blocks. Add a Gallery block using the + button, upload or select multiple images at once, and WordPress arranges them in a responsive grid.
You can adjust the number of columns in the right-hand panel and add a caption to each image.
Replace an existing image
If you want to swap out an image for a better one:
Click the image block to select it.
Click the Replace button in the floating toolbar above the image. It looks like two circular arrows.
Upload or choose the new image from the media library.
The new image replaces the old one. The alt text and any caption remain, so update them if needed.
Common questions
Related guides
- Working with blocks
- The media library explained
- Image sizes for the web
- How to compress images
- Alt text explained
- How to add and edit links
Need a hand?
Learn more
How to add and edit links
Learn how to add hyperlinks to text, buttons, and images in WordPress — including internal links, external links, and how to remove or change a link.
How to embed a video
Learn how to embed YouTube, Vimeo, and other videos into your WordPress pages and posts without slowing down your site.