How to create a custom WordPress dashboard widget

Do you want to create a custom dashboard widget in WordPress?

There’s a really simple WordPress API you can use to create your dashboard widget. It will take you less than a minute to learn how to use it.

In this guide, you’ll learn how to register and render a custom WordPress widget…

How To Create a Custom Dashboard Widget

There’s only one function you need to create your dashboard widget. It’s called wp_add_dashboard_widget. This is what a call to this function looks like:

wp_add_dashboard_widget($widget_id, $widget_name, $callback, $control_callback, $callback_args, $context, $priority);

These are all the arguments it accepts in order:

• $widget_id — The CSS ID that will be applied to the widget when it’s displayed.
• $widget_name — Title of this widget. This will be displayed on the dashboard.
• $callback — Name of the function to call that will render this widget. More on this later…
• $control_callback — Adding this callback creates a ‘configure’ section for the widget. It also adds a configure link on top of the widget that displays this section when clicked.
• $callback_args — This variable will be passed as a second argument to your $callback function.
• $context — This is the “column” where your widget will be displayed. Acceptable values: normal, side, colum3, column4.
• $priority — Set this value to ‘high’ to display it above most other widgets inside its context. Other acceptable values: core, default, and low, ‘core’ is the default.

Only the first three arguments are required when calling this function:

wp_add_dashboard_widget('my-custom-dashboard-widget', 'My Widget Title', 'render_callback_function');

The most important argument of this function is the third argument: $callback. Whatever you return from this function will be displayed as the contents of your widget.

This is what your code will look like when you pass a function name to this argument:

function wpturbo_render_custom_widget($callback_args, $widget){
	return "<strong>This is my custom widget's content!</strong>";
}
wp_add_dashboard_widget('my-custom-dashboard-widget', 'My Widget Title', 'wpturbo_render_custom_widget');

As you can see, if you set the $callback_args argument in wp_add_dasbhoard_widget function, then it will be passed as the first argument to this function when it’s called.

Although the above code is technically correct, it’s not complete.

You can only call the wp_add_dashboard_widget function from the wp_dashboard_setup hook. So, the final code should look like this:

function wpturbo_render_custom_widget($callback_args, $widget){
	return "<strong>This is my custom widget's content!</strong>";
}

add_action( 'wp_dashboard_setup', 'wpturbo_register_custom_dashboard_widget' );
function wpturbo_register_custom_dashboard_widget(){
	wp_add_dashboard_widget('my-custom-dashboard-widget', 'My Widget Title', 'wpturbo_render_custom_widget');
}

You can place this code in your theme’s functions.php file or in a seperate custom plugin.

PRO TIP: Use our completely WordPress Widget Code Generator to generate this code for you. Our generator offers dozens of customization options, and will give you an easy template to start with.

Conclusion

You can easily create a custom dashboard widget in WordPress. All it takes is calling the wp_add_dashboard_widget function. Use our widget code generator to generate a quick, starter template!