How to Add Custom Dashboard Widgets in WordPress
Posted on 20th June 2023
The process of adding custom dashboard widgets in WordPress is relatively simple. Dashboard widgets are essentially pieces of code that display content in the admin area of WordPress. These can be anything from a simple text widget to a complex graph or chart.
In order to add a custom dashboard widget, you first need to create a WordPress plugin. Don’t worry, this is easier than it sounds. A WordPress plugin is simply a piece of code that extends the functionality of WordPress.
Once you’ve created your plugin, you can then add your custom dashboard widget to it. Here’s how:
1. Create a new file in your plugin directory called “dashboard-widgets.php”.
2. Add the following code to this file:
<?php
/*
Plugin Name: Custom Dashboard Widgets
Plugin URI: https://example.com/
Description: This plugin adds custom dashboard widgets.
Version: 1.0
Author: John Doe
Author URI: https://example.com/
*/
// Exit if accessed directly
if ( ! defined( 'ABSPATH' ) ) exit;
// Load Dashboard Widgets
require_once( plugin_dir_path( __FILE__ ) . 'includes/dashboard-widgets.php' );
This code defines a new plugin called "Custom Dashboard Widgets". It includes a file called "dashboard-widgets.php" which we will create in the next step.
3. Create a new file in your plugin directory called "includes/dashboard-widgets.php".
4. Add the following code to this file:
<?php
/*
Add Custom Dashboard Widgets
*/
function custom_dashboard_widgets() {
global $wp_meta_boxes;
// Add a new dashboard widget
wp_add_dashboard_widget(
'custom_dashboard_widget', // Widget slug
'Custom Dashboard Widget', // Title
'custom_dashboard_widget_content' // Callback function
);
}
add_action( 'wp_dashboard_setup', 'custom_dashboard_widgets' );
This code defines a new function called "custom_dashboard_widgets()" which adds a new dashboard widget. The "custom_dashboard_widget_content" function is a callback function that defines the content of the widget. We will create this function in the next step.
5. Add the following code to the "dashboard-widgets.php" file:
function custom_dashboard_widget_content() {
// Content goes here
}
This function defines the content of the custom dashboard widget. You can add any content you like here, such as text, HTML, or even PHP code.
Now that you've added the code to create your custom dashboard widget, all you need to do is activate your plugin. Once it's activated, your widget will appear on the WordPress admin dashboard.
Assuming you have a custom plugin or a custom theme for your WordPress site, you can add custom dashboard widgets in two ways: directly through code or using the Dashboard Widgets API.
Code
The first method is to simply add your widget code in the functions.php file of your custom theme or plugin. Here is an example of how you would do that:
function my_custom_dashboard_widgets() {
global $wp_meta_boxes;
wp_add_dashboard_widget('custom_help_widget', 'Theme Support', 'custom_dashboard_help');
}
add_action('wp_dashboard_setup', 'my_custom_dashboard_widgets');
function custom_dashboard_help() {
echo '
Welcome to Custom Theme! Need help? Contact the developer here.
‘;
}
This code simply adds a new dashboard widget with the title “Theme Support” and the content “Welcome to Custom Theme! Need help? Contact the developer here.”
If you want to add more than one custom dashboard widget, you can use the same code as above, but with a different callback function for each widget.
Dashboard Widgets API
The second method for adding custom dashboard widgets is to use the Dashboard Widgets API. This method is a little bit more complex, but it gives you more control over your widgets.
To use the Dashboard Widgets API, you need to first create a function that will register your widget. This function should hook into the ‘wp_dashboard_setup’ action:
function my_custom_dashboard_widgets() {
global $wp_meta_boxes;
wp_add_dashboard_widget(‘custom_help_widget’, ‘Theme Support’, ‘custom_dashboard_help’);
}
add_action(‘wp_dashboard_setup’, ‘my_custom_dashboard_widgets’);
This function simply registers a new widget with the title “Theme Support” and the content “Welcome to Custom Theme! Need help? Contact the developer here.”
If you want to add more than one custom dashboard widget, you can use the same code as above, but with a different callback function for each widget.
You can also use the ‘wp_dashboard_setup’ action to remove any default dashboard widgets that you don’t want to display. To do that, you need to use the unset() function:
function my_custom_dashboard_widgets() {
global $wp_meta_boxes;
unset($wp_meta_boxes[‘dashboard’][‘normal’][‘core’][‘dashboard_right_now’]);
unset($wp_meta_boxes[‘dashboard’][‘side’][‘core’][‘dashboard_quick_press’]);
unset($wp_meta_boxes[‘dashboard’][‘normal’][‘core’][‘dashboard_recent_drafts’]);
unset($wp_meta_boxes[‘dashboard’][‘normal’][‘core’][‘dashboard_recent_comments’]);
unset($wp_meta_boxes[‘dashboard’][‘side’][‘core’][‘dashboard_primary’]);
unset($wp_meta_boxes[‘dashboard’][‘side’][‘core’][‘dashboard_secondary’]);
wp_add_dashboard_widget(‘custom_help_widget’, ‘Theme Support’, ‘custom_dashboard_help’);
}
add_action(‘wp_dashboard_setup’, ‘my_custom_dashboard_widgets’);
This code will remove the default dashboard widgets and replace them with your custom widget.
You can also use the Dashboard Widgets API to add your widget to a different location on the dashboard. To do that, you need to use the ‘wp_dashboard_setup’ action and the ‘wp_dashboard_meta_boxes’ filter:
function my_custom_dashboard_widgets() {
global $wp_meta_boxes;
add_meta_box( ‘custom_help_widget’, ‘Theme Support’, ‘custom_dashboard_help’, ‘dashboard’, ‘side’, ‘high’ );
}
add_action(‘wp_dashboard_setup’, ‘my_custom_dashboard_widgets’);
function my_custom_dashboard_meta_boxes() {
global $wp_meta_boxes;
$wp_meta_boxes[‘dashboard’][‘normal’][‘core’][‘custom_help_widget’] = $wp_meta_boxes[‘dashboard’][‘side’][‘core’][‘custom_help_widget’];
unset($wp_meta_boxes[‘dashboard’][‘side’][‘core’][‘custom_help_widget’]);
}
add_filter(‘wp_dashboard_meta_boxes’, ‘my_custom_dashboard_meta_boxes’);
This code will add your custom widget to the “Normal” section of the dashboard (the middle column).
You can also use the Dashboard Widgets API to change the order of the dashboard widgets. To do that, you need to use the ‘wp_dashboard_setup’ action and the ‘get_user_option_meta-boxes-dashboard_dashboard_columns’ filter:
function my_custom_dashboard_widgets() {
global $wp_meta_boxes;
add_meta_box( ‘custom_help_widget’, ‘Theme Support’, ‘custom_dashboard_help’, ‘dashboard’, ‘side’, ‘high’ );
}
add_action(‘wp_dashboard_setup’, ‘my_custom_dashboard_widgets’);
function my_custom_dashboard_columns() {
return array(
‘normal’ => 2,
‘side’ => 1
);
}
add_filter(‘get_user_option_meta-boxes-dashboard_dashboard_columns’, ‘my_custom_dashboard_columns’);
This code will change the order of the dashboard widgets so that your custom widget is displayed before the default widgets.
You can also use the Dashboard Widgets API to hide a dashboard widget from certain users. To do that, you need to use the ‘wp_dashboard_setup’ action and the ‘wp_dashboard_meta_boxes’ filter:
function my_custom_dashboard_widgets() {
global $wp_meta_boxes;
add_meta_box( ‘custom_help_widget’, ‘Theme Support’, ‘custom_dashboard_help’, ‘dashboard’, ‘side’, ‘high’ );
}
add_action(‘wp_dashboard_setup’, ‘my_custom_dashboard_widgets’);
function my_custom_dashboard_meta_boxes() {
global $wp_meta_boxes;
$wp_meta_boxes[‘dashboard’][‘normal’][‘core’][‘custom_help_widget’] = $wp_meta_boxes[‘dashboard’][‘side’][‘core’][‘custom_help_widget’];
unset($wp_meta_boxes[‘dashboard’][‘side’][‘core’][‘custom_help_widget’]);
}
add_filter(‘wp_dashboard_meta_boxes’, ‘my_custom_dashboard_meta_boxes’);
function my_custom_dashboard_capabilities() {
return array(
‘read’ => ‘do_not_allow’,
‘edit_dashboard’ => ‘do_not_allow’
);
}
add_filter(‘map_meta_cap’, ‘my_custom_dashboard_capabilities’, 10, 4);
This code will hide your custom widget from users who don’t have the ‘edit_dashboard’ capability.
As you can see, the Dashboard Widgets API gives you a lot of flexibility when it comes to customizing your dashboard. With a little bit of code, you can add, remove, or change the order of the dashboard widgets.
