Learn how to add custom fields to posts and pages in WordPress with a PHP meta box. This guide shows how to create an editor input, save its value as post meta, and display it in a theme template using get_post_meta().
The four steps below build a single text field for both posts and pages. They use WordPress core APIs, a nonce, permission checks, input sanitization, and output escaping.
How Custom Fields and Meta Boxes Work
A custom field is a stored metadata value associated with a post ID. A meta box is the editor interface used to enter that value; adding the input alone does not save it or display it on your public website. In this example, custom_field is the form input name and custom_field_name is the stored meta key.
Before You Start
- Back up your site and test PHP changes on staging.
- Place steps 1–3 together in a small site-specific plugin or your child theme’s
functions.php. Step 4 belongs in the theme template where the value should appear. - Install each function only once. If you rename a function, update its hook or callback reference too.
- For a custom post type, add its identifier to the screen array in step 1. See our custom post type tutorial for registration details.
Step 1: Register a Meta Box for Posts and Pages
First, register the metabox that will hold our custom field. Add this to your theme’s functions.php file, or better, a small site-specific plugin.
/**
* Create the metabox
* @link https://developer.wordpress.org/reference/functions/add_meta_box/
*/
function custom_fields_metabox() {
add_meta_box(
'custom-fields-metabox',
'Custom Fields',
'display_custom_fields_metabox',
array( 'post', 'page' ), // Add to both posts and pages
'normal',
'default'
);
}
add_action('add_meta_boxes', 'custom_fields_metabox');
Note: The original version of this snippet only registered the metabox for 'post', with a comment suggesting you manually change it to 'page' if needed — despite the tutorial’s own title promising support for both. Since WordPress 4.4, the $screen parameter accepts an array, so passing array( 'post', 'page' ) as shown above adds the metabox to both post types at once, with no need to register it twice.
What each argument means:
'custom-fields-metabox'— the metabox’s unique ID.'Custom Fields'— the title shown on the metabox.'display_custom_fields_metabox'— the callback function that renders the metabox’s content.array( 'post', 'page' )— which post type(s) show this metabox. Add a custom post type’s slug here too if needed.'normal'— where on the screen the box appears (normal= main column,side= sidebar).'default'— the display priority within that context.
Step 2: Render the Custom Field Input
Next, render the actual input field inside the metabox, pre-filled with any existing value:
/**
* Render the metabox
* @param WP_Post $post The post object
*/
function display_custom_fields_metabox($post) {
// Add nonce for security and authentication.
wp_nonce_field( 'custom_fields_nonce_action', 'custom_fields_nonce' );
// Retrieve existing value for the custom field, if any
$custom_field_value = get_post_meta($post->ID, 'custom_field_name', true);
// Output the custom field input
echo '<label for="custom_field">Custom Field:</label>';
echo '<input id="custom_field" name="custom_field" type="text" value="' . esc_attr($custom_field_value) . '" />';
}
Step 3: Save the Custom Field Data
To make sure the value is actually saved when the post or page is updated, hook into save_post:
/**
* Save the metabox
* @param int $post_id The post ID
*/
function save_custom_fields( $post_id ) {
// Check if a nonce was submitted at all.
if ( ! isset( $_POST['custom_fields_nonce'] ) ) {
return;
}
// Check if the nonce is valid.
if ( ! wp_verify_nonce( $_POST['custom_fields_nonce'], 'custom_fields_nonce_action' ) ) {
return;
}
// Check if it's an autosave.
if ( wp_is_post_autosave( $post_id ) ) {
return;
}
// Check if it's a revision.
if ( wp_is_post_revision( $post_id ) ) {
return;
}
// Check if the user has permission to save this data.
if ( ! current_user_can( 'edit_post', $post_id ) ) {
return;
}
// Sanitize user input.
$custom_field_value = isset($_POST['custom_field']) ? sanitize_text_field($_POST['custom_field']) : '';
// Update the meta field in the database.
update_post_meta($post_id, 'custom_field_name', $custom_field_value);
}
add_action('save_post', 'save_custom_fields');
Warning: A common version of this save function has a real bug — it checks permissions and autosave/revision status using a variable called $campaign_id, which is never defined anywhere in the function (it appears to be a copy-paste leftover from an unrelated script). Calling current_user_can( 'edit_post', $campaign_id ), wp_is_post_autosave( $campaign_id ), and wp_is_post_revision( $campaign_id ) with an undefined variable means these checks run against null instead of the actual post ID — which can cause the permission check to behave incorrectly and, depending on your PHP error reporting settings, throw undefined-variable warnings on every single save. The corrected version above uses $post_id throughout, which is what these functions actually expect.
Note: The original also read the submitted field from $_POST['custom_field_name'], but the input’s name attribute in Step 2 is actually custom_field, not custom_field_name — a mismatch that means the value would never actually save. The corrected version reads from $_POST['custom_field'], matching the input’s real name. It also had a redundant nonce check (isset($nonce_name) checking a variable that was always set moments earlier by its own preceding line) rather than checking $_POST directly, which the corrected version does instead.
Step 4: Display the Custom Field in Your Theme
With the data saved, display it anywhere in your theme template files using get_post_meta():
$custom_field_value = get_post_meta(get_the_ID(), 'custom_field_name', true);
if (!empty($custom_field_value)) {
echo 'Custom Field Value: ' . esc_html($custom_field_value);
}
Note: Always wrap saved meta values in esc_html() (or esc_attr() for HTML attributes) when echoing them into a template, exactly as shown above — even though this value passed through sanitize_text_field() on save, escaping on output is a separate, equally necessary step. Sanitizing controls what gets stored; escaping controls what’s safe to print in a given context, and skipping either one is the same class of oversight covered in our WordPress security checklist.
Adding Multiple Custom Fields
The following is an optional rendering example, not a complete replacement for the single-field workflow. It replaces the step 2 function and uses different input names and meta keys. Do not install both versions of display_custom_fields_metabox(), and do not expect the step 3 handler to save these new inputs unchanged.
To render several inputs, loop over a defined list:
function display_custom_fields_metabox($post) {
wp_nonce_field( 'custom_fields_nonce_action', 'custom_fields_nonce' );
$fields = array(
'subtitle' => 'Subtitle',
'external_url' => 'External URL',
);
foreach ( $fields as $key => $label ) {
$value = get_post_meta( $post->ID, $key, true );
echo '<p><label for="' . esc_attr( $key ) . '">' . esc_html( $label ) . ':</label><br>';
echo '<input id="' . esc_attr( $key ) . '" name="' . esc_attr( $key ) . '" type="text" value="' . esc_attr( $value ) . '" style="width:100%" /></p>';
}
}
A matching save handler must retain the nonce, autosave, revision, and capability checks from step 3, then read and save each new key separately. Validate that submitted values are strings, unslash them before sanitizing, and select sanitization appropriate to the field: text and URLs require different handling. The example above only renders the inputs; the multiple-field save handler is not included.
Common Mistakes to Avoid
- An input
nameattribute that doesn’t match the$_POSTkey read in the save function — the exact mismatch fixed above, which causes the field to silently never save. - Undefined variables in permission/autosave checks, as covered in the warning above — always double-check these reference the actual
$post_idparameter. - Forgetting to escape output when displaying saved meta values in a template.
- Skipping the nonce check entirely, which leaves the save handler open to a cross-site request forgery (CSRF) style attack — a malicious page could submit a form to your save handler without the visitor’s knowledge if there’s no nonce to verify.
Verify That Your Custom Field Saves and Displays
- Edit a test post, enter a value in the Custom Fields meta box, and save.
- Reload the editor and confirm the value remains in the input.
- Repeat on a page to check both editor screens.
- Open the front end where you added step 4. Saving metadata does not automatically add it to the page layout.
Display limitation: The step 4 example uses empty(), so the string 0 will not be displayed. If zero is a valid value for your field, use an explicit empty-string check when adapting that example.
Using Custom Fields with the REST API
This meta box does not automatically register its field for REST API access. If a JavaScript application needs the value, register the metadata with an appropriate type, schema, and access policy, or expose it through a carefully designed custom WordPress REST API endpoint. Review whether the value is safe to make public; an editor input is not an access-control rule.
Troubleshooting Missing or Empty Custom Fields
- The meta box is missing: confirm that the registration code is loaded and the screen list includes the post type you are editing.
- The value does not save: check the input name, submitted nonce, and edit permission checks before changing the save handler.
- The value saves but does not appear publicly: confirm that the template uses the correct post ID and the stored key
custom_field_name, not the input namecustom_field.
For the core registration and retrieval APIs, see the WordPress custom meta boxes handbook and get_post_meta() reference. If you need a custom content-editor component, continue with our Gutenberg block tutorial.
Conclusion
Adding custom fields with a metabox is a genuinely powerful way to attach and display extra data beyond what the standard post editor supports — the pattern above works identically for posts, pages, and any custom post type you register, like the Movie post type from our custom post type guide. Get the nonce check, the permission check, and the input-name/POST-key matching right, and the rest is just repeating the same pattern for however many fields your project needs.
8 replies on “How to Add Custom Fields to Posts and Pages in WordPress”
Thanx
I appreciate the clarity in this explanation.
[…] building out custom data structures for this kind of work, it’s also worth reviewing how to add custom fields to posts and pages the right […]
[…] All five steps work together: render the fields, sanitize submitted values, calculate the fee, display cart data, and persist order metadata. For fields managed by editors rather than shoppers, see our WordPress custom fields tutorial. […]
[…] it is not a confidentiality boundary for a field deliberately exposed in a public response. See our custom fields tutorial for the storage side of this […]
[…] structured details such as a movie’s release year or director? Follow our WordPress custom fields tutorial for the metadata workflow, then adapt its post type and field identifiers to your Movies […]
[…] you need an editor-managed value attached to a post or page, such as a subtitle, start with our WordPress custom fields and meta boxes tutorial. The guide below focuses on building a block for the content […]
[…] your endpoint needs values stored against posts or pages, our custom fields tutorial explains the editor input, saving, and retrieval workflow. Storing a field does not by itself […]