Using z-index in the Web Widget (Classic)

Overview

Zendesk Web Widget (Classic) comes with many settings and customization options. Sometimes you will need to specify the stack order of the Web Widget (Classic) in relation to the other content on your webpage. You can do this by setting the z-index value in the Web Widget (Classic) settings.

This article highlights some basic cases of z-indexto change how your widget is arranged with other elements on your website.

Disclaimer: This article is provided for instructional purposes only. Zendesk does not support or guarantee the code. Post any issues you have in the comments section or try searching for a solution online.

What is z-index?

Z-index is a CSS property that is used to set the visibility and the positioning of overlapping content. When two elements overlap, the z-index determines which element appears on top of the other. The z-index value can be assigned with an integer or global values such as inherit, initial and unset.

When using integers, the element’s z-index assigned to the highest index will appear in front of other elements. For example, if container A is assigned a z-index of 2 and container B is assigned a z-index of 1, container A is positioned in front of container B. When using global values, the element will take the assigned position in relation to its parent’s value.

How does z-index relate to the Web Widget (Classic)?

You can the z-index of the Web Widget (Classic)to display your content in front of the Web Widget (Classic), or to hide the Web Widget (Classic) behind other content entirely.

How do I set the z-index for my Web Widget (Classic)?

You can set the z-index for your widget in two ways:

1. Use the window.zESettings object. This will set the z-index when the widget is first loaded. For more info on using the window.zESettings object, see the developer documentation: Settings reference.
2. Use the updateSettings API. This will allow the z-index to be updated at run-time. For more info on using the updateSettings API, see the developer documentation: Core API.

Note: The Web Widget (Classic) z-index setting defaults to an index of 999998 which means the widget will appear at the front of the screen unless another object’s z-index exceeds that number.

Example using the window.zESettings object

The window.zESettings object lets you set the z-index on page load.

This example sets the z-index using the window.zESettings object. As a reminder, the window.zESettings object is loaded only when the widget boots. To update the z-index value at run-time using the updateSettings API, see the examples further below.

Here is how the page will look prior to any changes to the z-index value of the Web Widget (Classic). As expected, the Web Widget (Classic) appears on top of our other content:

In the example above, the z-index of the container element has not been explicitly set. That means the z-index of the container element will default to auto, which corresponds to 0. To hide the Web Widget (Classic), set the z-index value lower than 0 as shown here:

Now, when the page is loaded the Web Widget (Classic) appear sbehind the container element. This is because the z-index value of the container element is higher than the z-index value of the Web Widget (Classic).

The new z-index value causes the Web Widget (Classic) to appear behind the other elements of the webpage.

Examples using the updateSettings API

The updateSettings API gives you flexibility to make changes in real time

These examples show you that the modal was given a z-index of 2. Only change the z-index of the widget to either hide or bring it to the front of the screen.

Example 1: Hiding the Web Widget (Classic) behind the modal

In the first example, to hide the Web Widget (Classic) behind the modal, set the widget's z-index to 1 as seen below.

See it in action:

Example 2: Bring the Web Widget (Classic) to the front of the modal

This example shows you how to make the Web Widget (Classic) show in front of the modal so that it is still accessible on the page. This example uses once again zE webWidget to updateSettings and set the z-index to 3. This will effectively move the position of the Web Widget (Classic).

See it in action:

Summary and additional resources

As a web developer you can choose the best method to set the z-index value of your Web Widget (Classic). The window.zESettings object gives you the ability to set the z-index on page load, whereas the updateSettings API gives you the flexibility to make changes in real time. For more information on customizing your widget, see this article: Advanced customization of Web Widget (Classic).