add_meta_box( string $id, string $title, callable $callback, string|array|WP_Screen $screen = null, string $context = 'advanced', string $priority = 'default', array $callback_args = null )

Compatibility

Present in every tracked release (6.7.7 to 7.1.0), and compiles on PHP 7.4 through 8.6-dev.

Parameters

$idstring

Meta box ID (used in the 'id' attribute for the meta box).

$titlestring

Title of the meta box.

$callbackcallable

Function that fills the box with the desired content.
The function should echo its output.

$screenstring|array|WP_Screenoptional

The screen or screens on which to show the box (such as a post type, 'link', or 'comment'). Accepts a single screen ID, WP_Screen object, or array of screen IDs. Default is the current screen. If you have used add_menu_page() or add_submenu_page() to create a new screen (and hence screen_id), make sure your menu slug conforms to the limits of sanitize_key() otherwise the 'screen' menu may not correctly render on your page.Default: null

$contextstringoptional

The context within the screen where the box should display. Available contexts vary from screen to screen. Post edit screen contexts include 'normal', 'side', and 'advanced'. Comments screen contexts include 'normal' and 'side'. Menus meta boxes (accordion sections) all use the 'side' context. Global default is 'advanced'.Default: 'advanced'

$prioritystringoptional

The priority within the context where the box should show.
Accepts 'high', 'core', 'default', or 'low'. Default 'default'.Default: 'default'

$callback_argsarrayoptional

Data that should be set as the $args property of the box array (which is the second parameter passed to your callback). Default null.Default: null

Performance profile

How much work a call to add_meta_box() does, and what it touches: the algorithmic scaling, the Zend instruction count per call across PHP versions, the hooks it hands control to, and the core code that calls it. Measured from the compiled opcodes, not a stopwatch, so every number is identical on any machine running the same PHP version, and every function in core is ranked by cost.

Cost class

Light

Touches nothing outside its own arguments.

Scaling

Scales with input

The body loops, so the work grows with what you pass in.

Instructions

17–76

Executed per call on PHP 8.5, depending on the branch taken. The body compiles to 156.

Plugin surface

None

Nothing here hands control to plugin code.

Called by

7

7 places in core call this, so the cost is paid more often than your own code shows.

What one call costs · 6 distinct outcomes

One number would be a lie: the work depends on which branch runs. These are every distinct cost add_meta_box() can have, taken from its control-flow graph on PHP 8.5.

Uses · 3

• get_current_screen()Get the current screen object
• convert_to_screen()Converts a screen string to a screen object.
• add_meta_box()Adds a meta box to one or more screens.

Used by · 7

• add_meta_box()Adds a meta box to one or more screens.
• do_meta_boxes()Meta-Box template function.
• register_and_do_post_meta_boxes()Registers the default post meta boxes, and runs the `do_meta_boxes` actions.
• wp_add_dashboard_widget()Adds a new dashboard widget.
• wp_nav_menu_post_type_meta_boxes()Creates meta boxes for any post type menu item.
• wp_nav_menu_setup()Register nav menu meta boxes and advanced menu items.
• wp_nav_menu_taxonomy_meta_boxes()Creates meta boxes for any taxonomy menu item.

Source code

View on Trac ↗View on GitHub ↗

1075function add_meta_box( $id, $title, $callback, $screen = null, $context = 'advanced', $priority = 'default', $callback_args = null ) {1076	global $wp_meta_boxes;1077 1078	if ( empty( $screen ) ) {1079		$screen = get_current_screen();1080	} elseif ( is_string( $screen ) ) {1081		$screen = convert_to_screen( $screen );1082	} elseif ( is_array( $screen ) ) {1083		foreach ( $screen as $single_screen ) {1084			add_meta_box( $id, $title, $callback, $single_screen, $context, $priority, $callback_args );1085		}1086	}1087 1088	if ( ! isset( $screen->id ) ) {1089		return;1090	}1091 1092	$page = $screen->id;1093 1094	if ( ! isset( $wp_meta_boxes ) ) {1095		$wp_meta_boxes = array();1096	}1097	if ( ! isset( $wp_meta_boxes[ $page ] ) ) {1098		$wp_meta_boxes[ $page ] = array();1099	}1100	if ( ! isset( $wp_meta_boxes[ $page ][ $context ] ) ) {1101		$wp_meta_boxes[ $page ][ $context ] = array();1102	}1103 1104	foreach ( array_keys( $wp_meta_boxes[ $page ] ) as $a_context ) {1105		foreach ( array( 'high', 'core', 'default', 'low' ) as $a_priority ) {1106			if ( ! isset( $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ] ) ) {1107				continue;1108			}1109 1110			// If a core box was previously removed, don't add.1111			if ( ( 'core' === $priority || 'sorted' === $priority )1112				&& false === $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ]1113			) {1114				return;1115			}1116 1117			// If a core box was previously added by a plugin, don't add.1118			if ( 'core' === $priority ) {1119				/*1120				 * If the box was added with default priority, give it core priority1121				 * to maintain sort order.1122				 */1123				if ( 'default' === $a_priority ) {1124					$wp_meta_boxes[ $page ][ $a_context ]['core'][ $id ] = $wp_meta_boxes[ $page ][ $a_context ]['default'][ $id ];1125					unset( $wp_meta_boxes[ $page ][ $a_context ]['default'][ $id ] );1126				}1127				return;1128			}1129 1130			// If no priority given and ID already present, use existing priority.1131			if ( empty( $priority ) ) {1132				$priority = $a_priority;1133				/*1134				 * Else, if we're adding to the sorted priority, we don't know the title1135				 * or callback. Grab them from the previously added context/priority.1136				 */1137			} elseif ( 'sorted' === $priority ) {1138				$title         = $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ]['title'];1139				$callback      = $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ]['callback'];1140				$callback_args = $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ]['args'];1141			}1142 1143			// An ID can be in only one priority and one context.1144			if ( $priority !== $a_priority || $context !== $a_context ) {1145				unset( $wp_meta_boxes[ $page ][ $a_context ][ $a_priority ][ $id ] );1146			}1147		}1148	}1149 1150	if ( empty( $priority ) ) {1151		$priority = 'low';1152	}1153 1154	if ( ! isset( $wp_meta_boxes[ $page ][ $context ][ $priority ] ) ) {

Changelog

Introduced in 2.5.0. Unchanged from 6.7.7 through 7.1.0.

1. 6.7.7
2. 6.8.8
3. 6.9.7
4. 7.0.4
5. 7.1.0

Signature, return type and hooks compared across 5 parsed releases.

About this page

Parsed data

Generated from the wordpress-develop 6.9.7 tag, from src/wp-admin/includes/template.php, and regenerated for each WordPress release so it tracks the code rather than a snapshot of it.

Corrections

Something wrong on this page? Report it and it gets fixed in the next regeneration.