Z-index

Z-index utilities change the stacking order of positioned elements: z-n1 sends an element behind its context, z-0 creates a base layer and z-1, z-2 and z-3 bring elements forward. They only apply to elements with a position, so pair them with position-relative or position-absolute.

1Z-index scale

z-n1, z-0, z-1, z-2 and z-3 stack positioned elements from back to front.

z-3

z-2

z-1

z-0

z-n1

<div class="position-relative" style="height:170px">
  <div class="position-absolute rounded-3 p-2 small fw-semibold border bg-body-secondary z-3" style="top:0;left:0;width:150px;height:90px">
    z-3
  </div>
  <div class="position-absolute rounded-3 p-2 small fw-semibold border bg-primary-subtle z-2" style="top:20px;left:40px;width:150px;height:90px">
    z-2
  </div>
  <div class="position-absolute rounded-3 p-2 small fw-semibold border bg-success-subtle z-1" style="top:40px;left:80px;width:150px;height:90px">
    z-1
  </div>
  <div class="position-absolute rounded-3 p-2 small fw-semibold border bg-warning-subtle z-0" style="top:60px;left:120px;width:150px;height:90px">
    z-0
  </div>
  <div class="position-absolute rounded-3 p-2 small fw-semibold border bg-danger-subtle z-n1" style="top:80px;left:160px;width:150px;height:90px">
    z-n1
  </div>
</div>

2Order without z-index

Without z-index, later elements paint on top of earlier ones.

first

second (on top)

<div class="position-relative" style="height:130px">
  <div class="position-absolute rounded-3 p-2 small fw-semibold border bg-primary-subtle" style="top:0;left:0;width:160px;height:90px">
    first
  </div>
  <div class="position-absolute rounded-3 p-2 small fw-semibold border bg-info-subtle" style="top:30px;left:60px;width:160px;height:90px">
    second (on top)
  </div>
</div>

3Bring the first one forward

z-1 on the first element puts it above its later sibling.

first, z-1

second

<div class="position-relative" style="height:130px">
  <div class="position-absolute rounded-3 p-2 small fw-semibold border bg-primary-subtle z-1" style="top:0;left:0;width:160px;height:90px">
    first, z-1
  </div>
  <div class="position-absolute rounded-3 p-2 small fw-semibold border bg-info-subtle" style="top:30px;left:60px;width:160px;height:90px">
    second
  </div>
</div>

4Background shape behind content

z-n1 places a decorative shape behind the text of its positioned parent, which uses z-0 to form a stacking context.

The new collection has landed

Thousands of shoppers already trust us, and we work hard to keep it that way.

<div class="position-relative z-0 p-4">
  <div class="position-absolute top-0 start-0 bg-primary-subtle rounded-circle z-n1" style="width:120px;height:120px">
  </div>
  <h3 class="h5 fw-semibold">The new collection has landed</h3>
  <p class="small mb-0">Thousands of shoppers already trust us, and we work hard to keep it that way.</p>
</div>

5Overlapping avatars

Decreasing z-index keeps the first avatar on top of the stack.

<div class="d-flex">
  <img src="../assets/img/avatar-6.svg" alt="Liam Nguyen" width="44" height="44" class="rounded-circle border border-2 border-white position-relative z-3"> <img src="../assets/img/avatar-7.svg" alt="Mia Rossi" width="44" height="44" class="rounded-circle border border-2 border-white position-relative z-2" style="margin-left:-14px"> <img src="../assets/img/avatar-8.svg" alt="Diego Brennan" width="44" height="44" class="rounded-circle border border-2 border-white position-relative z-1" style="margin-left:-14px"> <img src="../assets/img/avatar-9.svg" alt="Mateo Lindqvist" width="44" height="44" class="rounded-circle border border-2 border-white position-relative z-0" style="margin-left:-14px"> 
</div>

6Active button above its neighbours

In joined button rows the active one gets z-1 so its border is not hidden.

<div class="d-flex">
  <button type="button" class="btn btn-outline-secondary rounded-0 rounded-start position-relative">Day</button>
  <button type="button" class="btn btn-outline-primary rounded-0 position-relative z-1 active" style="margin-left:-1px" aria-pressed="true">Week</button>
  <button type="button" class="btn btn-outline-secondary rounded-0 rounded-end position-relative" style="margin-left:-1px">Month</button>
</div>

7Badge over a card image

The badge uses z-2 so it stays above an overlay with z-1.

tips

<div class="position-relative rounded-4 overflow-hidden" style="max-width:20rem">
  <img src="https://images.unsplash.com/photo-1573612664822-d7d347da7b80?auto=format&fit=crop&w=1200&h=800&q=70" alt="How to choose the right product" class="w-100 d-block"> 
  <div class="position-absolute top-0 start-0 w-100 h-100 bg-dark bg-opacity-25 z-1">
  </div>
  <span class="position-absolute top-0 start-0 m-2 badge text-bg-warning z-2">tips</span> 
</div>

8Floating label above a chart

A z-3 label stays above grid lines and bars.

Peak 945

<div class="position-relative border rounded-3 p-3" style="height:150px">
  <div class="position-absolute start-0 end-0 border-top z-0" style="top:50px">
  </div>
  <div class="position-absolute start-0 end-0 border-top z-0" style="top:100px">
  </div>
  <div class="d-flex align-items-end gap-2 h-100 position-relative z-1">
    <div class="bg-primary-subtle flex-fill h-50 rounded-top">
    </div>
    <div class="bg-primary flex-fill h-75 rounded-top">
    </div>
    <div class="bg-primary-subtle flex-fill h-25 rounded-top">
    </div>
  </div>
  <span class="position-absolute top-0 start-50 translate-middle-x mt-2 badge text-bg-dark z-3">Peak 945</span> 
</div>

9Sticky header layer

A sticky header with z-2 stays above rows that have their own positioned badges.

Team

Luna Okafor new

Lea Ibrahim

Ravi Varga

Zoe Rossi

Priya Whitaker

<div class="border rounded-3 overflow-auto" style="height:160px">
  <div class="sticky-top z-2 bg-body-secondary px-3 py-2 small fw-semibold">
    Team
  </div>
  <div class="px-3 py-2 border-bottom position-relative">
    Luna Okafor <span class="badge text-bg-success position-relative z-1">new</span>
  </div>
  <div class="px-3 py-2 border-bottom">
    Lea Ibrahim
  </div>
  <div class="px-3 py-2 border-bottom">
    Ravi Varga
  </div>
  <div class="px-3 py-2 border-bottom">
    Zoe Rossi
  </div>
  <div class="px-3 py-2">
    Priya Whitaker
  </div>
</div>

10Cards in a fan

Rotated cards stacked with z-1 to z-3.

z-1

z-2

z-3

<div class="position-relative mx-auto" style="height:170px;max-width:18rem">
  <div class="position-absolute top-50 start-50 bg-body border rounded-3 shadow-sm p-3 z-1" style="width:140px;transform:translate(-80%,-50%) rotate(-10deg)">
    <div class="small">
      <code class="small">z-1</code>
    </div>
  </div>
  <div class="position-absolute top-50 start-50 bg-body border rounded-3 shadow-sm p-3 z-2" style="width:140px;transform:translate(-50%,-50%)">
    <div class="small">
      <code class="small">z-2</code>
    </div>
  </div>
  <div class="position-absolute top-50 start-50 bg-body border rounded-3 shadow-sm p-3 z-3" style="width:140px;transform:translate(-20%,-50%) rotate(10deg)">
    <div class="small fw-bold">
      <code class="small">z-3</code>
    </div>
  </div>
</div>

11Image behind a heading

The hero image sits on z-n1 inside a z-0 context, the text sits on top.

Good things, made to be used

Our team has done this many times, so you never have to guess.

<div class="position-relative z-0 rounded-4 overflow-hidden p-4 text-white bg-dark" style="min-height:180px">
  <img src="https://images.unsplash.com/photo-1521335629791-ce4aec67dd15?auto=format&fit=crop&w=1600&h=700&q=70" alt="" class="position-absolute top-0 start-0 w-100 h-100 object-fit-cover z-n1"> 
  <div class="position-absolute top-0 start-0 w-100 h-100 bg-dark bg-opacity-50 z-n1">
  </div>
  <h3 class="h4 fw-bold">Good things, made to be used</h3>
  <p class="mb-0 small">Our team has done this many times, so you never have to guess.</p>
</div>

12Focus ring over siblings

List group items lift their active item with z-1 so its border shows on both edges.

Home
Apparel
Apparel

<ul class="list-unstyled mb-0" style="max-width:18rem">
  <li class="border px-3 py-2 rounded-top position-relative">Home</li>
  <li class="border border-primary bg-primary-subtle px-3 py-2 position-relative z-1" style="margin-top:-1px">Apparel</li>
  <li class="border px-3 py-2 rounded-bottom position-relative" style="margin-top:-1px">Apparel</li>
</ul>

13Notification over a header

A count badge on z-3 overlaps the next header item.

<div class="d-flex gap-3 border rounded-3 p-3 align-items-center">
  <span class="position-relative fs-4"><i class="bi bi-bell" aria-hidden="true"></i><span class="position-absolute top-0 start-100 translate-middle badge rounded-pill text-bg-danger z-3 fs-6">43</span></span> <span class="position-relative fs-4 bg-body rounded-2 px-2"><i class="bi bi-chat-dots" aria-hidden="true"></i></span> 
</div>

14Stacked paper effect

Two layers on z-n1 behind a card look like a pile of pages.

Beauty

27 documents

<div class="position-relative z-0 mx-auto" style="max-width:20rem">
  <div class="position-absolute top-0 start-0 w-100 h-100 bg-body-secondary border rounded-3 z-n1" style="transform:translate(8px,8px)">
  </div>
  <div class="position-absolute top-0 start-0 w-100 h-100 bg-body-tertiary border rounded-3 z-n1" style="transform:translate(4px,4px)">
  </div>
  <div class="bg-body border rounded-3 p-3">
    <div class="fw-semibold">
      Beauty
    </div>
    <div class="small text-body-secondary">
      27 documents
    </div>
  </div>
</div>

15Overlapping sections

A card with z-1 overlaps the coloured band above it via a negative top offset.

Quality goods delivered to your door

We measure success by how many shoppers come back and tell their friends.

<div>
  <div class="text-bg-primary rounded-top-4 p-4 pb-5">
    <h3 class="h5 mb-0">Quality goods delivered to your door</h3>
  </div>
  <div class="position-relative z-1 bg-body border rounded-4 shadow-sm p-3 mx-3" style="margin-top:-2rem">
    We measure success by how many shoppers come back and tell their friends.
  </div>
</div>

16Corner ribbon above a border

A z-2 ribbon overlaps the card border.

Shipped

Free shipping

Gift wrapping and a handwritten note are free on every order.

<div class="position-relative border border-2 rounded-4 p-4" style="max-width:18rem">
  <span class="position-absolute top-0 end-0 translate-middle-y me-3 badge text-bg-success z-2">Shipped</span> 
  <div class="fw-semibold">
    Free shipping
  </div>
  <div class="small text-body-secondary">
    Gift wrapping and a handwritten note are free on every order.
  </div>
</div>

17Hover card layer (static preview)

A preview popover on z-3 overlapping a list.

Aria Novak
Isla Delgado
Kai Moreau

Members get early access to new drops and prices only they can see.

<div class="position-relative" style="height:150px">
  <ul class="list-unstyled border rounded-3 mb-0">
    <li class="px-3 py-2 border-bottom">Aria Novak</li>
    <li class="px-3 py-2 border-bottom">Isla Delgado</li>
    <li class="px-3 py-2">Kai Moreau</li>
  </ul>
  <div class="position-absolute bg-body border rounded-3 shadow p-3 z-3 small" style="top:20px;left:40%;width:13rem">
    Members get early access to new drops and prices only they can see.
  </div>
</div>

18Z-index needs a position

z-* only works on positioned elements: the left box has no position, the right one has position-relative.

z-3, static (ignored)

z-3, position-relative

<div class="row g-2">
  <div class="col-6">
    <div class="bg-info-subtle border rounded-3 p-3 z-3 small">
      z-3, static (ignored)
    </div>
  </div>
  <div class="col-6">
    <div class="bg-info-subtle border rounded-3 p-3 z-3 position-relative small">
      z-3, position-relative
    </div>
  </div>
</div>

19Price tag over a product

A z-1 price tag over the product image and a z-2 heart button above it.

$30.34

<div class="position-relative rounded-4 overflow-hidden border" style="max-width:16rem">
  <img src="../assets/img/product-11.svg" alt="Hand cream" class="w-100 d-block"> <span class="position-absolute bottom-0 start-0 m-2 badge text-bg-dark z-1">$30.34</span> 
  <button type="button" class="btn btn-light btn-sm rounded-circle position-absolute top-0 end-0 m-2 z-2" aria-label="Save"><i class="bi bi-heart" aria-hidden="true"></i></button>
</div>

20Dropdown above content

An open menu at z-3 overlaps the panel below it.

Newest
Price low to high
Rating

We keep things simple, so you can focus on what matters to you. We work directly with makers, so prices stay fair for everyone.

<div class="position-relative" style="height:170px">
  <button type="button" class="btn btn-sm btn-outline-secondary"><i class="bi bi-sort-down" aria-hidden="true"></i> Sort</button>
  <ul class="position-absolute list-unstyled bg-body border rounded-3 shadow py-1 mt-1 z-3 small mb-0" style="width:11rem">
    <li class="px-3 py-1">Newest</li>
    <li class="px-3 py-1 bg-primary-subtle">Price low to high</li>
    <li class="px-3 py-1">Rating</li>
  </ul>
  <div class="bg-body-tertiary border rounded-3 p-3 mt-2 small">
    We keep things simple, so you can focus on what matters to you. We work directly with makers, so prices stay fair for everyone.
  </div>
</div>