WordPress Media Uploader Custom Fields can be used for storing various information. You can create a relationship between other data such as adding users to the picture or writing additional information about the image. In this tutorial we will learn how to add custom fields to the media uploader.

We will create two fields here:

  1. Info – textarea
  2. Tags – checkboxes to tag users

Adding a WordPress Media Uploader Custom Field

To add a field you need to filter the hook attachment_fields_to_edit such as this:

You then add a field by providing the field key/name as key and then an array that will define the field. To see some of the default fields that are set there, go to wp-admin/media.php and find the function get_attachment_fields_to_edit.

Saving a Custom Field

When we add a field, we also need to save it. This can be done in hooks edit_attachment or attachment_fields_to_save. The first hook is an action and the second one is a filter.

Since filters return data, if you are using the second one, you will need to return the $post. This filter can be also used to set error messages.

Adding a Media Uploader Textarea Field

Let’s now do some actual coding. We will now add a simple textarea field and save it. Let’s see how to add a custom field:

First, we are getting the value for the provided attachment ($post). After that we are adding that field here and providing the value parameter with the field’s value. To render our field as a textarea, we will have to set the parameter input to textarea.

Saving the Textarea Field

In this tutorial, I will work with the hook edit_attachment. We will use that hook to save the data.

We are checking if the field is set for our attachment by checking . That is because the custom fields are rendered like that. If that field has been posted, we will save the data.

You would need to validate it and sanitize it before saving it, but that is out of the scope of this tutorial.

Adding Media Uploader Field “Tags”

The Tags field will be a WordPress Media Uploader Custom Field that will render all our users and then we can tag them by checking them. We can look at it as we tag people on Facebook.

Here we are getting the tags from the database inside the variable $tags. We are also getting all the users registered in our WordPress site. Next, we are creating a custom html that will hold all our users with checkbox next to their names.

Since the custom field is made in this way:

we will have to create the attribute name in similar way. We are adding the tag key with the user’s ID as a key.

The last part of adding this field is to extend the variable $form_fields with our field. To provide our custom html as the input’s output, we need to add that output to the parameter html and also assign 'html' to the parameter input.

List of checkboxes with user names next to it

Saving the WordPress Media Custom Field “Tags”

When we check or uncheck a user, WordPress will send a POST request to our site. Since all of those checkboxes will be in a form:

We will just need to get the tags which will be an array of key => value pair and save them:


Adding custom fields can be a challenging task. You need to know a little bit more than just writing custom HTMLs. The WordPress Plugin API provides us with the hooks so that we can extend the current fields with others.

Have you ever added a custom field to the attachment page? Please share your experience here with us:)

If you want to jump to an article, you can do it here:

  1. Introduction
  2. Edit Fields
  3. Embed Options
  4. Editor
  5. Custom Tab

Posted by Igor Benic

Web Developer who mainly uses WordPress for projects. Working on various project through Codeable & Toptal. Author of several ebooks at https://leanpub.com/u/igorbenic.


  1. Very useful, code worked well for me. Great job. Thanks for sharing.


    1. No problem Jethin! Thank you for reading and trying out the code.


  2. Hi Igor,

    Thank you for your great tutorial. It saved me a ton of timea and I applied the exapmles to add my own custom fields to one project I’m working on. But there’s one thing troubling my mind.

    How would you handle clearing the checkbox values? I mean – how would you save empty values?

    I kind of managed to create a working solution for this situation with a if-else statement that checked if the checkbox was set ,the same way you have on the last example on line 16. And if it wasn’t checked then the meta value would get deleted.

    I noticed my solution caused a problem, when updating the WP native media title, alt or description fields on the Media Library grid view attachment details dialog (I mean this, https://codex.wordpress.org/File:attachedfile-detail.png).

    The ajax call the details dialog makes when it saves the changes to the title, alt and description fields doesn’t include the custom fields (I checked browser dev tools > network > param). This basically means, that the custom checkboxes are “not set” even if they’re checked, but not changed. This in turn this fires my if-else statement and wipes the checkbox meta from the database and I have to re-check the checkboxes.

    So, would you have a suggestion what the if-else statement should be like to enable clearing the checboxes while protecting the saved checkbox values from getting wiped out by updates to other media file’s fields?


    p.s. My apologies if I explained myself in a unclear way.


    1. Hi Antti, does your solution follow the code in this article or is it implemented in another way?


Leave a reply

Your email address will not be published. Required fields are marked *