wp_add_dashboard_widget()
Adds (register) a new widget (a meta box) to the administration dashboard (the main page of the admin panel).
The function should be called during the following actions:
- wp_dashboard_setup - to add a widget to the dashboard of the site.
- wp_network_dashboard_setup (multisite) - to add a widget to the dashboard of multisite network.
- wp_user_dashboard_widgets (multisite) - to add a widget to the dashboard of the user. See is_user_admin().
It means that WordPress uses following events to run widgets created (registered) by this function:
do_action( 'wp_dashboard_setup' ); // консоль do_action( 'wp_network_dashboard_setup' ); // консоль сети сайтов do_action( 'wp_user_dashboard_widgets' ); // консоль юзера
See also: how to remove a widget from the dashboard.
No Hooks.
Return
null
. Nothing (null).
Usage
wp_add_dashboard_widget( $widget_id, $widget_name, $callback, $control_callback, $callback_args );
- $widget_id(string) (required)
- Widget ID. Will be used in the CSS class of the widget HTML block. Will be the key of the widget in the widgets array.
- $widget_name(string) (required)
- Title of the widget. Will be on the top of the widget, e.g. "Latest comments".
- $callback(callable) (required)
- Function that fills the widget with the desired content. The function should echo its output.
- $control_callback(callable)
- Function that saves widget data: function that handle the submission of widget form (widget options), and also display the widget HTML form.
Default: null - $callback_args(array)
- Data that will be passed to the $callback function. So $callback function receive $post object and the data specified in this parameter.
Default: null
Examples
#1 Add a widget to the dashboard
// Register a widget on action add_action( 'wp_dashboard_setup', 'add_dashboard_widgets' ); // A callback for registering a widget function add_dashboard_widgets() { wp_add_dashboard_widget( 'my_dashboard_widget', 'Metabox for the dashbord', 'my_dashboard_widget_function' ); } // Widget's content function my_dashboard_widget_function( $post, $callback_args ) { echo 'Hello World! This is my first widget!'; }
#2 Add a widget to the multisite dashboard
// Add a widget usining an anoynymous function add_action( 'wp_network_dashboard_setup', function() { wp_add_dashboard_widget( 'my_dashboard_widget', 'A meta box in the dashboard of the multisite', 'my_dashboard_widget_function' ); } ); function my_dashboard_widget_function( $post, $callback_args ) { echo 'Hello! This is a widget on the dashboard of the multisite network!'; }
#3 Changing the widget location
This function does not allow you to specify the location of the widget and, by default, the position of the widget will be at the end of the first (left) column. Because of this function works based on add_meta_box() function, we can use it instead, it allows to specify the location of the widget (in which column it should be shown). Technically, all widgets are added to the global $wp_meta_boxes array, changing the location of the widgets in it, you can change their real location. However, we need to remember that the location of the widgets saves to WP user options when we drag them, and this, in turn, can affect the final location of the $wp_meta_boxes array elements.
Let's place the widget in the right column by specifying the fourth $post_type parameter for the add_meta_box() function.
add_meta_box( 'id', 'Dashboard Widget Title', 'dash_widget', 'dashboard', 'side', 'high' );
For multisite network the fourth parameter should be dashboard-network
:
add_meta_box( 'id', 'Network Dashboard Widget Title', 'widget_output_func', 'dashboard-network', 'normal', 'high' );
#4 Using $control_callback parameter
With $control_callback parameter we can add a configuration section to the widget. The code below will register this widget:

Which has this configuration:

#5 A widget for notes in the dashboard
The example below shows how to create a dashboard widget for notes. It saves the note content to WP options using AJAX.
This widget can be useful when you need to quickly write something to remember when you're in the dashboard.
<?php /** * Plugin Name: Ajax WordPress Lessons * Description: Displays a widget with notes on the dashboard. * Plugin URI: https://github.com/campusboy87/lessons-ajax-wordpress * Author: Educational YouTube channel "WP-PLUS" * Author URI: https://www.youtube.com/c/wpplus */ // Registers "My notes" widget add_action( 'wp_dashboard_setup', 'my_notes_dashboard_widget' ); function my_notes_dashboard_widget() { // Registers a widget only for administrators if ( current_user_can( 'activate_plugins' ) ) { wp_add_dashboard_widget( 'my_notes', 'My notes', 'my_notes_form' ); } } // Displays the content of the widget function my_notes_form() { ?> <form> <textarea><?php echo esc_textarea( get_option( 'my_notes_content' ) ); ?></textarea> <button type="reset" class="clear button button-secondary">Clear</button> <?php submit_button( null, 'primary', null, false ); ?> </form> <?php } // Saves the note content using AJAX add_action( 'wp_ajax_my_notes', 'my_notes_ajax_save' ); function my_notes_ajax_save() { check_ajax_referer( 'my_notes_nonce', 'security' ); if ( ! isset( $_POST['my_notes_content'] ) || ! current_user_can( 'activate_plugins' ) ) { return; } // Get and sanitize the data $notes_content = sanitize_textarea_field( wp_unslash( $_POST['my_notes_content'] ) ); // Saves the data to the option of the widget $status = update_option( 'my_notes_content', $notes_content, false ); if ( $status ) { wp_send_json_success( [ 'message' => 'The note is saved', ] ); } else { wp_send_json_error( [ 'message' => 'The note is not saved', ] ); } } // Custom styles, and JS for saving the note content using AJAX. add_action( 'admin_print_scripts', 'my_notes_scripts', 999 ); function my_notes_scripts(){ // Exit from the function if the current page is not the main page of the dashboard (where the widgets are located) if ( 'dashboard' != get_current_screen()->base ) { return; } ?> <style> #my_notes textarea { width: 100%; min-height: 100px; margin-bottom: 5px; } </style> <script> jQuery(document).ready(function ($) { var $boxNotes = $('#my_notes'); var boxTitle = $('h2 span', $boxNotes).text(); // Clean the note content $('.clear', $boxNotes).click(function () { $('textarea', $boxNotes).text(''); $('h2 span', $boxNotes) .text('The field is cleared. Don`t forget to save the result!') .css('color', 'orangered'); }); // Send a form using AJAX $('form', $boxNotes).submit(function (e) { e.preventDefault(); // Animation $boxNotes.animate({opacity: 0.5}, 300); // AJAX var request = $.post( ajaxurl, { action: 'my_notes', my_notes_content: $('textarea', $boxNotes).val(), security: '<?php echo wp_create_nonce( "my_notes_nonce" ); ?>' } ); // Success request.done(function (response) { var $title = $('h2 span', $boxNotes).text(response.data.message); if (response.success) { $title.css('color', 'green'); } else { $title.css('color', 'orangered'); } }); // Fail request.fail(function () { $('h2 span', $boxNotes) .text('ERROR: unknown error!') .css('color', 'red'); }); // Else request.always(function () { $boxNotes.animate( {opacity: 1}, 300, '', function () { setTimeout(function () { $('h2 span', $boxNotes) .text(boxTitle) .attr('style', ''); }, 2000); }); }); }); }); </script> <?php }
And we will get the following widget:

Notes
- Global. callable[]. $wp_dashboard_control_callbacks
Changelog
Since 2.7.0 | Introduced. |
Since 5.6.0 | The $context and $priority parameters were added. |