Blogging & content · Guide
How to Add Media to WordPress Page (Step by Step)

Short answer
Open the page in the block editor, click the plus button and choose a media block such as Image, Gallery, Video, Audio or File. Upload a new file, pick one from the Media Library or paste a URL, add alt text, then click Update to save the page.
Key takeaways
- Each media type has its own block in the WordPress editor.
- Uploaded files go to the Media Library and can be reused anywhere.
- Embedding YouTube or Vimeo saves storage compared with uploading video.
- Write short, descriptive alt text for every meaningful image.
- Most upload failures come from file size, file type or server limits.
How do you add media to a WordPress page?
Open the page in the editor, add an Image, Video, Audio, Gallery or File block, then upload a file, pick one from the Media Library or paste a URL.
In WordPress, media means images, videos, audio files and documents such as PDFs. Every upload is stored in the Media Library, so you can reuse the same file on many pages.
The block editor gives each media type its own block. You choose the block that matches your file, and it handles the upload and display for you. The rest of this guide walks through each one, plus embeds, alt text and common upload problems.
How do you open the page and find media blocks?
Go to Pages in your dashboard, click the page title to open it in the editor, then click the plus button to see the media blocks.
Step by step:
- Log in and go to Pages > All Pages.
- Hover over the page and click Edit, or create a new one with Add New Page.
- Click where you want the media to appear.
- Click the plus (+) icon, called the block inserter.
- Open the Media group, or type the block name in the search box.
The Media group contains Image, Gallery, Audio, Cover, File, Media & Text and Video. You can also type a slash, such as /image, on an empty line to add a block quickly.
How do you add an image to a page?
Insert an Image block, then click Upload to add a new file, Media Library to reuse an existing one, or Insert from URL to show an image hosted elsewhere.
Here is the full process:
- Add an Image block.
- Choose Upload and pick a file from your computer, or drag the file onto the block.
- Or choose Media Library and select an image you uploaded before.
- Add alternative text in the block sidebar so screen readers can describe it.
- Use the toolbar to set alignment, crop or add a link.
- Click Update or Publish to save the page.
The WordPress.org guide to the Image block lists every setting, including resolution, aspect ratio and captions.
Upload images at a sensible size. A photo straight from a phone can be several megabytes, which slows the page. Our guide on how to optimize images for WordPress explains how to resize and compress them first.
Format matters as well as size. The web.dev guide to choosing the right image format explains when to use JPEG, PNG, WebP or AVIF.
How do you add a gallery of images?
Add a Gallery block and select or upload several images at once, then set the number of columns and how the images are cropped.
To build one:
- Insert a Gallery block.
- Click Upload to add several files, or Media Library and select multiple images.
- Click Create a new gallery, reorder the images if needed, then Insert gallery.
- In the sidebar, set the columns, whether images are cropped, and where they link.
Each image inside a gallery is its own Image block, so you can still add alt text and captions to each one.
How do you add video and audio?
Use the Video or Audio block to upload a file to your site, or use an Embed block to show a video hosted on a service like YouTube or Vimeo.
Uploading video to your own site is simple, but video files are large. They use storage and bandwidth, and some hosts limit them.
For most sites, embedding is the better choice. Paste a YouTube or Vimeo link on its own line in the editor and WordPress usually turns it into an embedded player automatically. This uses oEmbed, which the WordPress.org Embeds documentation explains, along with the list of supported services.
YouTube also gives you an embed code under the Share button, explained in its help page on embedding videos and playlists. In WordPress you rarely need that code, because the plain link is enough.
| Option | Where the file lives | Best for |
|---|---|---|
| Video block upload | Your hosting | Short clips, private or background video |
| Embed block | YouTube, Vimeo and similar | Long videos, tutorials, public content |
| Audio block upload | Your hosting | Podcasts or clips you own |
| Audio embed | Spotify, SoundCloud and similar | Music and hosted podcasts |
Our guide to self-hosting videos vs embedding YouTube goes into the trade-offs in more detail.
How do you add a PDF or other file?
Add a File block and upload the document, and WordPress shows a download link, with an optional button and an inline preview for PDFs.
Steps:
- Insert a File block.
- Upload your PDF, spreadsheet or other document, or choose it from the Media Library.
- Edit the link text so readers know what they are downloading.
- In the sidebar, choose whether to show a download button and, for PDFs, an inline preview.
WordPress only allows certain file types for security reasons. Common images, documents, audio and video formats work. Unusual types may be blocked unless a plugin allows them.
How do you place text next to media or over an image?
Use the Media & Text block to put an image or video beside text, or the Cover block to place text on top of an image or video background.
The Media & Text block is useful for feature sections, team bios and product highlights. You can switch the media to the left or right and let it stack on mobile.
The Cover block is often used for page headers and banners. Pick an image or video, add a heading and button on top, and adjust the overlay color so the text stays readable.
Both blocks pull from the same Media Library as the Image block.
Can you upload media to the library first?
Yes, go to Media and choose the option to add a new file, upload everything you need, then insert those files into any page later.
This is handy when you are preparing a page with many images. Go to Media > Add New Media File, drag files into the upload area and wait for them to finish. The wording of this menu item has changed slightly across WordPress versions.
Then, when editing the page, choose Media Library in any media block to insert them. The Media Library screen documentation explains the grid and list views and how to edit details like titles and alt text.
How do you add alt text and captions properly?
Write short alt text that describes what the image shows and why it matters on the page, and use captions only when visible context helps readers.
Alt text is read aloud by screen readers and shown if an image fails to load. It also helps search engines understand the image.
Good habits:
- Describe the content and purpose, not just image of.
- Keep it to one short sentence in most cases.
- Leave alt text empty for purely decorative images, so screen readers skip them.
The W3C's alt text decision tree is a quick way to decide what to write. You can edit alt text in the block sidebar or in the Media Library, though library changes may not update images already placed on pages.
Is the process different in the Classic Editor or page builders?
In the Classic Editor you click the Add Media button above the text box, and page builders such as Elementor use their own image, video and gallery widgets.
With the Classic Editor plugin, place your cursor where the media should go, click Add Media, then upload or select files and click Insert into page.
Page builders work in a similar way. Drag an image or video widget onto the layout, then choose the file from the same WordPress Media Library. If you use Elementor, our guide on how to use Elementor in WordPress covers its widgets.
What if your media will not upload?
Upload failures are usually caused by the file being too large, an unsupported file type, server memory limits or folder permission problems.
Common fixes:
- File exceeds the maximum upload size. Compress the file or raise the limit. See how to increase the max upload size.
- HTTP error during upload. Often a memory or image processing issue. Our guide to the HTTP error when uploading images covers it.
- Sorry, you are not allowed to upload this file type. The format is blocked, so convert it to a common type.
- Media Library will not load. A plugin conflict is a frequent cause.
Once your files are in place, preview the page on desktop and mobile before publishing, and check that every image has alt text.
Frequently asked questions
Where are WordPress media files stored?
Uploaded files are stored on your web server, normally inside the wp-content/uploads folder, organised by year and month by default. The Media Library in your dashboard lists them and stores details such as titles and alt text.
Can I add the same image to several pages?
Yes. Once an image is in the Media Library, choose Media Library in any Image block and select it. The file is stored once and reused, so you do not need to upload it again.
Why does my image look blurry on the page?
The block may be using a smaller image size. Select the image and change the resolution setting in the block sidebar, or upload a larger original if the file itself is small.
How do I replace an image on a page?
Select the Image block and click Replace in the toolbar. You can then upload a new file, choose another from the Media Library or insert one from a URL, without deleting the block.
Can I add media to a page without uploading files?
Yes. Use Insert from URL in the Image block or paste a link from a supported service such as YouTube to create an embed. The file stays on the other service and is displayed on your page.
Sources
- Image block WordPress.org Documentation
- Embeds WordPress.org Documentation
- Media Library Screen WordPress.org Documentation
- An alt Decision Tree W3C Web Accessibility Initiative
- Choose the right image format web.dev
- Embed videos and playlists YouTube Help
Is your product missing, or something out of date?
Tell us what to add or correct. We read every note and reply when we need a source. A message does not buy a ranking.
Thanks — we review requests within 3 business days.
Related guides
About the editors
Researched from the primary sources listed above and checked against our editorial rules before publishing.


