Have you tried adding a custom metabox to an ACF Options Page in WordPress, but it never appears?
This can be confusing if you have previously added metaboxes to posts or custom post types. The usual add_meta_box() function works differently here because an ACF Options Page is not a standard post-editing screen.
The important thing is to use the correct screen identifier when registering the metabox and check the options page’s menu slug to make sure it appears only on the intended page.
In this tutorial, I’ll show you how to create an ACF Options Page and add a custom metabox to it using PHP, without an additional metabox plugin.
What You Need Before Starting
Before adding the code, make sure you have:
- WordPress installed and working.
- ACF PRO installed and activated. The options-page functionality used in this tutorial is part of ACF PRO.
- Access to your child theme’s
functions.phpfile or a custom plugin file. - Basic knowledge of PHP and WordPress hooks.
If you want to keep your custom functionality separate from your theme, you can also follow our guide on creating a custom plugin in WordPress.
Why Is the Metabox Not Appearing on an ACF Options Page?
When adding a metabox to a post or page, you might use code similar to this:
add_meta_box(
'my-metabox',
'Metabox Title',
'my_metabox_callback',
'post'
);
Here, post is the screen identifier for the standard WordPress post-editing screen.
However, an ACF Options Page uses its own metabox screen identifier. Passing the options page’s menu slug directly to add_meta_box() will not register the metabox on the correct screen.
There are two different identifiers to understand:
- Menu slug: Identifies the specific ACF Options Page in the admin URL, such as
my-acf-options-page. - Metabox screen identifier: ACF uses
acf_options_pagewhen registering metaboxes for its options-page interface.
For example, your options page URL may look like this:
https://example.com/wp-admin/admin.php?page=my-acf-options-page
In this example, my-acf-options-page is the menu slug, while acf_options_page is the screen identifier passed to add_meta_box().
Step 1: Create an ACF Options Page
First, register an options page using ACF’s acf_add_options_page() function.
Add the following code to your child theme’s functions.php file:
add_action('acf/init', function () {
if (function_exists('acf_add_options_page')) {
acf_add_options_page(array(
'page_title' => 'My Options Page',
'menu_title' => 'My Options Page',
'menu_slug' => 'my-acf-options-page',
'capability' => 'manage_options',
'redirect' => false,
));
}
});
This code creates a new options page in the WordPress admin menu.
We use the acf/init action to register the page after ACF has initialized. The menu_slug value uniquely identifies this options page.
The manage_options capability restricts access to users who have permission to manage site options. You can change it if your website requires a different access level.
Step 2: Add a Metabox to the ACF Options Page
Now that the options page is registered, you can add a custom metabox to it.
Use the following code:
add_action('admin_init', function () {
// Check whether the page parameter exists.
if (!isset($_GET['page'])) {
return;
}
// Get the current options page slug.
$page = sanitize_key(wp_unslash($_GET['page']));
// Run only on our ACF options page.
if ($page !== 'my-acf-options-page') {
return;
}
// Register the metabox.
add_meta_box(
'my-options-page-metabox',
'My Custom Metabox',
'my_options_page_metabox_callback',
'acf_options_page',
'normal',
'high'
);
});
Pay attention to this part:
if ($page !== 'my-acf-options-page') {
return;
}
This checks the menu slug from the current admin URL. The metabox will only be registered when the visitor opens our specific ACF Options Page.
Now look at the fourth argument of add_meta_box():
'acf_options_page'
This is the screen identifier used by ACF’s options-page metabox interface. It is not the same as the menu slug.
The remaining arguments specify the metabox ID, title, callback function, display context, and priority.
Step 3: Create the Metabox Callback Function
The callback function controls what appears inside your custom metabox.
Add the following function to your PHP file:
function my_options_page_metabox_callback() {
echo '<p>Simple metabox content here.</p>';
}
That’s all you need for a basic metabox.
When you open your ACF Options Page, you should now see a metabox titled My Custom Metabox containing the text you added in the callback function.
Complete Working Code
If you prefer to copy everything at once, here is the complete example. It creates the ACF Options Page, checks its menu slug, registers the metabox, and displays its content.
// Register the ACF Options Page.
add_action('acf/init', function () {
if (function_exists('acf_add_options_page')) {
acf_add_options_page(array(
'page_title' => 'My Options Page',
'menu_title' => 'My Options Page',
'menu_slug' => 'my-acf-options-page',
'capability' => 'manage_options',
'redirect' => false,
));
}
});
// Add a metabox to the ACF Options Page.
add_action('admin_init', function () {
if (!isset($_GET['page'])) {
return;
}
$page = sanitize_key(wp_unslash($_GET['page']));
if ($page !== 'my-acf-options-page') {
return;
}
add_meta_box(
'my-options-page-metabox',
'My Custom Metabox',
'my_options_page_metabox_callback',
'acf_options_page',
'normal',
'high'
);
});
// Metabox callback.
function my_options_page_metabox_callback() {
echo '<p>Simple metabox content here.</p>';
}
Add this code to your child theme’s functions.php file or a custom plugin file. Make sure you do not register the same options page more than once.
How to Check Whether the Metabox Is Working
After adding the code, follow these steps:
- Log in to your WordPress dashboard.
- Open the My Options Page menu.
- Check whether the My Custom Metabox box appears.
- Confirm that the callback content is displayed inside the metabox.
If you do not see the metabox, check that the URL contains the correct page parameter and that the value matches the menu_slug used when registering the options page.
What If You Want to Display Custom Fields Inside the Metabox?
You can replace the simple paragraph in the callback function with your own HTML, form controls, or custom output.
For example:
function my_options_page_metabox_callback() {
?>
<div>
<h3>Additional Settings</h3>
<p>Manage your custom options here.</p>
<label for="custom_message">Custom Message</label>
<input
type="text"
id="custom_message"
name="custom_message"
value=""
>
</div>
<?php
}
Important: This example only displays an input field. It does not automatically save its value. If you want to save custom data, you must implement a proper submission and saving process with nonce verification, capability checks, and input sanitization.
If you only need to display and manage ACF fields, it may be simpler to create an ACF field group and assign it to the options page using ACF’s Options Page location rule.
You can also explore our related tutorial on customizing ACF repeater fields for more examples of working with custom field data.
Common Mistakes When Adding a Metabox to an ACF Options Page
Here are some common reasons why a metabox may not appear:
- Using the wrong screen identifier: Use
acf_options_pageas the screen argument inadd_meta_box(). - Checking the wrong page slug: The value in the URL’s
pageparameter must match the registeredmenu_slug. - Not registering the options page: Make sure
acf_add_options_page()runs successfully. - ACF PRO is not active: The options-page feature used in this example requires ACF PRO.
- Registering the metabox on the wrong screen: Do not use the options page menu slug as the fourth argument of
add_meta_box(). - Duplicate registration: Avoid registering the same options page or metabox multiple times.
Frequently Asked Questions
Why is my metabox not showing on an ACF Options Page?
A common reason is using the wrong screen identifier. For an ACF Options Page metabox, use acf_options_page as the screen argument in add_meta_box(). Also check that your current page slug matches the registered options page.
What screen ID should I use for an ACF Options Page metabox?
Use acf_options_page as the screen argument when registering the metabox with add_meta_box(). The menu slug, such as my-acf-options-page, is used separately to identify the specific options page.
Do I need ACF PRO to create an options page?
Yes. The options-page functionality used in this tutorial is included with ACF PRO. The free version of ACF does not include the same built-in options-page feature.
Can I add multiple metaboxes to an ACF Options Page?
Yes. You can call add_meta_box() multiple times with different metabox IDs and callback functions. Use acf_options_page as the screen argument for each one.
Can I add a metabox to only one specific ACF Options Page?
Yes. Check the page parameter in the admin URL and compare it with the options page’s registered menu slug. This ensures that the metabox is registered only for the intended options page.
Where should I add the PHP code?
You can add the code to your child theme’s functions.php file or a custom plugin file. A custom plugin is a good choice if you want the functionality to remain independent of your active theme.
Final Thoughts
Adding a metabox to an ACF Options Page requires using the correct screen identifier and checking the correct menu slug.
Remember these two important values:
my-acf-options-pageidentifies your specific options page through its menu slug.acf_options_pageis the screen argument used when registering the metabox.
Once you use both correctly, you can add custom metaboxes to your ACF Options Page and display your own content without installing another metabox plugin.
