How to create a custom WordPress dashboard widget

by
example dashboard widget

Want to create your own dashboard widget that appears when you log in to the WordPress dashboard?

You can do it in a few lines of code, once you have the widget setup, you can then concentrate on writing the functionality for the contents of the widget.

What are dashboard widgets?

Dashboard widgets are shown on the homepage of the WordPress dashboard. They are usually used to display summary information or for quick access to functionality.

They can be from WordPress itself, the plugins you have installed, or even your theme.

image 4
Dashboard widgets shown in a typical WordPress website

It’s easy to add your own custom dashboard widget with code, read on to find out how.

How to create a dashboard widget

To create a dashboard widget, you can use the following code example:

function yourprefix_add_widgets() {

	if ( current_user_can( 'edit_posts' ) ) { // Set this to the capability a user must have to see the widget

		wp_add_dashboard_widget(
			'example-widget', // Give your widget a unique ID
			'Example Widget', // This is the title of the widget, you may want to consider making this a translatable string
			'yourprefix_example_widget' // This is the function which will render the content in the widget, which is below
		);

	}

}
add_action( 'wp_dashboard_setup', 'yourprefix_add_widgets' );

function yourprefix_example_widget() {

	// The content to display in the widget, you could add your own PHP functionality here

	echo 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla varius malesuada dolor vitae imperdiet. Integer congue nunc quis ipsum ultricies tempus. Etiam in sem vitae tellus finibus vulputate. Nullam ultricies ligula commodo, tristique neque id, maximus urna. Aliquam vel accumsan ligula. Sed nec sem elit. Vestibulum quam libero, maximus lacinia aliquam vitae, porta at quam. Nunc quis cursus sem. Donec tincidunt gravida dictum. Curabitur id dictum magna, ut consequat tellus.';

}

Once you have added the code (see how), when you visit the WordPress dashboard homepage, you’ll see the widget on display:

image 5
Example dashboard widget

Pretty neat, right? If you just want to display some text, this is great, but maybe you want some custom PHP functionality in here. To do that, you just need to edit the yourprefix_example_widget function.

Things to consider

When creating dashboard widgets, there are a few points you should consider:

  1. Use wp_add_dashboard_widget inside a current_user_can condition to check the user capability, as you probably only want to display the widget to users with a specific capability
  2. Consider using translatable strings in the text output of the widget if translation is required
  3. Users have the ability to hide dashboard widgets via the screen options tab at the top right of the WordPress dashboard, if a user can’t see your widget, this is probably why
  4. If you’ve just created a dashboard widget, it will immediately be visible for current users, if they want to hide it, they’ll need to do so via their screen options
  5. Change the yourprefix in my example code to your own unique function prefix, this helps reduce the risk of function name clashes

Leave a comment