Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Use WordPress’s documented Dashboard Widgets API: create a render callback, register it with wp_add_dashboard_widget() on the wp_dashboard_setup action, and add an optional control callback only when the widget needs settings. For Network Admin, use wp_network_dashboard_setup instead. This creates an admin-dashboard widget, not a front-end widget area.
What the Dashboard Widgets API does
The standard PHP API adds boxes to the WordPress administration dashboard. The main function, wp_add_dashboard_widget(), has been available since WordPress 2.7. Its required pieces are a stable widget ID, a displayed title, and a render callback. Read the full API overview in the Dashboard Widgets API handbook.
Do not confuse this feature with theme widgets managed under Appearance > Widgets. Those are front-end components and use a different registration system, as explained in the Theme Handbook.
How to register a basic custom widget
- Choose an ID and title. The ID becomes the widget’s HTML identifier, so keep it unique and stable. Make the title translatable.
- Write the render callback. Output only the dashboard content and escape values for their context.
- Hook registration to the site dashboard. Add your registration function to
wp_dashboard_setup.
<?php
function example_register_dashboard_widget() {
wp_add_dashboard_widget(
'example_dashboard_widget',
esc_html__( 'Example Dashboard Widget', 'example' ),
'example_render_dashboard_widget'
);
}
add_action( 'wp_dashboard_setup', 'example_register_dashboard_widget' );
function example_render_dashboard_widget() {
esc_html_e( 'Dashboard content goes here.', 'example' );
}Place this code in a plugin rather than a theme when the widget is site functionality that should remain active after a theme change. The function reference documents the complete parameter list at wp_add_dashboard_widget().
Free tools Windows power users keep installed
One-click scans. No signup required.
Adding configurable settings
Pass a fourth argument—the control callback—when administrators should configure the widget. That callback displays the settings form and processes its submission; the normal render callback then reads the saved option and displays the result.
wp_add_dashboard_widget(
'example_dashboard_widget',
esc_html__( 'Example Dashboard Widget', 'example' ),
'example_render_dashboard_widget',
'example_dashboard_widget_controls'
);The API identifies the control callback’s role, but a production form still needs normal WordPress safeguards: verify the user has an appropriate capability, include and check a nonce, validate and sanitize submitted values, and escape values when printing them. Store only the settings the widget needs. The render callback should also handle an unset, invalid, or deleted option gracefully.
Rank #2
Choosing position and priority
The function accepts optional context and priority arguments. These parameters were added in WordPress 5.6.0.
| Parameter | Supported values | Purpose |
|---|---|---|
context |
normal, side, column3, column4 |
Preferred dashboard area. |
priority |
high, core, default, low |
Preferred order within that area. |
For example, the optional arguments follow the control callback:
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Rank #3
wp_add_dashboard_widget(
'example_dashboard_widget',
esc_html__( 'Example Dashboard Widget', 'example' ),
'example_render_dashboard_widget',
null,
null,
'side',
'high'
);These are preferences, not a guaranteed final layout. Users can drag widgets, hide them through Screen Options, and save their own order. The handbook warns that saved user preferences can override attempts to force a position. It also documents add_meta_box() as an alternative approach for side placement; see the Dashboard Widgets API guidance.
Site dashboard versus Network Admin
wp_dashboard_setup runs for the regular site dashboard. A multisite network-management widget must be registered separately on wp_network_dashboard_setup; otherwise it will not appear in Network Admin. Keep the callback and capability checks appropriate to the administrators who can access that dashboard. The standard hook reference is wp_dashboard_setup.
Conventional PHP widgets or the Gutenberg system?
| Option | Implementation | Status and best fit |
|---|---|---|
| Dashboard Widgets API | PHP registration with wp_add_dashboard_widget(), a render callback, and optionally a control callback. |
Established documented approach for conventional admin dashboard boxes. |
| Gutenberg Dashboard Widget System | Experimental block-editor widget authoring, build, and registry pipeline. | Use only when deliberately targeting the experimental host and accepting API changes. |
WordPress’s June 2026 developer update says the customizable dashboard “is not a stable admin extension API yet” (WordPress Developer Blog). The Block Editor Handbook, last updated September 15, 2026, says the widget system is experimental, ships behind the gutenberg-dashboard-widgets experiment, and that its APIs and file conventions may change (Dashboard Widget System). For a normal plugin that simply needs an admin dashboard box, the conventional PHP API is the safer choice.
Quick Recap
Practical checks before shipping
- Use a globally unique, stable ID and a translation-ready title.
- Escape translated strings and dynamic output in the correct context.
- Keep registration on the correct dashboard hook: site or Network Admin.
- For settings, enforce capabilities, verify a nonce, sanitize input, validate values, and handle missing options.
- Test with the intended user roles and with existing dashboard widgets enabled.
- Expect users’ Screen Options choices and drag-and-drop order to determine the final layout.
- Do not build on the Gutenberg dashboard experiment without checking its current status and accepting that conventions may change.
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
