Super Plugin Sale! Your Choice: BOGO or 30% Off »
Web Dev + WordPress + Security

WordPress Custom Fields, Part I: The Basics

[ Magnetic Fields ] I recently developed a theme that makes heavy use of WordPress’ custom fields. The custom-field functionality of WordPress makes it possible to rig up just about any customized layout quickly and easily. Custom fields enable designers to organize post content into different sections, making it possible to create non-linear page layouts, with different types of content easily removed from the normal post loop and relocated to different parts of the document. This organizational and design flexibility has the added benefit of making it super-easy to update your content, redesign your theme, and handle blog maintenance in general. In the first part of this mini-series, we walk through the process of implementing and using custom fields; then, in part two, I will share some delicious tips and tricks to help you get the most out of everything that custom fields have to offer.

Learning by example: Custom image gallery

To help us understand the process of implementing and using custom fields, let’s imagine a hypothetical design scenario wherein you would like to represent each of your posts with a unique thumbnail image. Specifically, in your sidebar, you would like to display the ten most-recent of these thumbnail images as links to their corresponding posts, thereby enabling users to browse the images and follow through to the full post at their convenience. While there are probably several ways to accomplish this configuration, we are going to take advantage of WordPress’ custom-field functionality to learn about custom fields while getting the job done.

Step 1: Add custom images to posts

The first thing we need to do is to add the custom images to our posts. So, let’s say we currently have three posts, and will be writing many more posts in the future. Open the first post in the admin edit screen and scroll down to the “Custom Fields” area. Each custom field requires two parts: a “key” and a “value”. For this tutorial, our key will be specifying different “post-icon” values, so let’s use “post-icon” as the name of the key. If the key has been used at least once before, it will be available in the “Custom Fields” drop-down menu like so:

Update: In the Admin Area, WordPress now refers to a custom field’s “Key” as its “Name”. So for custom fields, “key” and “name” refer to the same thing.
[ Screenshot: Pre-populated 'Key' field dropdown menu ]
Existing custom fields will be displayed in the dropdown menu

If the key is not listed in the drop-down menu (or if the drop-down menu fails to appear), we will need to add it by filling out the “Key” field. As this is the first post we are editing, we will create a key called “post-icon”, like so:

[ Screenshot: 'post-icon' value entered in 'Key' field ]
If the custom key value does not yet exist, we can enter it manually

Once the key has been specified in the appropriate field, we need to add its corresponding value. For this tutorial, we want each post to have its own custom thumbnail image, so we will use the image path as the value for this post’s “post-icon” key. Depending on the location of your custom images, your custom-field key/value pair should look like this:

[ Screenshot: Both 'Key' and 'Value' fields populated with data ]
With both "Key" and "Value" fields populated, we are all set

Click the “Add Custom Field” button to activate the custom field for the current post. Once done, this information is available to us in our WordPress theme files, thereby enabling us to call and display the custom post-images however necessary. Of course, the process we just went through should be repeated for all existing and future posts for which you would like to associate custom post-icon thumbnail images.

Step 2: Call and display the custom images

With the custom fields added to our posts, we are now ready to tap into some core WordPress functionality and display our custom post-images in the desired fashion. The function we will be using to retrieve the images is as follows:

<?php get_post_meta(); ?>

This is a native WordPress function designed to retrieve specific custom-field key values. The get_post_meta() function takes the following parameters:

  • $post_id — defines the post from which the custom-field data is called
  • $key — defines the key of the desired custom-field meta value
  • $single — specifies whether to return the data as a string or as an array

Plugged into the get_post_meta() function, these parameters look like this:

<?php get_post_meta($post_id, '$key', $single); ?>

To specify the ID parameter, $post_id, for each post, we use “$post->ID”, which requires the function to be placed within the loop. For the $key parameter, we will use the name of the target key, which in this case is “post-icon”. And finally, because we want the key value returned as a string, we use “true” for the $single parameter.

So at this point our get_post_meta() function looks like this:

<?php get_post_meta($post->ID, 'post-icon', true); ?>

And we are almost there. As is, this code will simply return the custom-field value without printing it to the web page. So, we make one final edit to echo the data to the browser:

<?php echo get_post_meta($post->ID, 'post-icon', true); ?>

When placed in the loop, this function will output each post’s “post-icon” custom-field value, which at this point is simply a URL to the specific thumbnail image. For example:


Not very useful for your visitors, however, by enclosing our function with a little code, we can easily transform that URL into an actual image that links to its corresponding post:

<a href="<?php the_permalink() ?>" title="<?php the_title(); ?>">
	<img src="<?php echo get_post_meta($post->ID, 'post-icon', true); ?>" alt="Icon for Post #<?php the_ID(); ?>" />

That’s the ticket right there! Each post now includes its own custom icon that links directly to the single view of the post itself. In the next section, we will remove these custom images from their associated posts and display them in your sidebar as a consecutive thumbnail gallery.

Step 3: Display image gallery in teh sidebar

At this point, everything is setup, configured, and working great. We are successfully displaying custom post images that link to their associated posts. Now, to demonstrate the usefulness of WordPress custom fields, let’s remove our custom images from their respective posts and display them as a consecutive gallery within the sidebar.

So instead of displaying this in the main column:

first post title
first post content
first custom image

second post title
second post content
second custom image

third post title
third post content
third custom image

..we will display this in the sidebar:

first custom image

second custom image

third custom image

Without using custom fields, it is practically impossible to segregate intra-post data in this way. In other words, if we were to have included the custom-image URL along with the main post content, there would be no practical way1 of separating the information from the remainder of the post; they would always need to be displayed together. By placing the URL data within a custom field, however, we are able to display the custom data wherever and however we wish. In our current example, we are going to sequester the thumbnail images into the sidebar.

The catch here is that our get_post_meta() function requires the loop in order to work. Thus, to display our thumbnails in the sidebar, we will need to create a secondary loop within the sidebar itself. Fortunately, we have a number of tools at our disposal. For this tutorial, let’s go with everybody’s favorite loop function, query_posts. Without going into detail about the query_posts() function, suffice it to say that it is an excellent way to create multiple, customized loops and display them anywhere in the theme template. So with that in mind, here is the basic structure of our second loop:

<?php query_posts(); ?>
<?php if (have_posts()) : while (have_posts()) : the_post(); ?>

// content goes here

<?php endwhile; endif; ?>

Then after adding the secondary loop to our sidebar, we embellish it like so:

<?php query_posts('showposts=10&offset=0'); ?>
<?php if (have_posts()) : while (have_posts()) : the_post(); ?>
<a href="<?php the_permalink() ?>" title="<?php the_title(); ?>">
	<img src="<?php echo get_post_meta($post->ID, 'post-icon', true); ?>" alt="Icon for Post #<?php the_ID(); ?>" />
<?php endwhile; endif; ?>

As you can see, in the first line, we added two parameters — the first specifies the total number of loop cycles (ten, in our example), and the second indicates that we want the loop to begin with the most recent item (i.e., no offset). Beyond that bit of voodoo, we simply copy-&-pasted our previously marked-up get_post_meta() function into the “content goes here” portion of the loop.

Once we upload our newly edited sidebar.php file to the server, our web pages will feature the desired result: a nice thumbnail image gallery respectively linked to the ten most recent posts. Ahhhh.. feels so good! ;) Now let’s move on to some juicy custom-field tips and tricks! Actually, by the time I had finished this post, it was waayy too long (even by my standards) to publish as a single article. Thus, to alleviate the pain, I am breaking this post up into two parts. Stay tuned for Part II: Custom Field Tips and Tricks!


1 I say “practical” because just about anything is possible with the right knowledge ;)

About the Author
Jeff Starr = Creative thinker. Passionate about free and open Web.
GA Pro: Add Google Analytics to WordPress like a pro.

40 responses to “WordPress Custom Fields, Part I: The Basics”

  1. Nice write up Jeff. I too use custom fields in my blog. I agree with you, without CF, I wouldn’t know how to give each blog post its unique look. I mostly use CFs for css settings. I did a quick tutorial on this you may be interested in:

    Same concept though.

  2. Jeff Starr 2008/12/17 5:03 pm

    Hi Jin, thanks for the visit and for sharing your custom-fields post. Your tutorial is well-written and provides additional information not covered in this article. There is certainly no lack of custom-field information out there, but I always find that writing about a topic is a great way to understand the information at a deeper level. Hopefully both of our articles will further help the growing WordPress community take advantage of custom fields in their own designs. Cheers! :)

  3. Wow, nice tutorial, i want implement it in my bog :)

  4. Excellent intro to the use of custom fields, Jeff. Folks need to learn this stuff, and your presentation is so easy to follow. I doubt, however, that I’ll be implementing it in my bog, nor in my kitchen or garage come to that ;)

    Oh, and ‘teh sidebar’. You are so a joker 2.0, dude you crack me up!

    Happy holidays and thanks again! You’re a star.


  5. Custom fields are definitely a valuable wordpress tool in creating that special look. I don’t know what I would do without them on other sites.

  6. Custom fields are great. They really add a whole lot of flexibility. On our site, we use custom fields for small galleries (similar to your example above), as well as for certain other template items (and features) that aren’t built in to WordPress.

    Great tutorial. It might be a good idea to link to this article from the WP Codex.

  7. @Jeff M: Thanks for the positive feedback! I think custom fields would work great in your garage! LOL ;) Happy Holidays to you as well! Thanks for being a part of Perishable Press in 2008 — looking forward to hearing more from you in 2009! Cheers!

    @Susan: That is definitely the take-home message for this post: you can achieve virtually any layout by using the functionality of WordPress custom fields. Thanks for the comment :)

    @Shirley: I totally agree, I have been using them more and more on the sites I develop. Even for segregating things like subtitles, footnotes, and code examples, custom fields enable long-term design flexibility. They are a little more work up front, but definitely pay off in the long run. Also, thanks for the idea of linking from the Codex — hopefully others will find it helpful as well!

  8. Interesting. I use a theme in one of my blogs with a custom field to enter an image name which will b used as a thumb nail for the post. It really changed the appearance of the entire blog, thanks to WP custom fields.

    Btw. Nice article, Bookmarked. :)

  9. Wow another mind-blowing post, Jeff! Seriously, your tutorials are extremely useful and they appeal to me very much like what a WordPress-centered Wiki will. Although there are a lot of information out there on WordPress custom fields (like on WP Codex), yours is the most comprehensive on so far (and it’s only part one, golly!).

    I’ve never been able to understand custom fields completely, even when I’ve googled for how we should use them, in the shoes of a designer or a blogger. I never knew that so much can be done with custom fields and how helpful it can be when it comes to delivering custom content to readers.

    What really surprises me is that to extract information from custom fields, a simple loop is what we really need (with some knowledge of WP php tags, that is) – it’s fairly straightforward and simple. Thank you so much for sharing the important codes – they are a really good headstart for amateurs like me.

    And when I’m done with dinner, I’ll continue with Part II ;) thanks!

    p/s: There’s a minor typo for the H2 header for Step 3: “the” instead of “teh”. I’m sorry :P

  10. @Hemanth: Absolutely! Thanks for the positive feedback — Much appreciated :)

    @teddY: You are too kind! Thank you for the great comment. It is very encouraging to hear that my articles are useful and appreciated. They do take some time to produce, but hearing such excellent feedback really fuels the fire and encourages me to keep on sharing this type of information. Great to hear from you teddY — I hope you enjoy “Part II” as well! (oh, and the typo was intentional — an attempt at a little “leet speak”! Thanks for pointing it out though!:) Cheers and Happy New Year to you and yours! :)

  11. what a descriptive post for custom fields, never understood before its functionality and now at least i understand its basics.
    the more i read,i will get it.
    Many Thanks Bro!

  12. Jeff Starr 2009/01/03 6:23 pm

    @eddai: My pleasure — glad to be of service! :)

Comments are closed for this post. Something to add? Let me know.
Perishable Press is operated by Jeff Starr, a professional web developer and book author with two decades of experience. Here you will find posts about web development, WordPress, security, and more »
BBQ Pro: The fastest firewall to protect your WordPress.
All free plugins updated and ready for WP 6.6 dropping next week. Pro plugin updates in the works also complete :)
99% of video thumbnail/previews are pure cringe. Goofy faces = Clickbait.
Crazy that we’re almost halfway thru 2024.
I live right next door to the absolute loudest car in town. And the owner loves to drive it.
8G Firewall now out of beta testing, ready for use on production sites.
It's all about that ad revenue baby.
Get news, updates, deals & tips via email.
Email kept private. Easy unsubscribe anytime.