WordPress Tips & Tricks

Add a Custom Dashboard Widget in WordPress

Every time you log in to WordPress, you land on the dashboard. It shows news, quick drafts, site health, and activity, but it rarely shows the information you actually need first. A custom dashboard widget puts that information right where everyone sees it.

You do not need a plugin to add a custom dashboard widget in WordPress. A short PHP function, hooked into the right place, creates a widget box that looks like every other box on the dashboard. This guide shows how to build one, remove default widgets, show it only to certain roles, and style it.

Why Should You Add a Custom Dashboard Widget?

The WordPress dashboard is the first screen every logged in user sees, so it is the best place for short and useful information. A custom widget can hold support contact details, links to important pages, publishing rules, or a reminder about how to ask for help.

A custom widget also makes a client site feel finished and professional. Instead of a dashboard full of WordPress news and plugin notices, your client sees a friendly welcome box with your name, your support link, and the next steps for their site. That small touch reduces support questions.

For your own sites, a dashboard widget works like a personal note pinned to your desk. You can keep a publishing checklist or links to tools you open every day. If you are new to the admin area, start with our guide on the WordPress dashboard explained for beginners.

What Is wp_add_dashboard_widget() and How Does It Work?

WordPress provides a built in function called wp_add_dashboard_widget() for this exact job. It takes a unique ID for your widget, a title that appears at the top of the box, and the name of a callback function that prints the content inside the box. WordPress creates the box and styles it to match the rest of the dashboard.

You must call wp_add_dashboard_widget() inside the wp_dashboard_setup action hook. WordPress runs this hook while it builds the dashboard, so your widget is registered at the right moment. The official function reference at developer.wordpress.org documents this function and its parameters.

The callback function is where your widget content lives. It can print plain text, HTML links, a short list, or dynamic information pulled from your site. Keep the content short, because a dashboard widget is a small box, not a full page.

How Do You Add a Basic Custom Dashboard Widget?

The simplest widget needs only two functions: one to register the widget and one to print its content. The first function hooks into wp_dashboard_setup and calls wp_add_dashboard_widget() with an ID, a title, and the callback name. Save the code in a child theme functions.php file or in the Code Snippets plugin, then refresh your dashboard.

function vtg_register_welcome_widget() {
    wp_add_dashboard_widget(
        'vtg_welcome_widget',
        'Welcome to Your Website',
        'vtg_welcome_widget_content'
    );
}
add_action( 'wp_dashboard_setup', 'vtg_register_welcome_widget' );

function vtg_welcome_widget_content() {
    echo '<p>Welcome back. If you need help with this site, contact support and include the page URL where the problem appears.</p>';
    echo '<p><a href="https://yoursite.com/contact/">Contact support</a></p>';
}

Use a unique ID for your widget, and start it with a short prefix such as vtg so it never clashes with a widget added by a plugin or theme. Test the widget right after you save the code, and check that the box appears, the title is correct, and every link works.

How Do You Build a Help and Links Widget?

A help and links widget is the most useful version of this idea, because it answers the questions people ask most often. It holds a short welcome message, a list of links to the pages and tools your team uses, and a clear way to reach support.

function vtg_register_help_widget() {
    wp_add_dashboard_widget(
        'vtg_help_links_widget',
        'Need Help or Quick Links?',
        'vtg_help_links_widget_content'
    );
}
add_action( 'wp_dashboard_setup', 'vtg_register_help_widget' );

function vtg_help_links_widget_content() {
    echo '<p>Use the links below for the pages and tools you need most often.</p>';
    echo '<ul>';
    echo '<li><a href="https://yoursite.com/style-guide/">Site style guide</a></li>';
    echo '<li><a href="https://yoursite.com/publishing-checklist/">Publishing checklist</a></li>';
    echo '<li><a href="https://yoursite.com/contact/">Contact support</a></li>';
    echo '</ul>';
}

Replace the example links with your own pages, and keep the list short. Three to five links are enough for most sites. For a matching branded touch, read our guide on how to change the WordPress login logo without a plugin.

How Do You Remove Default WordPress Dashboard Widgets?

WordPress ships with several default widgets, and most sites do not need all of them. The At a Glance box, the Activity box, the Quick Draft box, and the WordPress Events and News box all take up space, and on a client site they can distract from the content that matters.

Use remove_meta_box() inside the same wp_dashboard_setup hook to remove a default widget. Each default widget has its own ID, and you pass that ID to remove_meta_box() along with the dashboard screen name and the context where the box lives. Keep the ones you actually use, and remove only the ones that add noise.

function vtg_remove_default_dashboard_widgets() {
    remove_meta_box( 'dashboard_primary', 'dashboard', 'side' );
    remove_meta_box( 'dashboard_quick_press', 'dashboard', 'side' );
    remove_meta_box( 'dashboard_activity', 'dashboard', 'normal' );
}
add_action( 'wp_dashboard_setup', 'vtg_remove_default_dashboard_widgets' );

In this example, dashboard_primary is the WordPress Events and News box, dashboard_quick_press is the Quick Draft box, and dashboard_activity is the Activity box. A cleaner dashboard also loads a little faster, and our guide on choosing good web hosting explains why server speed matters for admin pages too.

How Do You Show a Widget Only to Certain User Roles?

Not every widget suits every user. An admin notice about updates or backups is useful for site owners, but it only confuses an author who just needs to write posts. Role based visibility solves this problem by checking the current user before the widget is registered.

Use current_user_can() to check what the logged in user is allowed to do. The function checks a capability, not a role name directly, so you can target editors with edit_pages or administrators with manage_options. The example below registers the widget only for users who can manage options.

function vtg_register_admin_only_widget() {
    if ( ! current_user_can( 'manage_options' ) ) {
        return;
    }
    wp_add_dashboard_widget(
        'vtg_admin_notes_widget',
        'Admin Notes',
        'vtg_admin_notes_widget_content'
    );
}
add_action( 'wp_dashboard_setup', 'vtg_register_admin_only_widget' );

function vtg_admin_notes_widget_content() {
    echo '<p>Backup runs daily at 2am. Check the backup log before any plugin update.</p>';
}

Choose the capability with care, because a wrong capability can hide the widget from the very people who need it. Test with a second user account that has the target role. Never rely on a hidden widget as a security measure, because hiding a box does not block access to the settings.

How Do You Style a Custom Dashboard Widget?

By default, a custom widget uses the standard WordPress dashboard style, which is clean and consistent. That is usually the right choice, because it matches every other box on the screen. You can still add a small amount of CSS when you want a link to stand out or an important line to catch the eye.

function vtg_dashboard_widget_styles() {
    echo '<style>.vtg-widget-highlight { background: #fff8e1; padding: 10px; border-left: 4px solid #f0b429; }</style>';
}
add_action( 'admin_head', 'vtg_dashboard_widget_styles' );

Add a matching class to the HTML in your widget callback, and the CSS will style that part of the box. A soft background and a coloured left border work well for an important notice. If you want to learn more about safe CSS, our guide on how to add custom CSS in WordPress covers the safe places to put custom styles.

Where Should You Put the Widget Code?

Put the code in a child theme functions.php file or in the Code Snippets plugin, and never put it in a parent theme functions.php file or in any WordPress core file. A parent theme update overwrites functions.php and deletes your widget without warning. A child theme keeps your code safe, and Code Snippets keeps it safe through theme changes too.

  • Child theme functions.php: best when the widget belongs to that theme and you already use a child theme.
  • Code Snippets plugin: best when you want to turn the widget on and off easily, or move it between sites.
  • Custom plugin: best when the widget belongs to the site itself and must survive every theme change.
  • Parent theme functions.php: never use this, because a theme update deletes the code.
  • WordPress core files: never use these, because a WordPress update deletes the code.

Before you add any code, take a backup of your site, or at least a backup of the file you are about to edit. A small PHP error in functions.php can lock you out of the admin area. Code Snippets is safer for beginners, because a faulty snippet can be turned off from the snippets list.

What Mistakes Should You Avoid?

  • Registering the widget outside wp_dashboard_setup, so WordPress never shows it.
  • Using a widget ID that already exists, which can clash with a plugin or theme widget.
  • Putting the code in a parent theme, so a theme update deletes your widget.
  • Adding long content or large images that make the dashboard feel crowded.
  • Showing admin notices to every role, when only administrators need to see them.
  • Using a hidden widget as security, because hiding a box does not block access to settings.

The most common mistake is also the easiest to fix: the widget does not appear because the snippet is not active, or because it was saved in the wrong place. Check the snippet status first, then check that the hook name is wp_dashboard_setup and that the function names match.

Frequently Asked Questions

Can I add a custom dashboard widget without a plugin?

Yes. Use wp_add_dashboard_widget() inside the wp_dashboard_setup hook, and add the code to a child theme functions.php file or to the Code Snippets plugin. You only need a register function and a callback function.

How do I remove the default WordPress dashboard widgets?

Use remove_meta_box() inside the wp_dashboard_setup hook, with the ID of the widget you want to remove. For example, dashboard_primary removes the WordPress Events and News box, and dashboard_quick_press removes the Quick Draft box.

Can I show a dashboard widget only to administrators?

Yes. Check current_user_can( ‘manage_options’ ) at the start of your register function, and return early when the check fails. Only administrators will see the widget. Test with a second account that has a different role.

Will my custom dashboard widget survive a theme update?

It will survive when you put the code in a child theme functions.php file, in the Code Snippets plugin, or in a small custom plugin. It will not survive in a parent theme functions.php file, because a theme update overwrites that file.

Last updated: November 2026.

Hostinger - Get 20% OFF

Habib ur Rehman

Hello! I'm the founder of VU Tech Geek. As a BSCS graduate and experienced WordPress professional, I'm passionate about technology and education. My Virtual University journey has given me valuable insights and knowledge, which I love to share with fellow students.… More »

Related Articles

Leave a Reply

Your email address will not be published. Required fields are marked *

Back to top button

Adblock Detected

Please consider supporting us by disabling your ad blocker