Attention Interested in functions, hooks, classes, or methods? Check out the new WordPress Code Reference!

Javascript Reference/wp.media

This page is marked as incomplete. You can help Codex by expanding it.


wp.media is used to handle and control the admin media modal. For instance, custom image selector/uploader controls and meta boxes. It is located in the wp scope/namespace.


One key use of this class is to create a custom image upload/select link. Let's assume you are creating a custom admin meta box with an image upload link, similar to the Set Featured Image link for WordPress posts.

To be able to use the JavaScript-API, you first have to init all the needed JavaScript-Libraries and Styles:


Your meta box PHP might look like this...

global $post;

// Get WordPress' media upload URL
$upload_link = esc_url( get_upload_iframe_src( 'image', $post->ID ) );

// See if there's a media id already saved as post meta
$your_img_id = get_post_meta( $post->ID, '_your_img_id', true );

// Get the image src
$your_img_src = wp_get_attachment_image_src( $your_img_id, 'full' );

// For convenience, see if the array is valid
$you_have_img = is_array( $your_img_src );

<!-- Your image container, which can be manipulated with js -->
<div class="custom-img-container">
    <?php if ( $you_have_img ) : ?>
        <img src="<?php echo $your_img_src[0] ?>" alt="" style="max-width:100%;" />
    <?php endif; ?>

<!-- Your add & remove image links -->
<p class="hide-if-no-js">
    <a class="upload-custom-img <?php if ( $you_have_img  ) { echo 'hidden'; } ?>" 
       href="<?php echo $upload_link ?>">
        <?php _e('Set custom image') ?>
    <a class="delete-custom-img <?php if ( ! $you_have_img  ) { echo 'hidden'; } ?>" 
        <?php _e('Remove this image') ?>

<!-- A hidden input to set and post the chosen image id -->
<input class="custom-img-id" name="custom-img-id" type="hidden" value="<?php echo esc_attr( $your_img_id ); ?>" />

To properly control the above HTML, you would use the following Javascript...


  // Set all variables to be used in scope
  var frame,
      metaBox = $('#meta-box-id.postbox'), // Your meta box id here
      addImgLink = metaBox.find('.upload-custom-img'),
      delImgLink = metaBox.find( '.delete-custom-img'),
      imgContainer = metaBox.find( '.custom-img-container'),
      imgIdInput = metaBox.find( '.custom-img-id' );
  addImgLink.on( 'click', function( event ){
    // If the media frame already exists, reopen it.
    if ( frame ) {
    // Create a new media frame
    frame = wp.media({
      title: 'Select or Upload Media Of Your Chosen Persuasion',
      button: {
        text: 'Use this media'
      multiple: false  // Set to true to allow multiple files to be selected

    // When an image is selected in the media frame...
    frame.on( 'select', function() {
      // Get media attachment details from the frame state
      var attachment = frame.state().get('selection').first().toJSON();

      // Send the attachment URL to our custom image input field.
      imgContainer.append( '<img src="'+attachment.url+'" alt="" style="max-width:100%;"/>' );

      // Send the attachment id to our hidden input
      imgIdInput.val( attachment.id );

      // Hide the add image link
      addImgLink.addClass( 'hidden' );

      // Unhide the remove image link
      delImgLink.removeClass( 'hidden' );

    // Finally, open the modal on click
  delImgLink.on( 'click', function( event ){


    // Clear out the preview image
    imgContainer.html( '' );

    // Un-hide the add image link
    addImgLink.removeClass( 'hidden' );

    // Hide the delete image link
    delImgLink.addClass( 'hidden' );

    // Delete the image id from the hidden input
    imgIdInput.val( '' );



For more information on adding custom meta boxes to WordPress, see add_meta_box() or the Example Meta Box Plugin on Github


This is defined by /wp-includes/js/media-models.js

External Resources