Mastering the WordPress Media Uploader to Make it Work For You

The WordPress Media Library is essentially a repository for all of the media on your site, from images and video to any files you wish to upload, such as PDFs.

Unfortunately, there’s not a lot of documentation about how to actually use it and make the most of what it has to offer.

So, in this Weekend WordPress Project we’re going to delve into the ins and outs of the media library, how to use the uploader, supported files, creating galleries, and audio and video playlists.

Media Library Versus Media Uploader

It’s important to understand the difference between the media library and the uploader and what they can do

The uploader can be found right above the visual editor, where you edit pages or posts. It’s a tool that allows you to insert images, videos and other files directly into posts or pages via the Add Media button.

The images or files you add will appear in the editor where you clicked before you accessed the uploader.

The "Add Media" button above the visual editor for a sample page. Above the button is the permalink for the post and title field.
Even when the distraction-free mode is enabled, you can still see the button sitting in the same position.

The media library, on the other hand, is located in the admin dashboard under Media > Library. It contains all of the files you have uploaded to your site since you first created it.

The media library page accessed from the WordPress admin dashboard.
You can choose to display your files in a list by clicking the list icon underneath the “Media Library” title. By default, your files are tiled as thumbnails.

This is the main difference between the two, though many of the same tasks can be handled using either tool. The main point you need to know is that uploading a file to the media library does not mean it will appear anywhere on your site automatically – you need to add it first using the uploader.

Supported Files

While not all files are supported by the media uploader, there are many that you are able to add to your site:


  • .jpg
  • .jpeg
  • .png
  • .gif


  • .mp4, .m4v (MPEG-4)
  • .mov (QuickTime)
  • .wmv (Windows Media Video)
  • .avi
  • .mpg
  • .ogv (Ogg)
  • .3gp (3GPP)
  • .3g2 (3GPP2)


  • .mp3
  • .m4a
  • .ogg
  • .wav


  • .pdf (Portable Document Format; Adobe Acrobat)
  • .doc, .docx (Microsoft Word Document)
  • .ppt, .pptx, .pps, .ppsx (Microsoft PowerPoint Presentation)
  • .odt (OpenDocument Text Document)
  • .xls, .xlsx (Microsoft Excel Document)

While WordPress allows all of the files above, your hosting provider may not, especially if you’re on a shared server. You’ll also have a limit to the size of the file you can upload.

The limit will vary depending on your hosting or if you manually increase the limit yourself in your php.ini file. You can learn how to do this in our post How to Increase the Maximum Upload Limit in WordPress.

Understanding the Upload Settings

When you click the Add Media button at the top of the visual editor, you will automatically see all the media files you have previously uploaded.

When you click on one, options will appear on the right hand side. The first section you’ll see is called Attachment Details.

An image has been clicked from the media library location and the attachment details are shown to the right.
You can also select multiple images to add to the post or page you’re editing by simply clicking on each additional file you would like to add while also pressing the Ctrl key in Windows or Command key on Mac OS X.

An overview will be displayed of the file’s details and links to edit the image in WordPress or delete it permanently. You’ll then see the file’s meta data fields to fill out including a direct URL path among your site’s files.

The attachment details fields in the media uploader.
Adding or editing these fields is entirely optional, but it’s a good idea to at least add “Alt Text” to your image before you add it to your post or page.
  • The Title field should contain a good, brief description of your image since it will be shown if your image or file fails to load. It will also be displayed on its attachment page which is displayed only if you select that option further down the attachment details section.
  • It’s also picked up by search engines so having a generic title with a random string of letters or numbers won’t help you rank higher in search results.
  • The Caption is a short description or note about the image that is displayed below the image on the post or page. Depending on the theme you are using, it may be contained within a border along with the image or otherwise could have different styling than the rest of your page.
  • The Alt Text (alternative text) field is meant to have an accurate description of the image or video for visitors who are visually impaired. You should describe what is shown or what is happening in the image or video so visitors can follow along with your post and not skip a beat, even if they can’t see what’s being shown.
  • The Description is similar to alt text, but the difference is that it’s displayed on an file’s attachment page if the theme supports it. You can also add HTML to this section.
The attachment page using the Twenty Fifteen default theme. A title, description and link are included underneath the image. It says "PopUp Pro plugin" in a header 3 tag and in a paragraph tag, "Grab your visitors’ attention, build your mailing list and share targeted ad messages with the most customizable, smart, responsive pop-up and pop-over WordPress plugin." Lastly, there is a link in a paragraph tag which says, "Learn More ..."
You may not need to use this type of meta data, but it can be useful if you’d like to offer your visitors downloads of your content.

The final section of the available options is called Attachment Display Settings and it sets how the image or other media file is displayed on your site.

The "Attachment Display Settings" portion of the options in the media uploader which appears once an thumbnail is selected from the list.
One of the best ways to get familiar with these options is to test them out on a sample page and see the direct results of the options you choose.

With the Alignment option, you can choose to have your file positioned on the left, center or right of your post.

Selecting the default None option in the drop down box will display your image to the left and any text that you enter will appear at the bottom of the image on a new line.

Left alignment will display your image on the left, but it will also activate text wrapping. This means text that you enter will appear beside the image for its full height, then appear at the bottom.

A WordPress logo in the editor with left alignment. Sample text is positioned around the image on the right.
Adjusting the size of the image will help text wrapping fit nicely.

The Center option will position the image in the middle of the page on the line its on. Text will appear above and below the image.

The last option is Right and it’s similar to left aligning since text wrapping is enabled with this option, but it differs because an image is displayed to the right with text wrapping on the left.

Link to is another drop box option that has different ways your media file can display when it’s clicked. There are four choices for images and the default is Media file. When this option is selected, a clicked image will link directly to the file on your site.

A blank page with the image on the very top, left of the page will be displayed. There are plugins that will change how this option is displayed when an image or other file has been clicked such as the Easy FancyBox and WordPress Colorbox Lightbox plugins.

Other files such as MS Word documents and PDF’s will launch the file’s download when the displayed link is clicked.

Selecting Attachment Page displays links on a separate page that is styled to look like another page on your theme, but instead of post or page content being shown, your image or other file is displayed with the title and description attributes.

The Media file and Attachment Page options are available for all uploaded file types, but there are an extra two options for images.

The first of the two is the Custom URL option which allows you to choose any link on the web for your visitors to be directed to when they click your image. The other option is None which displays your image without a link attached. Clicking it will have no affect.

The last option in the Attachment Display Settings for image files only is Size. You will be able to choose between pre-defined sizes including Thumbnail which is set to 150 pixels by 150 pixels by default, Medium with a height of 300 pixels and Full Size which does not scale your image and displays the original uploaded size.

When you select these options, your original image is scaled to fit in your post or page, but the original file’s size remains untouched. This means that you can resize an image to be smaller in one post while also displaying it in another post as its original size.

With all the options covered, let’s dive into the different ways you can upload content to your site.

Uploading from Your Library

After clicking the Add Media button when editing a post or a page, an in-line pop-up will appear where you have a few different options to choose the file location of media you would like to upload. The default location is from your media library.

The default display in the in-line pop-up for the media uploader.
You can sift through the list faster by selecting a sorting option in the drop down boxes or search box above the thumbnails.

This is helpful if you’ve previously added a file to your site and want to use it currently, even if you have already used it before on your site.

All you have to do is click on the thumbnail of the file you want to add, then include any extra options you’d like on the right hand side of the pop-up. Finally, click the Insert into Page/Post button to add the file.

Uploading from Your Computer

After clicking the Add Media button, Select the Upload Files tab under the “Insert Media” title.

The "Upload Files" tab has been selected and the "Select Files" button appears to choose the files desired to upload to your WordPress site.
On larger screens there is an additional menu on the left of these tabs, but it is listed on smaller screens as a drop down list when hovering over the “Insert Media” title.

Next, click the Select Files button that appears to choose the files you wish to upload or drag and drop them from your computer’s files directly to this area in the pop-up.

Either option will upload your selected files and display them in the media library. Once the upload is complete, you will be automatically redirected to the Media Library tab where you can select the files you want to use.

Creating an Image Gallery

To create a gallery with the images of your choice, select the Create Gallery link in the menu on the left after opening the media uploader.

The "Create Gallery" link has been clicked and three images have been selected from the media library.
You can select multiple images by simply clicking them with your mouse. You don’t need to press any keys on your keyboard like you would in the media library. You can also add individual meta data for each image you select.

Choose the images you would like to use in the order you would like them to appear and enter in any meta data you would like to add. When you’re done, click on the Create a new gallery button at the bottom, right of the pop-up.

The "Edit Gallery" page in the media uploader. There is a menu on the left containing the links to cancel, edit and add to gallery. On the right are the "Gallery Settings."
Selecting the “Add to Gallery” link on the left will bring you back to the “Media Library” to select other images to include in your gallery.

You’ll have the chance to delete any images you don’t want to include on the Edit Gallery page that loads by clicking on the X buttons on the top, right of each thumbnail.

You can also reorder the images by clicking on one, then dragging and dropping it in your desired place, although, this may not be an option with certain themes or gallery plugins. There is also the Reverse order button next to the Gallery Settings which will flip the order the images.

You can also cancel the creation of the gallery or add more images by selecting those links from the menu on the left. Once you have all the images ready, choose the Gallery Settings you would prefer on the right.

You’ll see the familiar options of Link to and Size along with two new options: Columns and Random Order.

Selecting a number value in the Columns drop down box will determine how many images are displayed on one line. Keep in mind that if your images are larger, they may not all fit on one line and may spill over to a new one.

The Random Order radio button will display your images in a random order not just once, but for each time the page is loaded.

When you’re done setting up your new gallery, click the Insert gallery button on the bottom, right of the pop-up to add it to the post or page you’re editing.

Adding an Audio or Video Playlist

Embedding videos or music to your site is very similar to adding image galleries. For the full instructions you can check out our post How to Create Audio & Video Playlists in WordPress Without Plugins.

Keep in mind that if you want your playlist to work, your selected files need to be .mp3 for audio and .mp4 for videos, otherwise only a download link will appear. It may also help you to note that in order for the Create a Video/Audio Playlist buttons to appear, you need to upload your files first.

A finished audio playlist on a page. It includes a picture, titles and a bar with a play button, and a volume control button.
The audio and video meta data is added in the same way you would images for a gallery.

Inserting a Featured Image

The next option listed in the media uploader menu is Set Featured Image.

The "Set Featured Image" link is highlighted and has been selected in the media uploader menu on the left of the pop-up.
Unlike image galleries and adding images to your post or page, you can only select one image to be featured.

Once you upload the image you would like to display as the main image for your post or page, click the featured image link and select the image. Add the meta data you need and click the Set featured image button on the bottom, right of the pop-up.

Add an External Media File

You don’t just have the option to add files you uploaded to your site from your computer. You can also choose to embed a file from a direct link from another site. This means you can easily add Vimeo or YouTube videos to your site without having to upload them.

To do this, click the Insert from URL link in the left menu of the media uploader window and enter the link of the file you wish to embed to your post or page.

A sample link has been entered after selecting the "Insert from URL" link in the media uploader menu.
Adding a title is optional since YouTube videos, for example, already include a title with the video.

Finally, click the Insert into page button at the bottom, right corner of the pop-up to add the media file to your post or page.


Now you’ll be able to help your site stand out and become more dynamic by adding media files including images, audio and video.

There are also many plugins to enhance the image gallery feature. To learn more about some of the best ones, check out our post 5 Best Free WordPress Gallery Plugins.

If you would like to learn more about optimizing your images for your site to reduce load times, check out our plugin WP Smush Pro.

There are also many resources available for sourcing free images you can use on your site. You can find a great list in our post The Best Places to Find Free Stock Images for Your WordPress Site.

What are your favorite types of media you add to your site? Feel free to start a conversation in the comments below.

2 Responses

  • The Incredible Code Injector

    Ms. McKINNON

    Just posted a link to this article on Facebook with this caption: “Mein Gott, but I wish I had had access to an article like this when I launched my first blog two years ago. Three things would have happened: I would have had pictures on my site from the get-go (I only recently got past the intimidation factor and learned all the tricks, which are easy); i would have provided a better visual experience for both of my regular readers; and I would have saved a helluvalotta time!”

    If you had ONLY turned me onto Easy FancyBox I would be thankful: walking me through the Attachment Details is like gravy or dessert

    Thanks again! You have made three WordPress sites better sites for my readers!

    Sith agus Slainte ‘bah!


  • The Incredible Code Injector

    Hi Jenni,

    Thanks for the great article. I have users creating content all the time who are not wordpress experts. I would like to set the “Create Gallery” option as the default for when Add Media button is pressed in the visual editor of particular custom post types.

    I have tried fooling around with add_filter(media_upload_tabs, … ) and I can add an additional tab, however I cant seem to remove the Insert Media or Change it to come after Insert Gallery.

    Any help here would be appreciated.

    Thanks – Mark

Comments are closed.