Notifications
Preview Notifications
The notification component is an alert box often used when you need to make sure information comes through to the user. It will take the focus away from the current window forcing the browser to read the message.
Notification Design
Notification Type
Dismiss Button
Documentation
Required Markup
Float Notification
<!-- END: .sui-header --> <div class="sui-floating-notices"> <div role="alert" id="unique-id" class="sui-notice" aria-live="assertive" > <!-- Nothing should be placed inside. --> </div> <!-- Place the rest of floating notices here, inside .sui-floating-notices div. --> </div> <!-- START: Regular page content -->
Inline Notification
<div role="alert" id="unique-id" class="sui-notice" aria-live="assertive" > <!-- Nothing should be placed here --> </div>
Alert Actions
These are required actions for Alert Notifications to make them appear when needed.
Open Notice
Below you can find the function to show users the message you want to notify them. You can also learn more about each of its parameters by clicking on each section below.
SUI.openNotice( noticeId, noticeMessage, noticeOptions );
This is the unique ID of the element serving as the alert notice container.
const noticeId = 'unique-id';
In this parameter you must include the message would like to display in the notice. Remember it must be properly wrapped on its tag.
const noticeMessage = '<p>Hello, I am a notification.</p>';
This object parameter will allow you to overwrite default settings and styles for the notice. The allowed options are: type, icon, dismiss, and autoclose.
// Declare this only once, the rest of the options
// shown below will be attached to this variable.
const noticeOptions = {};
Type
You can leave this option empty to get the default (gray) notification or use: info for blue notification, success for green notification, warning for yellow notification, error for red notification or upsell for purple notification.
noticeOptions.type = 'success'; // To show a green (success) notification.
Icon
Add the name of the icon without its prefix sui-icon-. The "loader" icon will also add sui-loading state to the icon.
noticeOptions.icon = 'wordpress'; // This will show WordPress icon from SUI icons font.
Dismiss
This is an object that will handle 3 different options for the dismiss button: show (visibility), label and tooltip.
noticeOptions.dismiss = {};
Dismiss Button Visibility
Change this to show or hide the dismiss button.
noticeOptions.dismiss.show = true; // This will show a dismiss button for the notice.
Dismiss Button Label
The dismiss button will always be an icon button but screen readers need a proper label to notify users what's the button about. This option will help you to overwrite button label.
noticeOptions.dismiss.label = 'Dismiss Label';
Dismiss Button Tooltip
There will be cases when you need a tooltip for the dismiss button. Leave this option empty for no tooltip to show up.
noticeOptions.dismiss.tooltip = 'Dismiss Tooltip';
Auto Close
This is an object that will handle 2 different options: show (to enable or disable autoclose) and timeout.
Auto Close Show
This boolean variable will allow you to enable or disable autoclose ability for notices but when the dismiss button is enabled this will stop working since all dismissible notices will never auto-close.
noticeOptions.autoclose.show = false; // This will disable auto-close.
Auto Close Timeout
This option will define how much time have to pass before notice closes. By default it will close after 5 seconds. Make sure to add the value in milliseconds.
noticeOptions.autoclose.timeout = 5000; // Closes 5 seconds after show animation ends.
Close Notice
The Open Notice action already includes auto-close or the dismiss button with its proper actions, making this not necessary. If for some reason you need a Close Notice action for your project, you can find it below.
// This is the unique ID of the element serving as the alert notice container. SUI.closeNotice( 'unique-id' );
Open Notice
To open a notice, place the folloowing attributes on an element to trigger open notice function:
This attribute will open the alert notice you assign.
<button data-notice-open="unique-id">Show Notice</button>
Use this attribute to include the message you would like to display in the notice. Remember it must be properly wrapped with its tag.
<button data-notice-message="<p>Hello, I am a notification.</p>">Show Notice</button>
If you want to overwrite the default (information) icon, use the following attribute. Have in mind you need to add the name of the icon without its prefix sui-icon-.
The "loader" icon will also add sui-loading state to the icon.
<button data-notice-icon="wordpress">Show Notice</button>
NOTE: If you need the loader icon to spin, don't worry. That sui-loading class for spinner/loading state will be included automatically when you use loader icon.
This attribute will allow you to enable the dimiss button on notifications and will disable the auto-close option.
<button data-notice-dismiss="true">Show Notice</button>
When the dismiss button is enabled, you will be able to overwrite the dismiss button label and add a tooltip to it with the following attributes.
<button data-notice-dismiss="true" data-notice-dismiss-label="Dismiss Label">Show Notice</button> <button data-notice-dismiss="true" data-notice-dismiss-tooltip="Dismiss Tooltip">Show Notice</button>
Notices without a dismiss button enabled will be auto-closed, but you can disable this option if you want to, even when it's not recommended. This attribute accepts a boolean (true / false) value.
<button data-notice-autoclose="false">Show Notice</button>
When auto-close is enabled for notifications, you can overwrite its timeout property for the notice to take more or less time to vanish. The timeout value needs to be entered in milliseconds.
<button data-notice-autoclose="true" data-notice-autoclose-timeout="5000" >Show Notice</button>
Close Notice
Even when there's no need to close a notification with an external element, you can still do it with the attribute below.
<button data-notice-close="unique-id">Close Notice</button>