How to Use Image Uploader in WordPress Admin Area

In this tutorial I am going to dive deep in WordPress media uploader functionality. By the way it is possible to implement not for only images but for any supported file types.

This is how it looks in WordPress admin area:

The HTML part

In this very first part of the tutorial we begin with creating media upload buttons with HTML and a little bit of PHP.

The main question is how are you going to store the image field value in database. There are two options – image ID and image URL. I usually prefer to use the first one.

<?php if( $image = wp_get_attachment_image_url( $image_id, 'medium' ) ) : ?>
	<a href="#" class="rudr-upload">
		<img src="<?php echo esc_url( $image ) ?>" />
	</a>
	<a href="#" class="rudr-remove">Remove image</a>
	<input type="hidden" name="rudr_img" value="<?php echo absint( $image_id ) ?>">
<?php else : ?>
	<a href="#" class="button rudr-upload">Upload image</a>
	<a href="#" class="rudr-remove" style="display:none">Remove image</a>
	<input type="hidden" name="rudr_img" value="">
<?php endif; ?>

Here we have:

• We are going to use wp_get_attachment_image_url() to get the image URL. The function also returns false if there is no image with this specific ID.
• How to get $image_id? It depends on how are you going to use the image uploader. For example if you’re using it in settings pages, function get_option() should be ok for you.
• The second parameter of the function medium is the image size we are going to display. By default it is thumbnail.
• Never forget to escape the data, I used functions esc_url() and absint() for that.

The JavaScript part

Or to be exact – jQuery. Actually there is no reason to use vanilla JavaScript because jQuery is included in WordPress admin anyway.

jQuery( function($){
	// on upload button click
	$( 'body' ).on( 'click', '.rudr-upload', function( event ){
		event.preventDefault(); // prevent default link click and page refresh
		
		const button = $(this)
		const imageId = button.next().next().val();
		
		const customUploader = wp.media({
			title: 'Insert image', // modal window title
			library : {
				// uploadedTo : wp.media.view.settings.post.id, // attach to the current post?
				type : 'image'
			},
			button: {
				text: 'Use this image' // button label text
			},
			multiple: false
		}).on( 'select', function() { // it also has "open" and "close" events
			const attachment = customUploader.state().get( 'selection' ).first().toJSON();
			button.removeClass( 'button' ).html( '<img src="' + attachment.url + '">'); // add image instead of "Upload Image"
			button.next().show(); // show "Remove image" link
			button.next().next().val( attachment.id ); // Populate the hidden field with image ID
		})
		
		// already selected images
		customUploader.on( 'open', function() {

			if( imageId ) {
			  const selection = customUploader.state().get( 'selection' )
			  attachment = wp.media.attachment( imageId );
			  attachment.fetch();
			  selection.add( attachment ? [attachment] : [] );
			}
			
		})

		customUploader.open()
	
	});
	// on remove button click
	$( 'body' ).on( 'click', '.rudr-remove', function( event ){
		event.preventDefault();
		const button = $(this);
		button.next().val( '' ); // emptying the hidden field
		button.hide().prev().addClass( 'button' ).html( 'Upload image' ); // replace the image with text
	});
});

Where to insert the code? I recommend you to create an empty .js file and add it there, we are going to enqueue it in the next step. Or you can also add it to admin_footer action hook.

And Finally, Enqueueing Scripts

One last step, we have to include two scripts:

1. Our custom .js file from the previous step, let’s call it misha-uploader.js,
2. WordPress media uploader scripts, so we can actually use this modal media uploader.

Can be easily done with admin_enqueue_scripts action hook.

add_action( 'admin_enqueue_scripts', 'rudr_include_js' );
function rudr_include_js() {
	
	// I recommend to add additional conditions here
	// because we probably do not need the scripts on every admin page, right?
	
	// WordPress media uploader scripts
	if ( ! did_action( 'wp_enqueue_media' ) ) {
		wp_enqueue_media();
	}
	// our custom JS
 	wp_enqueue_script( 
		'mishaupload', 
		get_stylesheet_directory_uri() . '/misha-uploader.js',
		array( 'jquery' )
	);
}

Creating Settings Page with Image Upload Field

In the beginning of this tutorial I told you that I will describe how create a settings page like this:

It is actually super-simple and can be done with two easy steps:

1. Install and activate my Simple Fields plugin on your website.
2. Insert the following code to your current theme functions.php file:

add_filter( 'simple_register_option_pages', 'misha_option_page' );

function misha_option_page( $option_pages ) {

	$option_pages[] =	array(
		'id'	=>	'misha_settings',
		'title' => 'My Page Settings',
		'menu_name' => 'My page',
		'fields' => array(
			array(
				'id' => 'my_field',
				'label' => 'Text Field',
				'type' => 'text',
			),
			array(
				'id' => 'my_checkbox',
				'label' => 'Checkbox',
				'type' => 'checkbox',
				'short_description' => 'Yes, absolutely'
			),
			array(
				'id' => 'my_image',
				'label' => 'Image',
				'type' => 'image',
			)
	 	),
	);

	return $option_pages;

}

That’s pretty much it!

Oh and yes, now you can get the image field values with get_option() function, like this:

$image_id = get_option( 'my_image' );
$image_url = wp_get_attachment_image_url( $image_id, 'medium' );

# WordPress, Attachments, Metadata

Misha Rudrastyh

Hey guys and welcome to my website. For more than 10 years I've been doing my best to share with you some superb WordPress guides and tips for free.

Need some developer help? Contact me

Follow me on X