How to Customize and Use WordPress Dashboard Admin Alert Messages in Your Plugin or Theme

As a WordPress developer, providing users with clear, actionable alerts and notifications is crucial for creating a smooth user experience. One of the most effective ways to convey important information, such as plugin updates, warnings, or reminders, is through the WordPress Dashboard admin alerts. These alerts appear in the backend of WordPress and can serve as crucial touchpoints for admins and other users managing the site.

In this post, we’ll walk you through how to add, customize, and use admin alert messages in your WordPress plugin or theme. This is a great way to ensure that the necessary information reaches your users without them having to search for it.

What Are WordPress Dashboard Admin Alerts?

WordPress admin alerts (also known as admin notices) are messages that appear at the top of the WordPress Dashboard or on specific admin pages. These messages help notify users of important information or events such as plugin updates, new features, or errors. Admin alerts are color-coded by default:

• Success (green): Used for successful actions like updates.
• Error (red): Used for critical issues or errors.
• Warning (yellow): For warnings that need attention but aren’t urgent.
• Info (blue): For general informational messages.

These messages are displayed using the wp_die(), add_action(), or add_settings_error() functions, making them customizable to suit the needs of your plugin or theme.

Why Use Admin Alert Messages?

Admin alerts are useful for a variety of purposes:

• Updating users: You can notify users about plugin or theme updates, new features, or security changes.
• Displaying warnings: Alerts can be used to show critical information such as deprecation notices, compatibility issues, or potential errors.
• Guiding users: Use alerts to offer guidance or show next steps to users after they perform certain actions (e.g., plugin activation or post-publishing).

How to Customize and Display Admin Alert Messages

Step 1: Adding an Admin Alert Message

To create and display an admin alert, you’ll typically use the admin_notices hook, which ensures your message appears in the admin area of WordPress. Let’s create a simple success message in your plugin or theme.

Here’s the basic code to display a custom admin alert message:

function my_custom_admin_notice() {
    ?>
    <div class="notice notice-success is-dismissible">
        <p><?php _e( 'Your custom alert message here!', 'textdomain' ); ?></p>
    </div>
    <?php
}
add_action( 'admin_notices', 'my_custom_admin_notice' );

Explanation:

• The notice notice-success class specifies that the message will be styled as a success (green) alert. You can change notice-success to notice-error, notice-warning, or notice-info depending on the type of message you want to show.
• is-dismissible makes the alert message dismissible, allowing users to close it.
• _e() is a localization function, which makes the message translatable, helping with internationalization.

Step 2: Customizing the Alert Style and Content

You can further customize the alert by changing its content, style, or conditions under which it displays. For example, if you only want to show the message when a specific plugin is active or when a user has a particular role, you can add conditional checks:

function my_custom_admin_notice() {
    // Check if the plugin is active
    if ( ! is_plugin_active( 'some-plugin/some-plugin.php' ) ) {
        return;
    }

    // Custom message
    ?>
    <div class="notice notice-warning is-dismissible">
        <p><?php _e( 'This plugin requires a specific setup. Please check the settings!', 'textdomain' ); ?></p>
    </div>
    <?php
}
add_action( 'admin_notices', 'my_custom_admin_notice' );

This example ensures the alert only shows if a specific plugin is active. You can also check for user roles, post statuses, or any other condition to tailor the alert.

Step 3: Dismissing Admin Alerts

As mentioned earlier, adding the is-dismissible class allows users to dismiss the alert, but you can also programmatically handle the alert’s visibility across sessions using user meta or options.

For example, to prevent the alert from showing after the user dismisses it, you can use set_transient() to save the dismissal status:

function my_custom_admin_notice() {
    // Check if the user dismissed the alert
    if ( get_transient( 'my_custom_alert_dismissed' ) ) {
        return;
    }

    ?>
    <div class="notice notice-success is-dismissible">
        <p><?php _e( 'This is a one-time alert. You can dismiss it!', 'textdomain' ); ?></p>
    </div>
    <?php
}
add_action( 'admin_notices', 'my_custom_admin_notice' );

function dismiss_custom_alert() {
    set_transient( 'my_custom_alert_dismissed', true, 30 * DAY_IN_SECONDS );
}
add_action( 'admin_footer', 'dismiss_custom_alert' );

In this code:

• When the user dismisses the alert, the dismiss_custom_alert() function sets a transient.
• This prevents the alert from appearing again for the next 30 days.

Step 4: Using Admin Alert Messages in Your Theme or Plugin Settings

If your theme or plugin has a settings page, you may want to display alerts based on the user’s interaction with your settings. For example, after a user saves settings, you can display a success message confirming their action.

function my_plugin_settings_alert() {
    if ( isset( $_GET['settings-updated'] ) && $_GET['settings-updated'] == 'true' ) {
        ?>
        <div class="notice notice-success is-dismissible">
            <p><?php _e( 'Your settings have been successfully updated!', 'textdomain' ); ?></p>
        </div>
        <?php
    }
}
add_action( 'admin_notices', 'my_plugin_settings_alert' );

This message will appear only when the user saves the settings in your plugin or theme.

Admin alert messages are a powerful way to inform users about important updates, warnings, and other key actions directly within the WordPress Dashboard. By customizing these alerts with conditional logic, user preferences, and styling, you can create an even more intuitive experience for your plugin or theme users.

With the steps outlined in this post, you now know how to add, customize, and manage admin alert messages. Whether it’s to notify users of updates, provide warnings, or guide them through a specific task, admin alerts can make your WordPress plugin or theme more user-friendly and informative.