The WordPress dashboard is the first screen you see after logging in. It shows a set of boxes, called widgets, with news, activity, quick draft, and site health information. On a fresh install the screen is useful, but as plugins pile up, the dashboard fills with boxes you never read. Client sites are worse, because a client who sees twenty widgets feels lost before doing any work.
A custom dashboard widget is a box you add yourself, with content you choose. It can hold help links, a support phone number, a checklist for new editors, or shortcuts to the pages your team uses every day. It turns a noisy default screen into a tidy starting point for you, your editors, and your clients.
This guide shows you how to add a custom dashboard widget without a plugin. You will start with the no code cleanup in Screen Options, then add a help links widget with the wp_add_dashboard_widget function, then hide the default boxes you never use. You will also learn where to put the code so a theme update never wipes it out. If you are new to the admin area, read our guide to the WordPress dashboard explained for beginners first.
What are WordPress dashboard widgets?
Dashboard widgets are the boxes on the WordPress home screen in the admin area. Each box shows a small piece of information or a small tool. The default set includes At a Glance, Activity, Quick Draft, WordPress Events and News, and Site Health Status. Plugins add their own boxes too, which is how the screen gets crowded so fast.
Dashboard widgets are different from the widgets you place in sidebars and footers. Sidebar widgets appear on the public site for visitors, while dashboard widgets appear only inside the admin area for logged in users. To learn the public side, read our guide to WordPress widgets explained for beginners. The code in this guide only touches the admin dashboard, so it never changes what visitors see.
Each user can arrange their own dashboard by dragging boxes, collapsing them, or hiding them in Screen Options. That personal control is useful, but it is not enough for a team, because every new user starts with the same crowded default screen. A custom widget set by code fixes the starting point for everyone.
How do I clean up the dashboard without code?
Before writing any code, clean up your own screen with Screen Options. Open the dashboard, click Screen Options at the top right, and untick every box you never read. The change applies to your user account only, so other users keep their own layout. This is the fastest way to declutter your own view, and it takes less than a minute.
You can also drag the boxes you do use into the left column, where your eye lands first, and collapse the rest by clicking the small arrow on each box title. Put Site Health and Activity where you can see them, and collapse WordPress News if you rarely read it. This no code cleanup is worth doing even if you plan to add custom widgets later, because it shows you which default boxes are worth keeping.
The limit is that Screen Options only change one user at a time. A new editor, a new client, or a new shop manager still sees the full noisy screen until they clean it up themselves. That is the problem custom code solves, because it changes the dashboard for every user on the site at once.
How do I add a custom dashboard widget with code?
The wp_add_dashboard_widget function registers a new box on the dashboard. It needs three things: a unique id for the widget, a title that shows in the box header, and a callback function that prints the content inside the box. Add the code below to your child theme functions.php file or with the Code Snippets plugin, and a help links widget appears for every admin user.
function vu_help_widget_content() {
echo '<p>Need help? Use these links before emailing support.</p>';
echo '<ul>';
echo '<li><a href="/wp-admin/post-new.php">Write a new post</a></li>';
echo '<li><a href="/wp-admin/upload.php">Media library</a></li>';
echo '<li><a href="/wp-admin/users.php">Manage users</a></li>';
echo '<li><a href="https://wordpress.org/">WordPress support forums</a></li>';
echo '</ul>';
echo '<p>Support hours: Monday to Friday, 9am to 5pm.</p>';
}
function vu_add_help_widget() {
wp_add_dashboard_widget(
'vu_help_widget',
'Site Help and Quick Links',
'vu_help_widget_content'
);
}
add_action( 'wp_dashboard_setup', 'vu_add_help_widget' );The code runs on the wp_dashboard_setup hook, which fires when WordPress builds the dashboard. The callback prints plain HTML, so you can put almost anything inside the box: links, a phone number, a short checklist, or a reminder of the publishing process. Keep the content short, because a dashboard box should be scanned in seconds, not read like an article.
Check the result by opening the dashboard while logged in as an administrator. The new box appears with the title “Site Help and Quick Links”. Drag it to the top of the left column so it is the first thing you see after login. If the box does not appear, confirm the snippet is active and that you pasted it in functions.php of the child theme, not the parent theme.
How do I remove the default dashboard widgets?
Once your custom widget is in place, hide the default boxes nobody reads. The remove_meta_box function removes a widget by its id, and you call it on the same wp_dashboard_setup hook. The code below hides the Quick Draft box, the WordPress Events and News box, and the welcome panel, which are the three boxes most sites never use.
function vu_remove_dashboard_widgets() {
remove_meta_box( 'dashboard_quick_press', 'dashboard', 'side' );
remove_meta_box( 'dashboard_primary', 'dashboard', 'side' );
remove_meta_box( 'dashboard_right_now', 'dashboard', 'normal' );
remove_action( 'welcome_panel', 'wp_welcome_panel' );
}
add_action( 'wp_dashboard_setup', 'vu_remove_dashboard_widgets' );Each remove_meta_box call needs the widget id, the screen name, and the column where the box lives. The ids above are the standard ones for the default widgets, but plugins use their own ids, which you can find by inspecting the box HTML in your browser or by searching the plugin code for wp_add_dashboard_widget. Remove only boxes you are sure nobody needs, and keep Site Health and Activity, because they warn you about real problems.
Be careful with hiding boxes for other roles. An editor may rely on the At a Glance box to see pending posts, while an administrator may not. You can wrap a remove call in a current_user_can check, so the box disappears for subscribers but stays for editors. Our guide to hide WordPress admin menu items without a plugin uses the same role check idea for menu items, and the pattern works for dashboard boxes too.
Where should I put the code, functions.php or a plugin?
You have three safe places for this code, and one place you must avoid. Never edit the parent theme functions.php file, because a theme update overwrites it and your widgets vanish. A child theme functions.php file is safe, because theme updates leave the child theme alone. The Code Snippets plugin is also safe, because it stores code in the database and survives theme changes.
The third option is a must use plugin, called an mu-plugin. An mu-plugin is a PHP file placed in the wp-content/mu-plugins folder, and WordPress loads it automatically on every request. It cannot be deactivated from the dashboard, which makes it ideal for client sites, because a client cannot switch it off by accident. Use an mu-plugin when the widget is part of the site setup itself, such as a client help box, and use a child theme or Code Snippets when the widget is part of your own workflow.
Whichever place you choose, keep a backup of the code in a text file on your computer. A single typo in functions.php can lock you out of the admin area with a white screen, so always edit theme files through a code editor with a backup, never through the built in theme editor on a live site. If you do get a white screen, restore the file through your host file manager or FTP. A reliable host makes recovery far less painful, so keep your hosting solid with our web hosting guide.
How do I style the widget to match my brand?
Dashboard widgets use the WordPress admin styles by default, so they look clean without any extra CSS. If you want your brand colour or a custom layout, add a small admin stylesheet with the admin_enqueue_scripts hook, and target your widget by its id. Keep the styling light, because the admin area is a work tool, not a design showcase. A coloured heading, a tidy link list, and generous spacing are enough.
You can also control the colour scheme each user sees. Go to Users, then Profile, and pick an admin colour scheme. A consistent scheme helps clients recognise their own site, and it makes screenshots in your support emails match what the client sees. For the official reference, see the developer documentation at developer.wordpress.org.
How do I test the widget for every user role?
A widget that looks perfect for an administrator may be useless for an editor or a subscriber. Test it with an account for each role your site uses, and confirm the links point to pages that role can actually open. A link to the user management screen is pointless for an editor, because WordPress blocks that page for them.
- Create a test editor account and log in with it in a private browser window.
- Confirm the custom widget appears and every link opens without a permission error.
- Repeat the check with a subscriber account if your site has members.
- Check the dashboard on a small screen, because widgets stack into one column on mobile.
- Confirm the widget still appears after you switch themes, if you used an mu-plugin or Code Snippets.
If a link should only appear for one role, wrap it in a current_user_can check inside the callback function. That keeps the widget relevant for each user, and it stops editors from seeing admin only links they cannot use. A widget that respects roles feels professional, while a widget full of dead links feels broken.
When is a plugin the better choice?
The code method in this guide is free, light, and perfect for one or two custom boxes with links and short text. A plugin is better when you need widgets with charts, recent orders, form entries, or data pulled from another service. A dashboard plugin is also better when a non technical user must edit the widget content from a settings screen instead of editing code. If you only need a help box and a cleaner screen, the code here does the job with about thirty lines and no extra plugin to update.
Frequently asked questions
Can I add a dashboard widget in WordPress without a plugin?
Yes. Use the wp_add_dashboard_widget function on the wp_dashboard_setup hook, as shown in this guide. Add the code to a child theme, Code Snippets, or an mu-plugin, and the widget appears for every admin user with no plugin installed.
How do I remove the WordPress news widget from the dashboard?
Call remove_meta_box with the id dashboard_primary on the wp_dashboard_setup hook, as shown in the code above. You can also hide it for your own account only through Screen Options at the top right of the dashboard, without any code at all.
Where do I put dashboard widget code so it survives updates?
Put it in a child theme functions.php file, in the Code Snippets plugin, or in an mu-plugin file under wp-content/mu-plugins. Never put it in the parent theme functions.php file, because a theme update overwrites that file and deletes your code.
Can different user roles see different dashboard widgets?
Yes. Wrap the widget registration or individual links in a current_user_can check inside your callback function. That way administrators see admin links, editors see editing links, and subscribers see only what applies to them.
Last updated: November 2026.
