Managing dynamic z-index in component-based UI architecture

This article is a response to an article published in Smashing Magazine recently that discusses the difficulties of managing z-index in a complex UI application. (The article’s author responded in a comment by saying “Huy’s approach nicely extends mine: making z-index dynamic can help in more complex scenarios. Thanks for sharing!“) Practically speaking, z-index determines the “stacking order” of a DOM element i.e. whether one element appears above another when their spatial extents overlap. Despite this fairly straightforward functionality, z-index can be tricky to work with in practice.

One example that I frequently encounter while developing interactive graphs and charts is that of adjacent interactive DOM elements that have mutually overlapping hover tooltips. For example, a graph that provides a hover tooltip for every data point can appear next to a legend that also has its own hover tooltip and we want either hover tooltip to be fully visible when they are shown.

Below is a live demonstration (with the code here).¹ The viewport is divided into 3 adjacent areas, labeled A, B and C and with different background-colors. They each should respond to hover interactions by increasing their background-color’s opacity and showing a tooltip that points toward their centers.

Here’s the problem. Because the z-index of the sibling areas are ascendingly ordered A, B to C, only C’s tooltip is unobstructed visually by the others because it has the highest z-index: whereas B’s tooltip appears below C but above A:

This demo highlights how z-index can be tricky to managed in an interactive, complex UI application:

• z-index only takes effect among siblings within the same stacking context. The implication is that if you are working on the area A, you must ensure that all sibling elements (B and C) that might visually intersect with A be included in the same stacking context. Practically, this requires making sure all sibling elements are relatively positioned and are assigned their own z-index value. These values should also be grouped together in a single place to avoid conflicts and “z-index wars” and to ensure the right order between these siblings. The demo’s implementation follows both suggestions.
• z-index is hierarchical i.e. an element’s children inherits the stacking order of its parent. If you want A’s tooltip to be unobstructed by B, you need to assign A a higher z-index value than that of B. Regardless of how large the z-index value of A’s tooltip is, if the z-index of A is less than that of B, A’s tooltip will be obstructed by B or B’s descendants. The implication is that if you’re working on A’s hover tooltips, you might have to manage the z-indexes of UI components (A, B and C) several levels above. The demo’s implementation doesn’t take this into account.
• z-index sometimes needs to be dynamic if sibling elements or their descendants could mutually obstruct each other visually. In the above demo, A’s and B’s tooltips will always appear behind at least one other area. The demo’s implementation also doesn’t take this into account.

Below is my solution in the context of an application that uses React, CSS-in-JS (emotion in this case but should apply equally well to other libraries such as styled-components) and TypeScript.² The general idea is that when the mouse enters each area, it “promotes” itself i.e. increases its own z-index relative to the other siblings in order for its hover tooltip to not be obstructed by them. You can play with the solution below:

The main part of the solution is a custom React hook (code here), called usePromotableZIndex here, that takes in:

• The regular z-index order.
• The value of the “promoted” z-index i.e. what z-index a DOM element should have if it’s promoted.

The hook returns three callbacks:

• getZIndex returns what z-index a sibling should have, taking into account promotion.
• promoteZIndex allows each sibling to promote its z-index.
• restoreZIndex allows each element to restore its regular z-index.

This is an example of how the hook is used in the solution. The parent is the App component. Within App, the variable zIndices holds the regular z-index order for the siblings named A, B and C. Each sibling (the Partition component) binds its name to the callbacks exposed by the usePromotableZIndex hook.

1// https://github.com/huy-nguyen/z-index-management/blob/problem-simple-solution/src/App.tsx
2const App = () => {
3  const zIndices = {
4    A: 10,
5    B: 20,
6    C: 30,
7  }
8  const {getZIndex, promoteZIndex, restoreZIndex} = usePromotableZIndex({
9    normalZIndices: zIndices,
10    promotedZIndex: 100,
11  })
12  return (
13    <Root>
14      <Partition
15        getZIndex={() => getZIndex('A')}
16        promoteZIndex={() => promoteZIndex('A')}
17        restoreZIndex={restoreZIndex}
18      />
19      <Partition
20        getZIndex={() => getZIndex('B')}
21        promoteZIndex={() => promoteZIndex('B')}
22        restoreZIndex={restoreZIndex}
23      />
24      <Partition
25        getZIndex={() => getZIndex('C')}
26        promoteZIndex={() => promoteZIndex('C')}
27        restoreZIndex={restoreZIndex}
28      />
29    </Root>
30  );
31}

Within each sibling’s implementation, they commit to querying the getZIndex callback to get their assigned z-index. In return for following that contract, they can call promoteZIndex just before showing the hover tooltip and restoreZIndex after hiding the tooltip. By following this contract, all siblings live harmoniously together z-index-wise.

1// https://github.com/huy-nguyen/z-index-management/blob/problem-simple-solution/src/Partition.tsx
2const Partition = (props: Props) => {
3  const [isTooltipShown, setIsTooltipShown] = useState<boolean>(false);
4  const onMouseEnter = () => {
5    promoteZIndex();
6    setIsTooltipShown(true);
7  }
8  const onMouseLeave = () => {
9    setIsTooltipShown(false);
10    restoreZIndex();
11  }
12  return (
13    <Root
14      css={css`
15        background-color: ${color};
16        grid-area: ${gridArea};
17        z-index: ${getZIndex()};
18      `}
19      onMouseEnter={onMouseEnter}
20      onMouseLeave={onMouseLeave}
21    >
22      {tooltip}
23      {label}
24    </Root>
25  )
26}

The advantages of this approach are:

• TypeScript’s type checking ensures that the getZIndex and promoteZIndex can only be called with valid sibling names. TypeScript’s autocomplete also provides suggestions of valid sibling names as shown in this screenshot:
• Only the hook has access to the actual z-index values, acting as a gatekeeper to encourage adherence to the z-index promotion contract.
• The z-index promotion behavior is entirely contained within a hook, making it re-usable across all levels of the component tree.
• The three callbacks can be passed arbitrarily deep down a component tree, allowing any descendant to control the z-index of the ancestor it needs in order to display itself correctly.