Introduction

The WordPress dashboard is the first screen administrators see after logging into the WordPress admin panel. It provides an overview of the website and displays useful information such as recent activity, quick drafts, and WordPress news.

In many cases, developers may want to add custom functionality to the dashboard. For example, you might want to display site statistics, custom reminders, quick links, or plugin information.

WordPress allows developers to add custom dashboard widgets that appear alongside the default widgets. These widgets can display custom content or useful information for administrators.

In this tutorial, you will learn how to create a custom WordPress dashboard widget using simple PHP code.

What is a Dashboard Widget?

A dashboard widget is a small panel displayed on the WordPress admin dashboard. It provides information or tools that help administrators manage the website.

WordPress includes several built-in dashboard widgets, such as:

• At a Glance
• Activity
• Quick Draft
• WordPress Events and News

Developers can create custom widgets to display additional information or functionality.

For example, a custom widget might display:

• Website statistics
• Plugin status information
• Custom admin notices
• Quick links for administrators

Custom dashboard widgets are especially useful when developing websites for clients or teams, as they can provide important information directly in the admin panel.

WordPress Function for Dashboard Widgets

WordPress provides a built-in function for adding dashboard widgets:

wp_add_dashboard_widget()

This function registers a new widget and displays it on the WordPress dashboard.

Syntax

wp_add_dashboard_widget(
    $widget_id,
    $widget_name,
    $callback_function
);

Parameters

Step 1: Create a Simple Plugin

Always add custom admin features via a plugin (not theme functions).

Create a new file:

/wp-content/plugins/divphp-dashboard-widget/divphp-dashboard-widget.php

Add this code:

<?php
/**
 * Plugin Name: DivPHP Custom Dashboard Widget
 * Description: Adds a custom dashboard widget to WordPress admin.
 * Version: 1.0
 * Author: DivPHP Tutorials
 */if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

Activate the plugin from:
WordPress Admin → Plugins

Step 2: Register the Dashboard Widget

Now hook into wp_dashboard_setup:

function create_custom_dashboard_widget() {

    wp_add_dashboard_widget(
        'custom_dashboard_widget',
        'My Custom Dashboard Widget',
        'custom_dashboard_widget_content'
    );

}

add_action('wp_dashboard_setup', 'create_custom_dashboard_widget');

Explanation

• custom_dashboard_widget is the internal widget ID.
• My Custom Dashboard Widget is the title shown on the dashboard.
• custom_dashboard_widget_content is the function that will display the widget content.

This code tells WordPress to add a new widget when the dashboard is loaded.

Step 3: Add Widget Content

Create the callback function:

function divphp_dashboard_widget_output() {
    echo '<h3>Welcome to DivPHP Tutorials</h3>';
    echo '<p>This is your custom WordPress dashboard widget.</p>';
    echo '<ul>
            <li><a href="https://yourwebsite.com">Visit Website</a></li>
            <li><a href="https://yourwebsite.com/tutorials">Latest Tutorials</a></li>
          </ul>';
}

Now refresh your WordPress dashboard.
You should see your widget 🎉

Step 4: Restrict Widget by User Role (Optional)

Only show widget to administrators:

function divphp_register_dashboard_widget() {    
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }    wp_add_dashboard_widget(
        'divphp_dashboard_widget',
        'DivPHP Dashboard Widget',
        'divphp_dashboard_widget_output'
    );
}

Step 5: Add Styling to the Widget

add_action( 'admin_enqueue_scripts', 'divphp_dashboard_widget_styles' );
function divphp_dashboard_widget_styles() {
    echo '<style>
        #divphp_dashboard_widget h3 {
            margin-bottom: 8px;
        }
        #divphp_dashboard_widget ul li {
            margin-left: 16px;
            list-style: disc;
        }
    </style>';
}

Step 6: Real-World Example (Show Post Count)

function divphp_dashboard_widget_output() {    
    $post_count = wp_count_posts()->publish;
    $page_count = wp_count_posts( 'page' )->publish;    
    echo '<p><strong>Published Posts:</strong> ' . esc_html( $post_count ) . '</p>';
    echo '<p><strong>Published Pages:</strong> ' . esc_html( $page_count ) . '</p>';
}

Example: Display Website Statistics

Custom widgets often display useful website information. For example, you might want to show the total number of published posts.

Example:

function custom_dashboard_widget_content() {    
    $post_count = wp_count_posts()->publish;
    echo "<p>Total Published Posts: " . $post_count . "</p>";
}

This code retrieves the number of published posts and displays it in the dashboard widget.

Display Total Users in Dashboard Widget

You can also display the total number of registered users.

Example:

function custom_dashboard_widget_content() {    
     $users = count_users();    
     echo "<p>Total Users: " . $users['total_users'] . "</p>";
}

This example uses the count_users() function to retrieve user statistics.

When Should You Use Dashboard Widgets?

Custom dashboard widgets are useful in many situations.

Common use cases include:

• Displaying site statistics
• Showing custom admin notices
• Providing quick navigation links
• Displaying plugin data
• Showing reminders for website administrators

For example, a developer building a website for a client might add a widget that shows:

• Important maintenance notices
• Links to documentation
• Website usage statistics

This makes the WordPress dashboard more useful for administrators.

Best Practices for Dashboard Widgets

When creating custom dashboard widgets, follow these best practices:

• Keep widgets simple and useful
• Avoid displaying too much information
• Use clear and descriptive widget titles
• Only display relevant information for administrators

The dashboard should remain clean and easy to use.

Common Beginner Mistakes

Beginners sometimes make the following mistakes when creating dashboard widgets:

• Using the wrong action hook
• Forgetting to create the callback function
• Adding too much content inside the widget
• Placing the code in the wrong file

Always test your widget after adding the code.

Practical Tasks

Try the following tasks to practice creating dashboard widgets.

Task 1

Create a custom dashboard widget called Site Overview.

Practical Tasks

Try the following tasks to practice creating dashboard widgets.

Task 1

Create a custom dashboard widget called Site Overview.

Task 2

Display the total number of published posts in the widget.

Task 3

Display the total number of registered users using the count_users() function.

Task 4

Add a custom welcome message for administrators inside the widget.

Example:

Welcome to the Admin Dashboard.

Final Thoughts

Custom dashboard widgets allow developers to extend the WordPress admin interface and provide useful information directly inside the dashboard.

By creating custom widgets, developers can display statistics, reminders, and helpful tools for administrators. This improves the usability of the WordPress admin panel and makes website management easier.

Understanding how to create dashboard widgets is an important step in advanced WordPress development, especially when building custom solutions for clients or complex websites.