Notifications

Display configurable notifications and alerts of different types.

Never before has it been so easy to add an unlimited number of custom notifications or alerts to your help center. With the Notifications plugin you have unprecedented control over how your notification look, where they are displayed and what content they contain.

This extension compliments the built-in notification feature available in all of our themes, which is configurable using theme settings.

Standard notification styles

The example below demonstrates the four default styles available through the extension: error, warning, success and tip.

Notification styles

The content of your notifications can be provided as static text, localized dynamic Content or content from articles with specific labels. Regardless of which approach is taken, the content can contain HTML elements (like links).

Dismissible notifications

You can optionally make your notifications dismissible.

Dismissible notifications

Dismissed notification remain hidden for the duration of the browser session, until you close your browser.

Like all of our other extensions, you can also use custom micro-templates to make your notifications look and behave however you like.

Installation

The Notifications extension is included for free in all of our themes and can be found in the theme’s Assets folder. To begin using the extension, add a reference to it in your theme’s footer.hbs template:

<script type="text/javascript" src="{{asset 'extension-notifications.min.js'}}" defer></script>

Creating notifications

To create notifications you must either:

  • Define the notification content using the content option, which can be static text or dynamic content if you need to support multiple languages; or

  • Identify articles to convert into notifications using the labels option, which is a comma-separated list of article labels. The extension will convert each article matching one or more of the labels you provide into a notification, using the article content as the notification content.

Use data-element="notification" on an element to create a new notification.

<div data-element="notification" data-type="success" data-content="This is the notification message"></div>
<div data-element="notification" data-type="error" data-labels="notification_error"></div>

If data attributes are used you will need to ensure that the allow unsafe HTML setting is enabled within Zendesk Guide.

The Notification extension can be initialized using JavaScript:

<div id="notification">...</div>

<script type="text/javascript">
  document.addEventListener('DOMContentLoaded', () => {
    new Notification(document.getElementById('notification'), {
      // Options go here
    });
  });
</script>

User-specific notifications

Using JavaScript you can show notifications to specific subsets of users that visit your Help Center. For example, to show a success notification to users with a tag of special_user, you could use the following code:

{{#if signed_in}}
  <div id="notification"></div>

  <script type="text/javascript">
    document.addEventListener('DOMContentLoaded', () => {
      fetch('/api/v2/users/me.json')
          .then(function(response) { return response.json(); })
          .then(function(json) {
            var user = json.user;
            if (user.tags.indexOf('special_user') !== -1) {
              new Notification(document.getElementById('notification'), {
                content: 'This is a notification that only some users can see.',
                type: 'success',
                // Other options go here
              });
            }
          });
    });
  </script>
{{/if}}

Any other user property could be used as a condition, like the user’s role or organization membership. To learn more about the user properties returned by the Zendesk REST API, refer to the Users endpoint documentation.

Options

Options can be passed via data attributes or JavaScript.

For data attributes, append the option name to data- and use kebab case instead of camel case.

Name Type Default Description
id string null The ID of the notification (required if the notification is dismissible).
content string '' The content to display within your notification.
labels string '' A comma-separated list of labels used to identify articles.
type string 'error' The type of notification to use (error, warning, success or tip).
dismissible boolean false True if the notifications should be dismissible.
template string
null
null The name of the template to use.
templateData object {} Additional data to expose to the templating function.

Custom micro-templates

Using custom micro-templates you can customize the appearance and behavior of the notifications and even present other data within them like the article title. The template itself will receive one or more notification objects. Each notification object has the following properties:

  • notifications which is an array of notification objects, each with the following properties:
    • url (only populated if articles are used)
    • title (only populated if articles are used)
    • body
    • body_plain
    • type
  • dismissible
<% notifications.forEach(function(notification, index) { %>
  <% if (notification.type === "error") { %>
    <div class="notification <%= notification.type %>"<% if (dismissible && notification.id) { %> data-notification-id="<%= notification.id %>"<%} %>>
      <% if (notification.title) { %>
        <h3><%= notification.title %></h3>
      <% } %>
      <%= notification.body %>
    </div>
  <% } %>
  <% if (notification.type === "warning") { %>...<% } %>
  <% if (notification.type === "success") { %>...<% } %>
  <% if (notification.type === "tip") { %>...<% } %>
<% }) %>

Events

Class Properties
notification:render Fires when the notification has been rendered.

Related extensions

Animations and transitions Free

Animations and transitions

Add engaging animation and transition effects to elements.

Carousels Free

Carousels

Present content in well-defined and easy to follow steps.

Content blocks and icons Free

Content blocks and icons

Display icons against categories, sections and articles.