Frontend Image Uploader in WordPress


WordPress has provided us many functions to upload images, like media_handle_upload(), media_handle_sideload(), wp_handle_upload(), wp_import_handle_upload(),wp_handle_sideload(), media_sideload_image().

I have another post showing how to upload an image with AJAX. Check it here. You are still recommended to read this post before going to the ajax one.

If you want to add an image upload form in the frontend, then you should read on.

Today I will show you how to let users upload image(s) from frontend with one of above functions: wp_handle_upload()

This function handles PHP uploads in WordPress, sanitizing file names, checking extensions for mime type, and moving the file to the appropriate directory within the uploads directory.


wp_handle_upload( $file, $overrides, $time ).

One thing to keep in mind that the $file parameter refers to a single element of $_FILES. So we have to call this function once for each uploaded file.

A typical file upload form contains below elements:


When the submit button is clicked, the post action is triggered and input data is usually sent to a server page for processing the data. In this case, the data is the $_FILES variables as we define the input type is file.

Below is the code to process the input:

if ( $_FILES ) {

If $_FILES is set, then a custom function upload_user_file will process the upload stuff.
Remember, ‘test_upload’ is the name of our file input in our form above.

And below is the upload_user_file function we create with wp_handle_upload.

Basically this function uses wp_handle_upload to handle the upload and wp_insert_attachment to insert the uploaded image into the media library. It returns the attachment ID for our easy use when everything is done.

Above example is for single image upload, if we want multiple images uploaded the same time, a bit of tweaks is required.

First we’ll need to redefine the upload form.


Here we change the name of the input to test_upload[] and add a multiple attribute. You should know why this is required if you have knowledge of HTML forms.

As I said earlier in this post, we’ll have to call upload_user_file once for each image upload and similarly we’ll call upload_user_file once for each image.

Before going forward, let’s first take a look at the $_FILES upload array.

In the single image upload example, we dump information about $_FILES with var_dump($_FILES['test_upload']) to check what’s there.


And we also check the array for multiple images upload array(2 images for example).


As such, we’ll need to re-array the multiple image upload array to better match the single image upload array.


Here is the result of the re-array with var_dump['arr'], you’ll see now it more suits our need.


Now it’s easy for us to call upload_user_file with foreach function.


In most cases we can use the multiple image upload method as above, even you only allow one image to be uploaded each time, just remove the multiple attribute from the file input.

I’ve put it all together and use it to a custom page template. Also remember to add the upload_user_file to your functions.php.


Author: Leo

My name is Leo who's behind this blog. I've been working with wordpress since 2010. I'll write about themes, plugins, tutorials and all about wordpress here. Hope you find it useful!

8 thoughts on “Frontend Image Uploader in WordPress”

    1. Yeah you are correct. Those codes are just for example not for production use.
      It’s better to use if ( isset($_FILES['test_upload']) ) to check if any file is chosen and uploaded.

Leave a Reply

Your email address will not be published. Required fields are marked *