How to Add Admin Notices & Error Messages to WordPress

Admin notices are an integral part of plugins, they allow you to show error/success/warning messages to your users, prompting them for action or simply notifying them of something that has happened.

In this article, we’ll take a look at the standard way to add admin notices and some additional options introduced in WordPress 4.2, including how to make notices dismissable.

Continue reading, or jump ahead using these links:

• What is an Admin Notice?
• The Anatomy of an Admin Notice
• Adding Notices to the Page
• Generating Notices Via User Actions
• Dismissable Notices
  • The Conditional Notice
  • Detecting The Click
  • Updating Our Option
  • Bringing the Notice Back

What is an Admin Notice?

An admin notice is a notification block consisting of a white background, a colored left border and some text. There are three types: green, orange and red. Given the class names, they should be used for update complete notices, update prompts and errors respectively. That being said, green ones are often used for general success messages, which I think is just fine.

Note that update prompts – or update nags – appear at the very top of the screen while the other two types are shown below the page title.

The Anatomy of an Admin Notice

Each notice is essentially a div with the notice class, in addition to another specific one. Green notices use the updated class, red notices use the error class, update nags use the update-nag class. Within this class you can add any content, a single line of text surrounded by a paragraph tag is the usual choice. The HTML for the notices in the screenshot above looks like this:

Adding Notices to the Page

An action is used to add update messages. This is ideal because plugin authors can overwrite default behaviors. In some instances you may want to suppress some messages – actions give you the ability to do so. The hook to use is admin_notices, the hooked function should simply echo the HTML required, something like this:

Should you need to add two notices at once, I suggest using two separate hooks instead of writing the HTML for both in the same function. This allows you or other plugin authors  to suppress only one message. This kind of flexibility is the basis of WordPress’ modularity, as plugin authors it is our job to uphold this standard.

In case you are unfamiliar with the _e() function it is used for translation purposes. It is part of a family of functions you can use to make your plugin available in multiple languages. If you’d like some more info on this, take a look at our guide to translating plugins

Generating Notices Via User Actions

Generally you will have some if statements in your code since your notices are dependent on specific actions and outcomes.

Let’s look at a plugin that displays a notice if the Advanced Custom Fields plugin is not active. This is handy if we rely on it, or if it makes our plugin that much better.

Dismissable Notices

WordPress 4.2 has given us built-in dismissible notices. On the front-end all you need to do is give your notices the is-dismissable class.

The downside is that as of yet there is no standardized way to get WordPress to remember the dismissal, except in a few cases. Read all about this in core developer Helen Hou-Sandi’s update.

For now, the best method is to bind an event to the click and do whatever we need to via AJAX. The process for this is as follows:

1. The notice will only display if he user has not dismissed it. Therefore we will have an option my-acf-notice-dismissed which will be 1 if the user has dismissed the notice.
2. We will detect a click on the dismissal button and fire an AJAX call
3. The AJAX call will update the my-acf-notice-dismissed option to 1
4. If we want to be super-thorough we can detect the presence of the the_field() ACF function and remove the option if it exists. This will make sure that if ACF is installed, then uninstalled, the notice will come back. This requires a check for the function on each page load though, which may be a bit wasteful.

The Conditional Notice

Let’s grab the my-acf-notice-dismissed option from the database and create a notice which only shows up if the value of the option is not 1.

This is very similar to our code above, with the addition of an empty check for our option. The value of our option may well be 0, but this is still considered to be empty, so we’re all set there.

Note that I’ve added a my-acf-notice class to the notice to make sure we can bind an event to only our notice.

Detecting The Click

Before we write any Javascript, we’ll need to create a JS file and enqueue it. I’m assuming a simple plugin with the Javascript file in a js folder.

Within this JS file, we’ll need to create a click event, bound to .my-acf-notice – this click event will trigger our AJAX call.

Updating Our Option

The action parameter of our AJAX call was my_dismiss_acf_notice which gives us the template for creating the code that handles things on the server side. All that is needed is a quick update to the my-acf-notice-dismissed option, setting its value to 1.

If you haven’t used AJAX in WordPress before we have a handy guide to AJAX you can use to brush up on your skills.

At this point you should be able to load your dashboard, see the notice and dismiss it, it will not show up in the admin again.

Bringing the Notice Back

Right now our notice is not complete. If ACF is not installed it will pop up. The user may then dismiss it, but install ACF later. If ACF is then deactivated for whatever reason, the notice will remain hidden.

To get around this, we can check for the existence of the the_field() function – a prominent function used in ACF – and if it doesn’t exist, delete the option.

This is a little wasteful, but we can do it using an admin hook which fires on admin screens only, which should be okay.

Admin notices are useful and modular parts of the admin experience. They can be registered individually, allowing developers better access to your work.

New additions in WordPress 4.2 allow for dismissable notices, although we do have to work a little to make them persistent. Hopefully this will change as a framework is implemented for better notice management, perhaps in one of the next couple of versions.

If you have a great custom way to create notices or you’ve used the default methods to great effect, let us know in the comments below.