Using WordPress Media Uploader (

I am writing this post as of WordPress 4.0, so this has nothing to with the ‘thickbox’ implementation in older versions of WordPress. It has been a long while since the new media library was implementated, but it has not been widely documented.

Tom McFarlin has written quite a comprehensive series titled Getting Started with the WordPress Media Uploader. However, his code had only covered usage of it in a edit/add post setting.

When using, there are a few things that we are interested. The first one is how to define the media frame. Tom has defined it this way:

file_frame = ={
    frame: 'post',
    state: 'insert',
    multiple: false

Note that frame: 'post' defines that our frame will be similar to the one we see when we add media in the tinymce editor. There are cases when we are using the media frame apart from the Post setting (e.g. in theme options or a plugin settings page), we need to define it as frame: select' , and state: 'insert' has to be removed.

Also, there are more arguments that the object can take. Doing a console.log on file_frame after defining it might be useful if you want to dig deeper. But the below is what I’ve used in most cases:

file_frame = ={
   className: 'media-frame foundation-image-frame',
   frame: 'select'
   multiple: false,
   title: 'Select Media',
   library: { 
      type: 'image' // limits the frame to show only images
   button: { 
      text : 'Select'

The second thing that we are interested in is how to capture the event when we have selected the image(s) and clicked on the Select button.

Tom has defined it for a Post Setting this way:

file_frame.on( 'insert', function() {
   // Do things on insert event

As expected, this will only work for frame: 'post' . For frame: 'select', we will have to do this:

file_frame.on( 'select', function() {
   // Do things on select event

Alright, hope this is useful!

5 thoughts on “Using WordPress Media Uploader (”

  1. Hi,

    Does this have any option to set the image size before upload?

    or do I have to do that with php?


  2. How can I translate the .on() bit so that it’s using vanilla JavaScript instead of jQuery? I’ve tried using .addEventListener("select"), but that throws an error TypeError: file_frame.addEventListener is not a function.

    • Hi Jacob, that is because file_frame is a javascript object with its own defined methods and handlers. I suppose it is not a regular EventTarget and thus does not have .addEventListener() method. You might want to do console.log(file_frame) to look at this object, and you will see what I mean.

    • Hi Mark,

      Well, one easy way will be use a plugin like Restrict Media Libaray Access.

      Or if you prefer otherwise, you might want to try adding a filter to your functions:

      add_filter( 'ajax_query_attachments_args', function( $query ) {
          $user_id = get_current_user_id();
          if ( $user_id && !current_user_can('create_users') ) {
              $query['author'] = $user_id;
          return $query;

      You’ll want to change the capability type for current_user_can depending on who can see all images, and who else can only see what they have uploaded. The above example shows all images to superadmins/admins (depending on whether the WordPress installation is a multisite or singlesite), and other type of users see only their own uploads. So if you want more fine grained control, this ‘if statement’ is where you want to set your limits.

      For reference on the above filter, see here:


Leave a Comment