WordPress User Notices

When working in WordPress’ Gutenberg editor, there may be times when we wish to notify the admin user of a change or response to an action. For example, if we have a custom block that makes a remote API request, we might want to notify the user about the result of that request. Luckily, WordPress has some built in functions to display a user notification in the editor. The rest of this post covers WordPress user notices and some example use cases.

Creating a Notice

In our Gutenberg block’s edit functionality we can access the ability to create a notice by using wp.data.dispatch( 'core/notices' ). To actually format and render a custom notice, we can add a call to the built-in function .createNotice(), making our syntax wp.data.dispatch( 'core/notices' ).createNotice(). Inside createNotice() we can pass parameters to indicate what type of notification to display and what the message should be, along with some other optional parameters.

Let’s say we want to display a message to the user which confirms an action was successful. In this case we’ll use ‘success’ as our first parameter, and we’ll pass in the custom message string as a second parameter. So if we format our notice like this:

wp.data.dispatch( 'core/notices' ).createNotice(
   'success',
   'The action was successful.'
)

We’ll expect to see the user notified like this:

Notice Types

In addition to the ‘success’ type notice demonstrated above, there are three other notice types available: ‘info’, ‘warning’, and ‘error’.

Info Notice

If we simply need to provide some general info to the user, we can use the ‘info’ notice like this:

wp.data.dispatch( 'core/notices' ).createNotice(
   'info',
   'Something notable has occurred.'
)

Which looks like this to the user:

Warning Notice

To warn the user of something that might not be worthy of an error notice, we can use a ‘warning’ notice:

wp.data.dispatch( 'core/notices' ).createNotice(
   'warning',
   'Warning! There is something that you should check on.'
)

Which will be displayed like this:

Error Notice

If something has gone wrong and generated an error, we can use the ‘error’ type like this:

wp.data.dispatch( 'core/notices' ).createNotice(
   'error',
   'An error has occurred'
)

Which looks like this to the user:

Message Options

In addition to the type and message, each notice can receive an optional third parameter, which is an ‘options’ object containing numerous optional notice parameters. These are documented at https://developer.wordpress.org/block-editor/reference-guides/data/data-core-notices/, but they include:

options.context [string]: Context under which to group notice.
options.id [string]: Identifier for notice. Automatically assigned if not specified.
options.isDismissible [boolean]: Whether the notice can be dismissed by user.
options.type [string]: Type of notice, one of default, or snackbar.
options.speak [boolean]: Whether the notice content should be announced to screen readers.
options.actions [Array<WPNoticeAction>]: User actions to be presented with notice.
options.icon [string]: An icon displayed with the notice. Only used when type is set to snackbar.
options.explicitDismiss [boolean]: Whether the notice includes an explicit dismiss button and can’t be dismissed by clicking the body of the notice. Only applies when type is set to snackbar.
options.onDismiss [Function]: Called when the notice is dismissed.

As an example, let’s imagine we’d like to create an error notice with the ID of ‘ryan-custom-block-api-fetch-error’, and we don’t want the user to be able to dismiss the notice. We can write our notice like this:

wp.data.dispatch( 'core/notices' ).createNotice(
   'error',
   'There was a problem fetching data from the API',
   {
      id: 'ryan-custom-block-api-fetch-error',
      isDismissable: false
   }
)

It’s a good idea to include an ID when generating a user notice. Including an ID can prevent multiple instances of the same notice being displayed simultaneously. When a notice with an ID is present, if a new notice with the same ID is generated, the new notice will replace the old one.

Alternate Function Syntax

In addition to the createNotice() function, WordPress provides functions named specifically for the notice types discussed above. These functions are createInfoNotice(), createSuccessNotice(), createWarningNotice(), and createErrorNotice().

We can use the more specific function syntax in a very similar fashion to using createNotice(), simply omitting the the first parameter that would indicate which type of notice to create. For example, if we revisit the error notice example from above:

wp.data.dispatch( 'core/notices' ).createNotice(
   'error',
   'There was a problem fetching data from the API',
   {
      id: 'ryan-custom-block-api-fetch-error',
      isDismissable: false
   }
)

We can rewrite this using createErrorNotice() like this:

wp.data.dispatch( 'core/notices' ).createErrorNotice(
   'There was a problem fetching data from the API',
   {
      id: 'ryan-custom-block-api-fetch-error',
      isDismissable: false
   }
)

More info on WordPress core notices: https://developer.wordpress.org/block-editor/reference-guides/data/data-core-notices/