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 ↗

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