WordPress Admin Notices Example: Show Dismissible Plugin Alerts Safely

Last reviewed: April 22, 2026

Admin notices are useful when a plugin needs to tell administrators that something happened or needs attention. They also become annoying quickly when they appear everywhere, cannot be dismissed, or show vague warnings that do not explain what to do next.

This guide shows how to render targeted, dismissible WordPress admin notices safely using modern notice helpers and sensible screen targeting.

Best fit

Use admin notices for operational feedback: setup incomplete, sync failed, migration finished, cache refreshed, license expired, or a required configuration value missing. Do not use notices as permanent advertising banners or generic reminders that appear on every admin screen.

Basic notice with wp_admin_notice()

<?php
add_action( 'admin_notices', 'vulnwp_show_setup_notice' );

function vulnwp_show_setup_notice() {
	if ( ! current_user_can( 'manage_options' ) ) {
		return;
	}

	$settings = get_option( 'vulnwp_plugin_settings', array() );

	if ( ! empty( $settings['configured'] ) ) {
		return;
	}

	wp_admin_notice(
		esc_html__( 'VulnWP setup is not complete. Review plugin settings before enabling production sync.', 'vulnwp-notices' ),
		array(
			'type'        => 'warning',
			'dismissible' => true,
			'id'          => 'vulnwp-setup-notice',
		)
	);
}

The notice checks capability, checks state, and uses a specific ID. The message tells the administrator what the problem is and what to do next.

Target a specific admin screen

function vulnwp_is_plugin_settings_screen() {
	$screen = function_exists( 'get_current_screen' ) ? get_current_screen() : null;

	return $screen && 'settings_page_vulnwp-settings' === $screen->id;
}

Screen targeting prevents unrelated administrators from seeing messages that do not apply to their current task.

Persistent dismissals

The built-in dismissible UI hides a notice in the browser, but many plugins need server-side dismissal so the notice stays dismissed across sessions. Store a user meta flag after a nonce-protected action or AJAX request.

function vulnwp_dismiss_notice_for_user( $user_id ) {
	update_user_meta( $user_id, 'vulnwp_setup_notice_dismissed', 1 );
}

function vulnwp_user_dismissed_notice( $user_id ) {
	return (bool) get_user_meta( $user_id, 'vulnwp_setup_notice_dismissed', true );
}

Notice lifecycle

A notice should have a clear lifecycle. It appears because a condition is true, and it disappears when the condition is fixed or when a user intentionally dismisses it. If a notice can never disappear, it becomes background noise.

For setup notices, prefer condition-based display: show the message while the required setting is missing, then remove it automatically after setup is complete. For informational notices, store a user dismissal flag so one administrator can dismiss it without hiding it from everyone else.

Testing workflow

1. Test with an administrator and a lower-privilege editor.
2. Confirm the notice appears only on intended screens.
3. Confirm dismissal persists when that is required.
4. Fix the underlying condition and verify the notice disappears.
5. Check that the notice text does not expose private configuration values.

Production checklist

• Show notices only to users who can act on them.
• Target relevant admin screens when possible.
• Use clear severity: error, warning, success, or info.
• Make recurring notices dismissible.
• Include the next action in the message.
• Do not expose secrets, raw errors, or server internals.

Common mistakes

• Showing notices to everyone. Editors should not see infrastructure alerts they cannot fix.
• No action path. A warning without a next step creates noise.
• Permanent banners. Non-dismissible notices train users to ignore admin messages.
• Raw error output. Errors need safe wording and operator detail elsewhere.
• Marketing in operational space. Admin notices should be reserved for real site state.

Related reading

Admin notices pair naturally with the Site Health custom test example and the Settings API example.

References and further reading

• WordPress Code Reference: wp_admin_notice()
• WordPress Code Reference: admin_notices
• WordPress Block Editor Handbook: Notices