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 Alternative text field in the right-hand panel — it's essential for accessibility and SEO.

What you'll need

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). Keep the file size small so your page loads quickly: how to compress images gives our recommended targets. For help with dimensions, 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 Insert from 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 Alternative 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.

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, or tick Mark as decorative in the block settings, so screen readers skip it

Keep alt text concise: a short phrase or sentence 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 Align button in the toolbar above the block.

Option	What it does
Align left / right	Wraps text around the image on the opposite side
Align 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

Wide width and Full width only appear if your theme supports them.

You can also drag the resize handles on the image to change its size, or set an exact Width and Height in the right-hand panel.

Add a caption

Click on the image block, then click Add caption in the toolbar above it. A space for the caption appears below the image. Type your caption there. 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 gallery layout.

You can adjust the number of columns in the right-hand panel, and add a caption to each image with the Add caption button in that image's toolbar.

Replace an existing image

If you want to swap out an image for a better one:

Click the image block to select it.

Click Replace in the toolbar above the image.

Choose Open Media Library or Upload to pick the new image.

The new image replaces the old one. The block picks up the new image's alt text from your media library, which may be blank, so check the alt text and the caption and update them to match the new image.

Common questions

My image looks blurry — what went wrong?

A common cause is an image file that is smaller than the space it fills. Wide width and Full width stretch the image across that space, and so does dragging an image bigger than its original size, which makes a small image look blurry. Also check Resolution in the block settings: a small size such as Thumbnail or Medium looks soft when shown large. Use the original, highest-quality version of the image rather than a small thumbnail. For guidance on ideal sizes, see image sizes for the web.

My image is making the page load slowly — what can I do?

Large image files are a common cause of slow pages. Compress the image before uploading using a free tool like Squoosh or TinyPNG. See how to compress images for the file sizes we recommend.

Can I add a link to an image so it goes somewhere when clicked?

Yes. Click the image block, then click Link in the toolbar above it. Paste the URL where you want the image to link, or search for a page on your site. See how to add and edit links for more.

My image is not showing up at all — what should I check?

Check that the image file uploaded successfully (no error message). If the image was inserted from a URL, check that the original URL is still valid. Also try doing a hard refresh on the preview page to bypass your browser's cache. In Chrome or Edge, press Ctrl+Shift+R (Windows) or Command+Shift+R (Mac); other browsers may use a different shortcut. See browser cache and refresh.

How do I upload images to use later?

You can upload images directly to your media library without inserting them anywhere. Go to Media → Add Media File in the WordPress dashboard (called Add New Media File or Add New on older versions). See the media library explained.

Need a hand?

If you're stuck, email support@chykalophia.com and we'll help. Include your website address and a screenshot if you can.