Bootstrap - Understanding Z-Index Utilities in Bootstrap (.z-*)

Introduction

When designing complex web layouts, it’s common for multiple elements to overlap — such as modals, dropdowns, tooltips, or navigation bars. Controlling which element appears on top or below others is managed using the CSS z-index property.

Bootstrap simplifies this process by offering Z-index utility classes (.z-*), allowing developers to easily adjust the stacking order of elements without writing custom CSS.

These utilities help maintain consistent layering and ensure that interactive components like dropdowns or modals appear properly above other page elements.

1. What Is Z-Index?

The z-index is a CSS property that controls the stacking order of elements along the z-axis (the axis that represents depth).

In simple terms:

  • Elements with a higher z-index value appear in front of elements with lower values.

  • Elements with the same z-index follow the HTML document order (the one that comes later appears on top).

Basic Example (CSS Concept):

.box1 {
  position: relative;
  z-index: 10;
}
.box2 {
  position: relative;
  z-index: 5;
}

Here, .box1 will appear above .box2 because it has a higher z-index.

2. Z-Index in Bootstrap

Bootstrap uses z-index values internally to layer components correctly — for example:

  • Modals appear above everything else.

  • Dropdown menus appear above buttons.

  • Tooltips appear above dropdowns.

To give developers control over stacking order, Bootstrap provides Z-index utility classes that directly apply these values through .z-* classes.

3. Basic Z-Index Utility Classes

Bootstrap 5+ includes several predefined .z-* classes for quickly setting stacking context.

Class CSS Equivalent Description
.z-n1 z-index: -1; Places element behind normal content
.z-0 z-index: 0; Sets neutral stacking level
.z-1 z-index: 1; Slightly above base level
.z-2 z-index: 2; Higher stacking level
.z-3 z-index: 3; Top-most among basic layers

These utilities are part of Bootstrap’s position utilities, and they only work on positioned elements (those with position: relative, absolute, fixed, or sticky).

4. Example: Using .z-* Classes

Example 1: Overlapping Boxes

<div class="position-relative">
  <div class="position-absolute top-0 start-0 bg-primary text-white p-3 z-1">Box 1 (z-1)</div>
  <div class="position-absolute top-2 start-2 bg-danger text-white p-3 z-3">Box 2 (z-3)</div>
</div>

Explanation:

  • Both boxes are absolutely positioned within the same container.

  • .z-3 ensures the red box appears above the blue one.

Example 2: Sending Elements Behind Content

<div class="position-relative bg-light p-5">
  <div class="position-absolute top-0 start-0 bg-warning p-4 z-n1">
    Behind Content
  </div>
  <p>This paragraph appears above the yellow box because of z-index layering.</p>
</div>

Here, .z-n1 pushes the yellow box behind the text content.

5. How Bootstrap’s Z-Index Utilities Work

Under the hood, Bootstrap defines these utilities in its SCSS files as:

.z-n1 { z-index: -1 !important; }
.z-0  { z-index: 0 !important; }
.z-1  { z-index: 1 !important; }
.z-2  { z-index: 2 !important; }
.z-3  { z-index: 3 !important; }

The use of !important ensures these utilities override other conflicting z-index values in your custom CSS.

6. Positioning Requirement

Z-index values only work when the element has a positioning context, meaning the position property must be something other than static (the default).

Valid positioning values include:

  • relative

  • absolute

  • fixed

  • sticky

Example (Incorrect use):

<div class="z-3 bg-primary">This won't layer properly.</div>

This won’t have any visual effect because the element has no defined position.

Correct version:

<div class="position-relative z-3 bg-primary">This will appear above others.</div>

7. Practical Applications

a. Managing Overlaps

When multiple UI elements overlap—like images, cards, or banners—.z-* classes help control which one appears on top.

b. Tooltips and Popovers

Sometimes tooltips or popovers might get hidden behind other components. Assigning .z-3 ensures they appear correctly in front.

c. Sticky Navigation Bars

Use .z-3 on sticky headers to ensure they stay visible above scrolling content.

d. Background Decorations

Elements with .z-n1 are perfect for background shapes or design elements that should remain behind text or images.

8. Real-World Example: Sticky Header with Background Layer

<header class="position-sticky top-0 z-3 bg-dark text-white p-3">
  Fixed Header
</header>

<div class="position-relative z-n1">
  <img src="background.jpg" class="w-100" alt="Background image">
</div>

<main class="p-5">
  <p>Scroll through the content and notice how the header stays on top.</p>
</main>

Here:

  • The header uses .z-3 to stay on top.

  • The background image uses .z-n1 to remain behind everything.

9. Customizing Z-Index Values in Bootstrap

Developers using Sass (SCSS) can customize or extend Bootstrap’s z-index utilities.

In the _variables.scss file, Bootstrap defines its z-index scale:

$zindex-dropdown: 1000;
$zindex-sticky: 1020;
$zindex-fixed: 1030;
$zindex-modal-backdrop: 1040;
$zindex-modal: 1050;
$zindex-popover: 1060;
$zindex-tooltip: 1070;

If you want to add more granular control, you can define your own z-index map like this:

$utilities: (
  "z-index": (
    property: z-index,
    class: z,
    values: (-1, 0, 1, 2, 3, 10, 50, 100)
  )
);

This customization allows you to use classes like .z-10 or .z-100 directly in your HTML.

10. Best Practices

  • Always use .z-* on positioned elements only.

  • Avoid using extremely high z-index values unnecessarily—it can cause layering conflicts.

  • Maintain a logical layering system in your design (e.g., headers > content > background).

  • Use negative z-index (.z-n1) carefully; it can make elements unclickable if they go behind the page background.

  • For complex layouts (like modals and dropdowns), rely on Bootstrap’s built-in z-index hierarchy.

11. Bootstrap’s Built-In Z-Index Hierarchy

Bootstrap’s components are layered intentionally with increasing z-index values:

Component Z-index value
Dropdown 1000
Sticky 1020
Fixed 1030
Modal Backdrop 1040
Modal 1050
Popover 1060
Tooltip 1070

Understanding this helps you avoid conflicts when layering custom elements.

Conclusion

Bootstrap’s Z-index utilities (.z-*) provide a simple and powerful way to control how elements stack visually on a webpage.

By combining these classes with positioning utilities, developers can manage overlapping content, fix layering issues, and ensure that interactive components like modals, popovers, and tooltips display correctly.

Whether you need to bring elements to the front, send them behind, or fine-tune your layout, the .z-* utilities make it quick, consistent, and CSS-free — keeping your code clean and responsive.