How to Use the WordPress Media Uploader in Custom Settings Pages

The WordPress media uploader provides an exceptional user experience that even beginners can master within minutes. When developing custom WordPress settings pages that require image uploads, leveraging this built-in tool is far superior to building a custom upload solution from scratch.

In this guide, we’ll walk through a simple implementation using JavaScript and PHP to integrate the native WordPress media uploader into your custom admin fields.

1. Implementing the JavaScript Logic

First, create a JavaScript file (e.g., media-uploader.js) within your theme or plugin directory with the following code. This script handles the opening of the media frame and the population of the selected image URL into your form field.

jQuery(document).ready(function($){
   var mediaUploader;
   $('#upload_image_button').click(function(e) {

     e.preventDefault();

     // If the uploader object has already been created, reopen the dialog
     if (mediaUploader) {
       mediaUploader.open();
       return;
     }

     // Extend the wp.media object
     mediaUploader = wp.media.frames.file_frame = wp.media({
       title: 'Choose Image',
       button: {
       text: 'Choose Image'
     }, multiple: false });

     // When an image is selected, run a callback
     mediaUploader.on('select', function() {
       var attachment = mediaUploader.state().get('selection').first().toJSON();

       // Insert the media URL into the target input field
       $('#background_image').val(attachment.url);
     });

     // Open the uploader dialog
     mediaUploader.open();
   });
 });

The logic is simple: when the #upload_image_button is clicked, the WordPress media frame opens. Once a user selects an image, the script captures the image’s URL and inserts it into the #background_image input field.

After saving the JS file, you must enqueue it in the WordPress admin area:

add_action('admin_enqueue_scripts', function () {
     // Enqueue the native media scripts and styles
     wp_enqueue_media();
     // Register and enqueue your custom script
     wp_register_script('media-uploader', plugins_url('media-uploader.js', __FILE__ ), array('jquery'));
     wp_enqueue_script('media-uploader');
 });

Note: We use the admin_enqueue_scripts hook because this functionality is intended for the WordPress backend. If you were implementing this on the frontend, you would use wp_enqueue_scripts instead.

2. Creating the Form Fields

With the JavaScript logic in place, you now need to add the corresponding HTML fields to your settings page. This includes a text input to hold the URL and a button to trigger the uploader.

<input id="background_image" type="text" name="background_image" value="<?php echo get_option('background_image'); ?>" />

<input id="upload_image_button" type="button" class="button-primary" value="Insert Image" />

The resulting interface will look like the image below. Clicking “Insert Image” launches the familiar WordPress media library interface, allowing you to upload new files or select existing ones.

For an even better user experience, you could further customize this by adding a hidden field to store the media ID (useful for retrieving different image sizes) and a live preview area to display a thumbnail of the selected image.