Wp Admin Notices

WordPress Admin Notices

The colored banner panels that appear above plugin admin pages. WP 6.4 added a proper helper (wp_admin_notice() / wp_get_admin_notice()) so you don't have to hand-write the <div class="notice notice-X is-dismissible"> markup anymore. Most plugins still do. This skill is the modern recipe + the dismissal-persistence pattern that's the hard part.

When to use this skill

Trigger when ANY of the following is true:

• A plugin needs an admin banner: post-save success flash, integration warning, missing-config nag, version-bump tour, or first-run instructions.
• Code references admin_notices, network_admin_notices, user_admin_notices, all_admin_notices, wp_admin_notice, wp_get_admin_notice, notice-error, notice-warning, notice-info, notice-success, is-dismissible, wp_admin_notice_args.
• The user wants a "dismiss forever" button on a notice and is reaching for cookies / localStorage when user-meta is the right place.
• The user complains: "my notice shows on every admin page" / "I dismissed it but it came back".

The four hooks — pick by audience

wp-admin/admin-header.php:290-321 uses if (is_network_admin()) / elseif (is_user_admin()) / else to fire exactly one of the three context-specific hooks (at lines 299, 306, 313), then ALWAYS fires all_admin_notices at line 321 in addition. So on any given admin page render you get two hook fires: one context-specific + all_admin_notices.

Most plugins want admin_notices unless they have a clear reason for one of the others.

Render markup the WP 6.4+ way

wp_admin_notice( $message, $args ) (defined at wp-includes/functions.php:9189) emits the full <div> wrapper with the right classes and runs wp_kses_post() on the markup. Args (verified at :9078):

add_action( 'admin_notices', static function (): void {
    if ( empty( get_option( 'myplugin_api_key' ) ) ) {
        wp_admin_notice(
            sprintf(
                /* translators: %s: settings page URL */
                __( 'My Plugin needs an API key. <a href="%s">Configure now</a>.', 'myplugin' ),
                esc_url( admin_url( 'admin.php?page=myplugin' ) )
            ),
            array(
                'type'        => 'warning',
                'dismissible' => false,
                'id'          => 'myplugin-api-key-missing',
            )
        );
    }
} );

If you specifically need just the markup string (e.g. to inject from a custom render path), use wp_get_admin_notice() with the same args — it returns the HTML without echoing. When you echo that string yourself, pass it through wp_kses_post() and keep dynamic id / attribute values sanitized.

Targeting the right screen

admin_notices runs on every admin page. Without filtering you spam the user across the whole admin. Use get_current_screen() to narrow:

add_action( 'admin_notices', static function (): void {
    $screen = get_current_screen();
    if ( ! $screen || 'toplevel_page_myplugin' !== $screen->id ) {
        return;
    }
    wp_admin_notice( __( 'Settings imported.', 'myplugin' ), array( 'type' => 'success' ) );
} );

Common screen IDs: dashboard, plugins, edit-post, edit-{cpt}, post, post-new, toplevel_page_{slug}, settings_page_{slug}, {parent}_page_{slug}.

Persisted dismissal (per-user)

is-dismissible adds an X button but core ONLY hides the notice in the DOM — next page load shows it again. For "dismiss forever" persistence, store a flag in user meta and bail before rendering.

// 1. Don't render if the user dismissed.
add_action( 'admin_notices', static function (): void {
    $user_id = get_current_user_id();
    if ( ! $user_id || get_user_meta( $user_id, 'myplugin_dismissed_v2_intro', true ) ) {
        return;
    }
    wp_admin_notice(
        __( 'My Plugin v2 is here. <a href="#" class="myplugin-dismiss-intro">Got it</a>', 'myplugin' ),
        array( 'type' => 'info', 'dismissible' => true, 'id' => 'myplugin-v2-intro' )
    );
} );

// 2. REST endpoint to record dismissal.
add_action( 'rest_api_init', static function (): void {
    register_rest_route( 'myplugin/v1', '/dismiss-notice/(?P<slug>[a-z0-9_-]+)', array(
        'methods'             => WP_REST_Server::EDITABLE,
        'permission_callback' => static fn () => is_user_logged_in(),
        'callback'            => static function ( WP_REST_Request $req ) {
            $slug = sanitize_key( $req['slug'] );
            update_user_meta( get_current_user_id(), 'myplugin_dismissed_' . $slug, 1 );
            return rest_ensure_response( array( 'ok' => true ) );
        },
    ) );
} );

// 3. Client-side: capture either the built-in close button OR your "Got it" link.
// Enqueue this script with deps: array( 'wp-api-fetch' ).
jQuery( function ( $ ) {
    $( document ).on( 'click', '#myplugin-v2-intro .notice-dismiss, .myplugin-dismiss-intro', function ( event ) {
        event.preventDefault();
        wp.apiFetch( {
            path:   '/myplugin/v1/dismiss-notice/v2_intro',
            method: 'POST',
        } );
        $( '#myplugin-v2-intro' ).fadeOut( 100 );
    } );
} );

The .notice-dismiss button is generated by core JS when is-dismissible is set; bind to that AND any custom dismiss link inside the message.

Flash notices after a redirect — use a transient

The Settings API handles its own "Settings saved" flash via settings_errors() — see wp-admin-settings-api. For non-Settings-API flows (custom admin form, after a bulk action redirect), use a per-user transient:

// At the end of a successful POST handler:
set_transient( 'myplugin_flash_' . get_current_user_id(), array(
    'message' => __( 'Records imported.', 'myplugin' ),
    'type'    => 'success',
), 60 );
wp_safe_redirect( $back_url );
exit;

// On the next admin page render:
add_action( 'admin_notices', static function (): void {
    $key   = 'myplugin_flash_' . get_current_user_id();
    $flash = get_transient( $key );
    if ( ! is_array( $flash ) || empty( $flash['message'] ) ) {
        return;
    }
    delete_transient( $key );
    $type = sanitize_key( $flash['type'] ?? 'info' );
    if ( ! in_array( $type, array( 'error', 'warning', 'info', 'success' ), true ) ) {
        $type = 'info';
    }

    wp_admin_notice( esc_html( $flash['message'] ), array(
        'type'        => $type,
        'dismissible' => true,
    ) );
} );

Per-user keys avoid one user's flash leaking onto another's session.

Customizing markup — wp_admin_notice_args / wp_admin_notice_markup

Both filter at wp-includes/functions.php:9098 and :9167. Use the args filter to inject a default class on every notice your plugin emits; use the markup filter to wrap output (e.g. add an icon span).

add_filter( 'wp_admin_notice_args', static function ( array $args, string $message ): array {
    if ( ! empty( $args['id'] ) && str_starts_with( $args['id'], 'myplugin-' ) ) {
        $args['additional_classes'] = array_merge(
            $args['additional_classes'] ?? array(),
            array( 'myplugin-notice' )
        );
    }
    return $args;
}, 10, 2 );

Critical rules

• Exactly one of the context-specific three fires per page render, plus all_admin_notices ALWAYS fires in addition. Hooking BOTH admin_notices and all_admin_notices for the same notice produces duplicate output on standard admin pages. Pick one.
• Always check get_current_screen() for plugin-scoped notices. A bare add_action( 'admin_notices', ... ) runs on every admin page including unrelated screens.
• is-dismissible only hides client-side — it does NOT persist. The dismiss button doesn't write anywhere. If you want "dismiss forever", you write the user meta yourself via a REST/AJAX endpoint.
• Declare wp-api-fetch when dismissing through REST. The admin nonce middleware is attached by that script; otherwise your dismiss call can fail or wp.apiFetch can be undefined.
• The type arg must NOT contain spaces. WP triggers _doing_it_wrong and the value still goes directly into notice-<type>, producing broken / extra classes.
• Escape the message yourself. wp_admin_notice() runs wp_kses_post() on the final markup — which allows <a> / <strong> / common HTML but strips dangerous tags. Inline user-controlled data with esc_html() / esc_attr() / esc_url() BEFORE passing to the function. The wrapper is not a sanitizer.
• wp_get_admin_notice() returns raw markup. It does not run wp_kses_post(); only wp_admin_notice() does that before echoing.
• Flash transients must be per-user. A global myplugin_flash key shows User B's "Imported!" notice to every admin on the next page load.
• Don't render notices in cron / REST contexts. Hooks like admin_notices only fire on admin page renders. A successful background job should write to a transient and let the next admin pageview surface it.

Common AI mistakes

// WRONG — hand-rolled markup, missing translator-safe wrapper, easy to drift from core CSS
echo '<div class="notice notice-success is-dismissible"><p>Saved!</p></div>';

// RIGHT — let core build the markup
wp_admin_notice( esc_html__( 'Saved!', 'myplugin' ), array( 'type' => 'success', 'dismissible' => true ) );

// WRONG — runs on every admin page including unrelated screens
add_action( 'admin_notices', static fn () => wp_admin_notice( '…', array( 'type' => 'warning' ) ) );

// RIGHT — gate on the current screen
add_action( 'admin_notices', static function (): void {
    $s = get_current_screen();
    if ( $s && 'toplevel_page_myplugin' === $s->id ) {
        wp_admin_notice( '…', array( 'type' => 'warning' ) );
    }
} );

// WRONG — "is-dismissible" with no persistence; reappears on every reload
wp_admin_notice( '…', array( 'type' => 'info', 'dismissible' => true ) );

// RIGHT — also gate on user meta + REST endpoint to record dismissal (see Persisted dismissal section)

// WRONG — global flash key; one user's success leaks to all admins on next load
set_transient( 'myplugin_flash', $msg, 60 );

// RIGHT — scope per user
set_transient( 'myplugin_flash_' . get_current_user_id(), $msg, 60 );

Cross-references

• See wp-admin-settings-api for add_settings_error / settings_errors — the Settings-API-native flash mechanism, which is the right tool when the notice belongs to an options page save.
• See wp-rest-api for the dismiss-notice endpoint shape — permission_callback + capability check.
• See wp-admin-list-table for set_transient flash usage after a bulk action redirect.

What this skill does NOT cover

• Block editor notices (wp.data.dispatch( 'core/notices' ).createSuccessNotice). Different stack — React/Redux state, not the classic PHP banners.
• Network-admin notices via update-core / plugin-install routes. Those have their own machinery (update-nag, core-major-auto-updates-notice).

References

• wp-includes/functions.php:9078 — wp_get_admin_notice() definition with full $args shape.
• wp-includes/functions.php:9189 — wp_admin_notice() echo helper (runs wp_kses_post, fires wp_admin_notice action before output).
• wp-admin/admin-header.php:290-321 — the if/elseif/else that picks ONE of network_admin_notices (line 299) / user_admin_notices (306) / admin_notices (313), then unconditional all_admin_notices at line 321.