admin_notices │ action-hook │ WP 3.1.0

Fires while notices (messages and errors) are displayed at the top of an admin panel page. The attached function must output HTML.

Although a notice appears below the heading, technically it is output earlier and then moved below the heading by a script. This makes it possible to output a notice before the page's own HTML is rendered.

WordPress admin notices API

Example of how such a notice looks:

Notice HTML:

<div class="notice notice-success is-dismissible">
	<p>Post updated. <a href="http://example.com/title/">View</a></p>
</div>

HTML template for these messages:

<div class="{class}"><p>{message}</p></div>

{class}

CSS classes of the block. The required class is notice; add the following classes as needed:

• notice-success for successful operations. Displays a green stripe on the left.

• notice-error for errors. Displays a red stripe on the left.

• notice-warning for warnings. Displays an orange stripe on the left.

• notice-info for information. Displays a blue stripe on the left.

• is-dismissible adds a close icon button (a cross at the end of the block). The icon is added via JavaScript. Clicking it hides (removes) the notice block, but this state is not saved, so the block appears again after the page is refreshed.

• notice-alt can be added to any of these classes to tint the background with the corresponding color.

class="notice notice-success notice-alt is-dismissible" is an example using the complete set of classes.

There is also an update-nag class, which creates a block with an orange stripe. It is placed before the <h2> heading rather than after it and uses the inline-block CSS property instead of block, so it does not span the full screen width.

Use of this type is not recommended.

Before version 4.7, the updated class was also available as an equivalent of notice-success, and error as an equivalent of notice-error. They are still supported but are not recommended.

{message}

The message text or HTML.

Alternatives to the admin_notices event

This hook has alternatives commonly used for the same purpose—displaying a message—but under different conditions:

• network_admin_notices is used with Multisite and displays the message to the network administrator.

• user_admin_notices is used with Multisite and displays the message to a site administrator in the network.

• all_admin_notices works exactly like admin_notices but has a different name, probably to make its purpose clearer in plugin code. The hooks may also behave differently in the future.

Usage

add_action( 'admin_notices', 'wp_kama_admin_notices_action' );

/**
 * Function for `admin_notices` action-hook.
 * 
 * @return void
 */
function wp_kama_admin_notices_action(){
	// action...
}

Examples

#1 Basic usage

Suppose we are developing a plugin and need to display the message "Settings updated!" after its options page is updated. In the POST request handler, attach a function to the admin_notices event after a successful update:

<?php
add_action( 'admin_notices', 'my_plugin_notice' );
function my_plugin_notice() {
	?>
	<div class="notice notice-success is-dismissible">
		<p>Settings updated!</p>
	</div>
	<?php
}

The localization function _e can also be used here to make the message translatable:

<div class="notice notice-success is-dismissible">
	<p><?php _e( 'Settings updated!', 'my-text-domain' ); ?></p>
</div>

The updated class displays a message with a white background and a green stripe on the left.

#2 Display an error

This example is similar to the first one, but displays an error message.

add_action('admin_notices', 'my_plugin_error_notice');
function my_plugin_error_notice(){
	$message = "Save error";
	echo '<div class="notice notice-error is-dismissible"> <p>'. $message .'</p></div>';
}

The error class displays a message with a white background and a red stripe on the left.

#3 Custom block

add_action('admin_notices', function(){
	echo '<div class="update-nag"><p>My message</p></div>';
});

The update-nag class displays a message with a white background and an orange stripe on the left. The block is also placed before the heading (the <h2> tag).