Menu Search
Jump to the content X X
Smashing Conf San Francisco

You know, we use ad-blockers as well. We gotta keep those servers running though. Did you know that we publish useful books and run friendly conferences — crafted for pros like yourself? E.g. our upcoming SmashingConf San Francisco, dedicated to smart front-end techniques and design patterns.

How To Create Custom Post Meta Boxes In WordPress

What seems like one of the most complicated bits of functionality in WordPress is adding meta boxes to the post editing screen. This complexity only grows as more and more tutorials are written on the process with weird loops and arrays. Even meta box “frameworks” have been developed. I’ll let you in on a little secret though: it’s not that complicated.


Creating custom meta boxes is extremely simple, at least it is once you’ve created your first one using the tools baked into WordPress’ core code. In this tutorial, I’ll walk you through everything you need to know about meta boxes:

  • Creating meta boxes.
  • Using meta boxes with any post type.
  • Handling data validation.
  • Saving custom meta data.
  • Retrieving custom meta data on the front end.

Note: When I use the term “post” throughout this tutorial, I’m referring to a post of any post type, not just the default blog post type bundled with WordPress.

What is a post meta box? Link

A post meta box is a draggable box shown on the post editing screen. Its purpose is to allow the user to select or enter information in addition to the main post content. This information should be related to the post in some way.

Generally, two types of data is entered into meta boxes:

  • Metadata (i.e. custom fields),
  • Taxonomy terms.

Of course, there are other possible uses, but those two are the most common. For the purposes of this tutorial, you’ll be learning how to develop meta boxes that handle custom post metadata.

What is post metadata? Link

Post metadata is data that’s saved in the wp_postmeta table in the database. Each entry is saved as four fields in this table:

  • meta_id: A unique ID for this specific metadata.
  • post_id: The post ID this metadata is attached to.
  • meta_key: A key used to identify the data (you’ll work with this often).
  • meta_value: The value of the metadata.

In the following screenshot, you can see how this looks in the database.

When you get right down to it, metadata is just key/value pairs saved for a specific post. This allows you to add all sorts of custom data to your posts. It is especially useful when you’re developing custom post types.

The only limit is your imagination.

Note: One thing to keep in mind is that a single meta key can have multiple meta values. This isn’t a common use, but it can be extremely powerful.

Working with post metadata Link

By now, you’re probably itching to build some custom meta boxes. However, to understand how custom meta boxes are useful, you must understand how to add, update, delete, and get post metadata.

I could write a book on the various ways to use metadata, but that’s not the main purpose of this tutorial. You can use the following links to learn how the post meta functions work in WordPress if you’re unfamiliar with them.

The remainder of this tutorial assumes that you’re at least familiar with how these functions work.

The setup Link

Before building meta boxes, you must have some ideas about what type of metadata you want to use. This tutorial will focus on building a meta box that saves a custom post CSS class, which can be used to style posts.

I’ll start you off by teaching you to develop custom code that does a few extremely simple things:

  • Adds an input box for you to add a custom post class (the meta box).
  • Saves the post class for the smashing_post_class meta key.
  • Filters the post_class hook to add your custom post class.

You can do much more complex things with meta boxes, but you need to learn the basics first.

All of the PHP code in the following sections goes into either your custom plugin file or your theme’s functions.php file.

Building a custom post meta box Link

Now that you know what you’re building, it’s time to start diving into some code. The first two code snippets in this section of the tutorial are mostly about setting everything up for the meta box functionality.

Since you only want your post meta box to appear on the post editor screen in the admin, you’ll use the load-post.php and load-post-new.php hooks to initialize your meta box code.

/* Fire our meta box setup function on the post editor screen. */
add_action( 'load-post.php', 'smashing_post_meta_boxes_setup' );
add_action( 'load-post-new.php', 'smashing_post_meta_boxes_setup' );

Most WordPress developers should be familiar with how hooks work, so this should not be anything new to you. The above code tells WordPress that you want to fire the smashing_post_meta_boxes_setup function on the post editor screen. The next step is to create this function.

The following code snippet will add your meta box creation function to the add_meta_boxes hook. WordPress provides this hook to add meta boxes.

/* Meta box setup function. */
function smashing_post_meta_boxes_setup() {

  /* Add meta boxes on the 'add_meta_boxes' hook. */
  add_action( 'add_meta_boxes', 'smashing_add_post_meta_boxes' );

Now, you can get into the fun stuff.

In the above code snippet, you added the smashing_add_post_meta_boxes() function to the add_meta_boxes hook. This function’s purpose should be to add post meta boxes.

In the next example, you’ll create a single meta box using the add_meta_box()5 WordPress function. However, you can add as many meta boxes as you like at this point when developing your own projects.

Before proceeding, let’s look at the add_meta_box() function:

add_meta_box( $id, $title, $callback, $page, $context = 'advanced', $priority = 'default', $callback_args = null );
  • $id: This is a unique ID assigned to your meta box. It should have a unique prefix and be valid HTML.
  • $title: The title of the meta box. Remember to internationalize this for translators.
  • $callback: The callback function that displays the output of your meta box.
  • $page: The admin page to display the meta box on. In our case, this would be the name of the post type (post, page, or a custom post type).
  • $context: Where on the page the meta box should be shown. The available options are normal, advanced, and side.
  • $priority: How high/low the meta box should be prioritized. The available options are default, core, high, and low.
  • $callback_args: An array of custom arguments you can pass to your $callback function as the second parameter.

The following code will add the post class meta box to the post editor screen.

/* Create one or more meta boxes to be displayed on the post editor screen. */
function smashing_add_post_meta_boxes() {

    'smashing-post-class',      // Unique ID
    esc_html__( 'Post Class', 'example' ),    // Title
    'smashing_post_class_meta_box',   // Callback function
    'post',         // Admin page (or post type)
    'side',         // Context
    'default'         // Priority

You still need to display the meta box’s HTML though. That’s where the smashing_post_class_meta_box() function comes in ($callback parameter from above).

/* Display the post meta box. */
function smashing_post_class_meta_box( $object, $box ) { ?>

  <?php wp_nonce_field( basename( __FILE__ ), 'smashing_post_class_nonce' ); ?>

    <label for="smashing-post-class"><?php _e( "Add a custom CSS class, which will be applied to WordPress' post class.", 'example' ); ?></label>
    <br />
    <input class="widefat" type="text" name="smashing-post-class" id="smashing-post-class" value="<?php echo esc_attr( get_post_meta( $object->ID, 'smashing_post_class', true ) ); ?>" size="30" />
<?php }

What the above function does is display the HTML output for your meta box. It displays a hidden nonce input (you can read more about nonces6 on the WordPress Codex). It then displays an input element for adding a custom post class as well as output the custom class if one has been input.

At this point, you should have a nice-looking meta box on your post editing screen. It should look like the following screenshot.

The meta box doesn’t actually do anything yet though. For example, it won’t save your custom post class. That’s what the next section of this tutorial is about.

Saving the meta box data Link

Now that you’ve learned how to create a meta box, it’s time to learn how to save post metadata.

Remember that smashing_post_meta_boxes_setup() function you created earlier? You need to modify that a bit. You’ll want to add the following code to it.

/* Save post meta on the 'save_post' hook. */
add_action( 'save_post', 'smashing_save_post_class_meta', 10, 2 );

So, that function will actually look like this:

/* Meta box setup function. */
function smashing_post_meta_boxes_setup() {

  /* Add meta boxes on the 'add_meta_boxes' hook. */
  add_action( 'add_meta_boxes', 'smashing_add_post_meta_boxes' );

  /* Save post meta on the 'save_post' hook. */
  add_action( 'save_post', 'smashing_save_post_class_meta', 10, 2 );

The new code you’re adding tells WordPress that you want to run a custom function on the save_post hook. This function will save, update, or delete your custom post meta.

When saving post meta, your function needs to run through a number of processes:

  • Verify the nonce set in the meta box function.
  • Check that the current user has permission to edit the post.
  • Grab the posted input value from $_POST.
  • Decide whether the meta should be added, updated, or deleted based on the posted value and the old value.

I’ve left the following function somewhat generic so that you’ll have a little flexibility when developing your own meta boxes. It is the final snippet of code that you’ll need to save the metadata for your custom post class meta box.

/* Save the meta box's post metadata. */
function smashing_save_post_class_meta( $post_id, $post ) {

  /* Verify the nonce before proceeding. */
  if ( !isset( $_POST['smashing_post_class_nonce'] ) || !wp_verify_nonce( $_POST['smashing_post_class_nonce'], basename( __FILE__ ) ) )
    return $post_id;

  /* Get the post type object. */
  $post_type = get_post_type_object( $post->post_type );

  /* Check if the current user has permission to edit the post. */
  if ( !current_user_can( $post_type->cap->edit_post, $post_id ) )
    return $post_id;

  /* Get the posted data and sanitize it for use as an HTML class. */
  $new_meta_value = ( isset( $_POST['smashing-post-class'] ) ? sanitize_html_class( $_POST['smashing-post-class'] ) : '' );

  /* Get the meta key. */
  $meta_key = 'smashing_post_class';

  /* Get the meta value of the custom field key. */
  $meta_value = get_post_meta( $post_id, $meta_key, true );

  /* If a new meta value was added and there was no previous value, add it. */
  if ( $new_meta_value && '' == $meta_value )
    add_post_meta( $post_id, $meta_key, $new_meta_value, true );

  /* If the new meta value does not match the old value, update it. */
  elseif ( $new_meta_value && $new_meta_value != $meta_value )
    update_post_meta( $post_id, $meta_key, $new_meta_value );

  /* If there is no new meta value but an old value exists, delete it. */
  elseif ( '' == $new_meta_value && $meta_value )
    delete_post_meta( $post_id, $meta_key, $meta_value );

At this point, you can save, update, or delete the data in the “Post Class” meta box you created from the post editor screen.

Using the metadata from meta boxes Link

So you have a custom post meta box that works, but you still need to do something with the metadata that it saves. That’s the point of creating meta boxes. What to do with your metadata will change from project to project, so this is not something I can answer for you. However, you will learn how to use the metadata from the meta box you’ve created.

Since you’ve been building a meta box that allows a user to input a custom post class, you’ll need to filter WordPress’ post_class hook so that the custom class appears alongside the other post classes.

Remember that get_post_meta() function from much earlier in the tutorial? You’ll need that too.

The following code adds the custom post class (if one is given) from your custom meta box.

/* Filter the post class hook with our custom post class function. */
add_filter( 'post_class', 'smashing_post_class' );

function smashing_post_class( $classes ) {

  /* Get the current post ID. */
  $post_id = get_the_ID();

  /* If we have a post ID, proceed. */
  if ( !empty( $post_id ) ) {

    /* Get the custom post class. */
    $post_class = get_post_meta( $post_id, 'smashing_post_class', true );

    /* If a post class was input, sanitize it and add it to the post class array. */
    if ( !empty( $post_class ) )
      $classes[] = sanitize_html_class( $post_class );

  return $classes;

If you look at the source code of the page where this post is shown on the front end of the site, you’ll see something like the following screenshot.


Pretty cool, right? You can use this custom class to style posts however you want in your theme’s stylesheet.

Security Link

One thing you should keep in mind when saving data is security. Security is a lengthy topic and is outside the scope of this article. However, I thought it best to at least remind you to keep security in mind.

You’ve already been given a link explaining nonces earlier in this tutorial. The other resource I want to provide you with is the WordPress Codex guide on data validation7. This documentation will be your best friend when learning how to save post metadata and will provide you with the tools you’ll need for keeping your plugins/themes secure.

Bonus points to anyone who can name all of the security measures used throughout this tutorial.

Create a custom meta box Link

Once you’ve copied, pasted, and tested the bits of pieces of code from this tutorial, I encourage you to try out something even more complex. If you really want to see how powerful meta boxes and post metadata can be, try doing something with a single meta key and multiple meta values for that key (it’s challenging).

I hope you’ve enjoyed the tutorial. Feel free to post questions about creating meta boxes in the comments.


Footnotes Link

  1. 1
  2. 2
  3. 3
  4. 4
  5. 5
  6. 6
  7. 7
  8. 8
  9. 9
  10. 10
  11. 11

↑ Back to top Tweet itShare on Facebook


  1. 1

    Russell Heimlich

    October 4, 2011 8:40 am

    Metaboxes are such a key part of how we publish that I abstracted my own metabox class so I could create them with a few lines. You can also use whatever HTML you want and my script will parse the HTML to find the value attributes and fill in the data automagically!

    You can poke around the code here ->

  2. 2

    SUPER article. Thank you for simplifying what so many people have gone to great lengths to complicate!

    In a way of advancing this post – do you have an easy (non-plugin way) to add the tinyMCE (aka wysiwyg) while adding the metabox.

    • 3

      This is the code I use for a Tinmyce metabox:
      function myplugin_inner_custom_box() {
      // The actual fields for data entry
      $pid = $_GET[‘post’];
      global $wpdb;
      $value = ”;
      $valori = $wpdb->get_results(“SELECT meta_value FROM wp_postmeta WHERE post_id = $pid AND meta_key = ‘meta_key_name'”);
      foreach ($valori as $val) {
      $value = $val->meta_value;
      echo ‘<textarea id=”meta_key_name_box” type=”text” name=”meta_key_name” style=”width: 300px;margin-left: 30px”>’.$value.'</textarea>’;
      echo ‘<script type=”text/javascript”>
      /* <![CDATA[ */

      jQuery(document).ready( function () {
      if ( typeof( tinyMCE ) == “object” && typeof( tinyMCE.execCommand ) == “function” ) {

      tinyMCE.execCommand(“mceAddControl”, true, “meta_key_name_box”);


      /* ]]> */
      Unfortunately it’s got some problems (it does’nt save new paragraphs and has no wysiwyg/html switch)

  3. 4

    Wow ! Really helps in my current project :) Thanks a lot Justin – I’m a regular reader of your blog :)

  4. 5

    totally wish I had read this before I went custom field happy on my last project..

  5. 6

    Quick question: Is that possible to load everything in the backend and using non-WP tables? I’m currently a plugin (more an application) and I need to have my own tables for many reasons.

    I just want to know if I can create, let’s say a Player interface, without using the postmeta or post tables?


  6. 8

    I can only reinforce that it is SO important to be sure you only add the custom meta if the POST data exists as you have displayed above. I recently looked at a database for another WP site and there were around 60 empty database entries for every single post and page simply because there was no validation of content.

    BTW – The book is incredible if anyone is reading this comment. I have not bought a WP book since this one. Invaluable resource!

    esc_html__ , wp_nonce_field, wp_verify_nonce, current_user_can, sanitize_html_class

    Did I miss any?

  7. 11

    Good post…..any idea how to save your custom post meta box when the ajax save draft function is called?

    • 12

      The autosave function doesn’t save metadata correctly, this is a known WP bug and should be fixed in a next release. That’s why I disable autosave :)

  8. 13

    Dustin McGrew

    October 4, 2011 7:33 pm

    With all due respect.. and I mean that truthfully.. I’d love to see some posts about CMSs other than WordPress. Seems like almost every web development post here is about WordPress. Would love to see some Drupal posts. More CSS and jQuery is never a bad thing either.

  9. 16

    interesting post.
    i was wondering if it’s possible to use the custom meta box to display a list of the attachments linked to a post ?

    • 17

      Russell Heimlich

      October 4, 2011 12:58 pm

      Sure! You just wouldn’t need anything about saving or updating meta data. You could write the code to display something in the smashing_post_class_meta_box() function.

      • 18

        I was thinking about checkboxes in front of each item of the list to select some images to be added in a slideshow,

        or a another one with radio button to select an image as a background for example.

  10. 19

    Good post, but if anyone want to make this very scalable and dynamically, you can use the WP_Alchemy classes.
    Very good class support media upload, multi fields and more feature like displaying metaboxes for one post_type or more for more infos :

    • 20

      I whole heartedly agree. By using the WP_Alchemy class you are able to build multiple, dynamically generated metaboxes, and setting up the back and front end is a breeze, I highly recommend anyone that uses metaboxes on a regular basis to try WP_Alchemy, you will not be disappointed, in fact it will be one of those “I can’t live with out it” pieces of code.

    • 22

      I was about to post the very same suggestion! WPAlchemy rocks!!! +1

    • 23

      Justin Tadlock

      October 6, 2011 1:07 pm

      This is one of the exact reasons I decided to write this tutorial.

      • 24

        Justin > Don’t like WPalchemy ? For a lot of non-devs/designers, it is really helpful and simple to use, no ?

  11. 25

    I believe this nifty little plugin can do just that, it’s very powerful
    and check their “More Types” plugin too.

    • 26

      Justin Tadlock

      October 6, 2011 1:04 pm

      How would the plugin/theme I develop use More Fields to serve up custom meta boxes to my plugin/theme users?

      • 27

        I agree that More Fields is a great plugin, but when creating themes to distribute for free or commercially, then this tutorial will be handy.

        It’d be freaking nice if More Fields can have an option to grab code….. just like Custom Post Types UI plugin does.

  12. 28

    Michael Beckwith

    October 4, 2011 10:21 pm

    Very nice work Justin. I used this to re-do my “template” file for my metabox uses, and hope to make it more efficient now.

  13. 29

    Is there a WordPress specific advantage to explicitly covering the add_post_meta() case?

    • 30

      Justin Tadlock

      October 4, 2011 1:58 pm

      Not really. update_post_meta() will be perfectly fine for that use case. I just wanted to show how the post meta functions could be used.

  14. 31

    Very useful tut – thanks bro!

  15. 32

    Very nice explained! When I was building my website I tried for days to make them work! And in the end, I gave up and used a plugin! :)) (It was the first time I was building a wordpress theme)
    Now, I will try again..

  16. 33

    Thank you very much for the tutorial, but I can’t see clearly which file every snippet belongs.

  17. 36

    Why is that whenever I read a crystal-clear explanation of some WordPress voodoo, it is written by Justin Tadlock?
    OK, there are a few others but Justin is doing more than anybody I can name to take us from newbies to experts.
    Thanks so much.

  18. 37

    John Surdakowski

    October 5, 2011 6:58 am

    Great article Justin. As always.

  19. 38

    actually i am loving you.


↑ Back to top