How to Add Custom Media Uploader Button in WordPress?

In this post, we will see how to add a custom media uploader button in wordpress. We can add a custom media button on meta boxes, a custom options page, or posts and pages sections.

WordPress has a built-in media upload feature that I am sure you have used when you upload any image in WordPress. When you click on the ‘Upload‘ button a popup will show the WordPress media library and you can upload a new image or can select from an existing one.

So what if we want the same functionality implemented on our custom plugin, custom theme, or any custom options page?

No worry!!!

In this tutorial, I will explain to you how you can implement custom media uploader button functionality anywhere.

Let’s get started!

Add Custom Media Uploader Button in WordPress

To add a custom media uploader button on your meta boxes, theme page, plugin options, or anywhere, you have to add the HTML structure for the ‘Upload‘ button and jQuery media library.

By taking the reference of the tutorial custom options page in WordPress, we will add a custom media uploader button on that options page.

I would recommend you to check this tutorial first how to create a custom options page in wordpress, so will be easy to continue here.

Add and Register Settings Fields

If you had a chance to check that tutorial, you see there were two input fields. Now we will add one more field ‘Theme Logo‘ and register a settings for it.

add_action( 'admin_init',  'custom_page_register_setting' );

function custom_page_register_setting() {

    add_settings_section(
        'homepage_section', // section ID
        '', // title
        '', // callback function
        'custom-page-slug' // page slug
    );

    // logo field
    add_settings_field(
        'theme_logo',
        'Theme Logo',
        'theme_logo_media_field_html', // function which prints the field
        'custom-page-slug', // page slug
        'homepage_section', // section ID
        array( 
            'label_for' => 'theme_logo',
            'class' => 'custom-media-uploader',
        )
    );

    register_setting(
        'custom_page_settings', // settings group name
        'theme_logo', // field name
        'sanitize_text_field' // sanitization function
    );

}

The above action hook will register the setting field for ‘Theme Logo‘. You can customize it as you want. Now we will add HTML structure of that field to show on the custom setting page.

HTML Structure for Field

In the above code, add_settings_fields() method have a third parameter ‘theme_logo_media_field_html‘ that is refrencing to HTML structure of the field.

So now we will make that HTML structure function to show that field on custom options setting page. Look at the following code.

function theme_logo_media_field_html() {
    $theme_logo = get_option( 'theme_logo' );
    if($theme_logo) {
        ?>
            <a href="#" class="custom-upload-button button"><img src="<?php echo $theme_logo; ?>" width="20%"/></a>
            <a href="#" class="custom-upload-remove">Remove image</a>
            <input type="hidden" name="theme_logo" value="">
        <?php
    } else {
        ?>
            <a href="#" class="custom-upload-button button">Upload image</a>
            <a href="#" class="custom-upload-remove" style="display:none;">Remove image</a>
            <input type="hidden" name="theme_logo" value="">
        <?php
    }
}

Simply add the above code in functions.php file too and you will see the ‘Upload image’ button. But nothing will happen by clicking on it because we haven’t added the jQuery code yet.

jQuery Media Button Code

So let’s add the jquery part of media uploader button in wordpress. You can enqueue this code with action hook directly or you can create the separate .js file.

I would recommand to create a new separate file called ‘scripts.js‘ but name dose not matter you can take anything.

So I have created file ‘scripts.js‘ file with following code. You also put the following code in that file san save it.

jQuery(document).ready(function($) {

	// upload function
	$('body').on( 'click', '.custom-upload-button', function(e){
		e.preventDefault();
		var upload_button = $(this),
		custom_media_uploader = wp.media({
			title: 'Insert image',
			library : {
				type : 'image'
			},
			button: {
				text: 'Use this image'
			},
			multiple: false
		}).on('select', function() {
			var attachment = custom_media_uploader.state().get('selection').first().toJSON();
			upload_button.html('<img decoding="async" src="'%20+%20attachment.url%20+%20'" width="20%">');
			$('.custom-upload-remove').show().next().val(attachment.url);
		}).open();
	
	});

	// remove function
	$('body').on('click', '.custom-upload-remove', function(e){
		e.preventDefault();
		var upload_button = $(this);
		upload_button.next().val('');
		upload_button.hide().prev().html('Upload image');
	});

});

So you have successfully added js code in file and now only one last thing is left to enqueue this file and media library file.

Enqueue Script Files

We will use the admin_enqueue_scripts action and wp_enqueue_script() method to enqueue the js script file and the media file. It will embed our js script file and wordpress media file in header of admin side only.

Add the following code in functions.php file and save it.

add_action( 'admin_enqueue_scripts', 'custom_script_js' );

function custom_script_js() {
    
    if ( ! did_action( 'wp_enqueue_media' ) ) {
        wp_enqueue_media();
    }
 
    wp_enqueue_script( 'custom-media-uploader', get_stylesheet_directory_uri() . '/scripts.js', array( 'jquery' ) );
}

After saving the above code, go to that setting page and you will see all the fields there. Now when you click on the ‘Upload image’ button it will open the WordPress media library popup, you can select the image or you can upload there new file.

When you have selected the image and click on Save setting button, you will see your image is saving along with other fields.

Conclusion

So in this tutorial, you learned about how to add custom media uploader button in wordpress on custom options page. You can also add on meta boxes, posts or pages, etc.

First we register the settings for the field using the add_settings_field() and register_setting() methods. Then create the HTML structure for the field and then enqueue the custom script file and media library file using the wp_enqueue_media() and wp_enqueue_script() methods.

That’s it!!!

If you have any question please do let me know in the comment section, I will get back to you as soon as possible.