The Best Way to Build Custom Meta Boxes in WordPress?

meta box

Recently I needed to accomplish a specific chore for my job. I needed to make a meta box in the WordPress admin.

The image below shows an example of a simple meta box. In WordPress, in the admin area, any box that holds a part of the User Interface is called a meta box.

meta box

It’s not very hard to make a meta box, the documentation in the codex is excellent. But then I needed to put inside it something fairly complex: the ability for the editor to upload a random number of images to attach to the post. I’ll skip ahead a little bit and show you what I mean:

multiple file upload

The editor can press that “Add or Upload Files” button as many times as they want, attach as many images as they want, and the Admin user interface shows all attached images. It works great, and is exactly what I wanted.

The Problem

The thing I struggled with most in this scenario wasn’t HOW to build this, but rather what tool to use. I had three options.

  1. Build it all from scratch. Meta boxes aren’t hard to make at all, but the contents have an infinite capacity for complexity. And this box needed some fairly complex code.
  2. Use a framework. There are a number of WordPress meta box code frameworks to help accelerate a solution for this problem. They come with built in functions for doing many of the things I wanted to get done.
  3. Use a plugin. There are also many many WordPress plugins that will allow you to simply fill out some forms, maybe do a little dragging and dropping, and get exactly what I wanted for my meta box.

Determining a Solution

The place I work has a long standing tradition of writing things ourselves, because then we know they’re built properly. That said, we’re talking some pretty serious clock time, and that means client dollars.

Using a plugin would probably have been the fastest method. Advanced Custom Fields is an extremely popular, powerful plugin for this. Just install it, fill out some forms, and I’m all set, right?  The problem is that many plugins like ACF store all the setup for the admin user interface in the database. This makes it a lot less configurable and creates many more database calls per page load.

In the end I used a framework called CMB2, or Custom Meta Boxes 2. I was able to write just a little code as in the image below.

cmb2 code

That code gave me the wonderful User Interface I showed at the beginning of the post. The code I write is concise, yet flexible and testable.

What made this the right tool?

I can’t say I picked CMB2 because it was the best option for every site. Any one of my options could have worked for me. The lazy part of me would have loved to use Advanced Custom Fields (although honestly I could CMB2 easier to understand). I actually picked CMB2 because it was right for the project.

It had just the right balance of accelerating the project without sacrificing too much in the way of speed or flexibility.

Since I was relying on it so heavily, I actually installed it as a Must Use Plugin, which means the client can’t accidentally deactivate it and break things. This makes it feel a lot more like part of WordPress core to the client.

The moral of the story

When learning to work with WordPress, you almost always have multiple tools available to you. Try to gain familiarity with as many of them as you can. As your toolbox gets bigger you’ll have more and more wisdom about how to solve problems, and solving problems is where your real value lies as a developer.

Anyone can take their favorite plugin and twist and turn it to make it do what they want. But if you have 5, or 10, or 100 favorite plugins, or frameworks, or whatever, then you start to understand problems, and present solutions, not software packages.

Then you’re a powerful developer.


  • Topher DeRosia

    Topher is an accomplished programmer, having written his own content management systems and managed some very large websites. He loves to help people and believes playing with WordPress is fun. Topher lives in Michigan, USA.

    View all posts
0 0 votes
Article Rating
Notify of

Newest Most Voted
Inline Feedbacks
View all comments
Lauren Carter
Lauren Carter
9 years ago

Good one

9 years ago

CMB2 is great. But there’s probably an even faster way of adding meta boxes.
Pods uses CMB2 under the hood. [url=][/url]

9 years ago

Never heard of CMB2, I always use Meta Box: [url=][/url]

9 years ago

This is Great wonderful information.. Thanks

Ryan Nguyen
Ryan Nguyen
8 years ago

I use Meta Box ([url=][/url]) for all of my projects, luv it 🙂

Sam Deacon
Sam Deacon
7 years ago

What are the other alternatives? I’m always keen to try out new cmb2/acf type plugins

6 years ago

Thank you. You speak from my heart as a junior developer. I have tried ACF, discarded it in favour of CUSTOM FIELD SUITE and – for now – arrived at CMB2, independent of your article. Still I am curious. But for now, I am happy to use CMB2. Thanks to the developers and community of CMB2. Greentings from Germany.

Would love your thoughts, please comment.x