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="relative" style="height:170px">
  <div class="absolute rounded-lg p-2 small font-semibold border bg-surface-2 z-3" style="top:0;left:0;width:150px;height:90px">
    z-3
  </div>
  <div class="absolute rounded-lg p-2 small font-semibold border bg-primary-subtle z-2" style="top:20px;left:40px;width:150px;height:90px">
    z-2
  </div>
  <div class="absolute rounded-lg p-2 small font-semibold border bg-success-subtle z-1" style="top:40px;left:80px;width:150px;height:90px">
    z-1
  </div>
  <div class="absolute rounded-lg p-2 small font-semibold border bg-warning-subtle z-0" style="top:60px;left:120px;width:150px;height:90px">
    z-0
  </div>
  <div class="absolute rounded-lg p-2 small font-semibold border bg-danger-subtle -z-1" 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="relative" style="height:130px">
  <div class="absolute rounded-lg p-2 small font-semibold border bg-primary-subtle" style="top:0;left:0;width:160px;height:90px">
    first
  </div>
  <div class="absolute rounded-lg p-2 small font-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="relative" style="height:130px">
  <div class="absolute rounded-lg p-2 small font-semibold border bg-primary-subtle z-1" style="top:0;left:0;width:160px;height:90px">
    first, z-1
  </div>
  <div class="absolute rounded-lg p-2 small font-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.

Quality goods delivered to your door

Thousands of five-star reviews from customers who came back for more.

<div class="relative z-0 p-6">
  <div class="absolute top-0 start-0 bg-primary-subtle rounded-full -z-1" style="width:120px;height:120px">
  </div>
  <h3 class="h5 font-semibold">Quality goods delivered to your door</h3>
  <p class="small mb-0">Thousands of five-star reviews from customers who came back for more.</p>
</div>

5Overlapping avatars

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

<div class="flex">
  <img src="../assets/img/avatar-6.svg" alt="Zoe Fischer" width="44" height="44" class="rounded-full border border-2 border-white relative z-3"> <img src="../assets/img/avatar-7.svg" alt="Nora Ashford" width="44" height="44" class="rounded-full border border-2 border-white relative z-2" style="margin-left:-14px"> <img src="../assets/img/avatar-8.svg" alt="Theo Kowalski" width="44" height="44" class="rounded-full border border-2 border-white relative z-1" style="margin-left:-14px"> <img src="../assets/img/avatar-9.svg" alt="Maya Varga" width="44" height="44" class="rounded-full border border-2 border-white 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="flex">
  <button type="button" class="btn btn-outline-secondary rounded-none rounded-s-md relative">Day</button>
  <button type="button" class="btn btn-outline-primary rounded-none relative z-1 active" style="margin-left:-1px" aria-pressed="true">Week</button>
  <button type="button" class="btn btn-outline-secondary rounded-none rounded-e-md 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.

tutorial

<div class="relative rounded-xl overflow-hidden" style="max-width:20rem">
  <img src="https://images.unsplash.com/photo-1718985342149-7178154e0aee?auto=format&fit=crop&w=1200&h=800&q=70" alt="Our favourite tips for busy weeks" class="w-full block"> 
  <div class="absolute top-0 start-0 w-full h-full bg-dark/25 z-1">
  </div>
  <span class="absolute top-0 start-0 m-2 badge text-bg-warning z-2">tutorial</span> 
</div>

8Floating label above a chart

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

Peak 931

<div class="relative border rounded-lg p-4" style="height:150px">
  <div class="absolute start-0 end-0 border-t z-0" style="top:50px">
  </div>
  <div class="absolute start-0 end-0 border-t z-0" style="top:100px">
  </div>
  <div class="flex items-end gap-2 h-full relative z-1">
    <div class="bg-primary-subtle flex-auto h-1/2 rounded-t-md">
    </div>
    <div class="bg-primary flex-auto h-3/4 rounded-t-md">
    </div>
    <div class="bg-primary-subtle flex-auto h-1/4 rounded-t-md">
    </div>
  </div>
  <span class="absolute top-0 start-1/2 -translate-x-1/2 mt-2 badge text-bg-dark z-3">Peak 931</span> 
</div>

9Sticky header layer

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

Team

Sofia Novak new

Finn Nguyen

Omar Sato

Arjun Harlow

Liam Quinn

<div class="border rounded-lg overflow-auto" style="height:160px">
  <div class="sticky-top z-2 bg-surface-2 px-4 py-2 small font-semibold">
    Team
  </div>
  <div class="px-4 py-2 border-b relative">
    Sofia Novak <span class="badge text-bg-success relative z-1">new</span>
  </div>
  <div class="px-4 py-2 border-b">
    Finn Nguyen
  </div>
  <div class="px-4 py-2 border-b">
    Omar Sato
  </div>
  <div class="px-4 py-2 border-b">
    Arjun Harlow
  </div>
  <div class="px-4 py-2">
    Liam Quinn
  </div>
</div>

10Cards in a fan

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

z-1

z-2

z-3

<div class="relative mx-auto" style="height:170px;max-width:18rem">
  <div class="absolute top-1/2 start-1/2 bg-page border rounded-lg shadow-sm p-4 z-1" style="width:140px;transform:translate(-80%,-50%) rotate(-10deg)">
    <div class="small">
      <code class="small">z-1</code>
    </div>
  </div>
  <div class="absolute top-1/2 start-1/2 bg-page border rounded-lg shadow-sm p-4 z-2" style="width:140px;transform:translate(-50%,-50%)">
    <div class="small">
      <code class="small">z-2</code>
    </div>
  </div>
  <div class="absolute top-1/2 start-1/2 bg-page border rounded-lg shadow-sm p-4 z-3" style="width:140px;transform:translate(-20%,-50%) rotate(10deg)">
    <div class="small font-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.

Everyday essentials, beautifully made

Free shipping on orders over $50 and easy returns within 30 days.

<div class="relative z-0 rounded-xl overflow-hidden p-6 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="absolute top-0 start-0 w-full h-full object-cover -z-1"> 
  <div class="absolute top-0 start-0 w-full h-full bg-dark/50 -z-1">
  </div>
  <h3 class="h4 font-bold">Everyday essentials, beautifully made</h3>
  <p class="mb-0 small">Free shipping on orders over $50 and easy returns within 30 days.</p>
</div>

12Focus ring over siblings

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

Home
Accessories
Home

<ul class="list-unstyled mb-0" style="max-width:18rem">
  <li class="border px-4 py-2 rounded-t-md relative">Home</li>
  <li class="border border-primary bg-primary-subtle px-4 py-2 relative z-1" style="margin-top:-1px">Accessories</li>
  <li class="border px-4 py-2 rounded-b-md relative" style="margin-top:-1px">Home</li>
</ul>

13Notification over a header

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

<div class="flex gap-4 border rounded-lg p-4 items-center">
  <span class="relative text-xl"><i class="bi bi-bell-fill" aria-hidden="true"></i><span class="absolute top-0 start-full -translate-x-1/2 -translate-y-1/2 badge rounded-full text-bg-danger z-3 text-base">29</span></span> <span class="relative text-xl bg-page rounded-md px-2"><i class="bi bi-chat-dots-fill" aria-hidden="true"></i></span> 
</div>

14Stacked paper effect

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

Apparel

14 documents

<div class="relative z-0 mx-auto" style="max-width:20rem">
  <div class="absolute top-0 start-0 w-full h-full bg-surface-2 border rounded-lg -z-1" style="transform:translate(8px,8px)">
  </div>
  <div class="absolute top-0 start-0 w-full h-full bg-surface-3 border rounded-lg -z-1" style="transform:translate(4px,4px)">
  </div>
  <div class="bg-page border rounded-lg p-4">
    <div class="font-semibold">
      Apparel
    </div>
    <div class="small text-muted">
      14 documents
    </div>
  </div>
</div>

15Overlapping sections

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

Small batches, big on quality

Friendly people answer your questions quickly, by phone, chat or email.

<div>
  <div class="text-bg-primary rounded-t-xl p-6 pb-12">
    <h3 class="h5 mb-0">Small batches, big on quality</h3>
  </div>
  <div class="relative z-1 bg-page border rounded-xl shadow-sm p-4 mx-4" style="margin-top:-2rem">
    Friendly people answer your questions quickly, by phone, chat or email.
  </div>
</div>

16Corner ribbon above a border

A z-2 ribbon overlaps the card border.

Draft

Live order tracking

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

<div class="relative border border-2 rounded-xl p-6" style="max-width:18rem">
  <span class="absolute top-0 end-0 -translate-y-1/2 me-4 badge text-bg-success z-2">Draft</span> 
  <div class="font-semibold">
    Live order tracking
  </div>
  <div class="small text-muted">
    Our team has done this many times, so you never have to guess.
  </div>
</div>

17Hover card layer (static preview)

A preview popover on z-3 overlapping a list.

Owen Delgado
Freya Hughes
Samir Tanaka

We keep things simple, so you can focus on what matters to you.

<div class="relative" style="height:150px">
  <ul class="list-unstyled border rounded-lg mb-0">
    <li class="px-4 py-2 border-b">Owen Delgado</li>
    <li class="px-4 py-2 border-b">Freya Hughes</li>
    <li class="px-4 py-2">Samir Tanaka</li>
  </ul>
  <div class="absolute bg-page border rounded-lg shadow-md p-4 z-3 small" style="top:20px;left:40%;width:13rem">
    We keep things simple, so you can focus on what matters to you.
  </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-lg p-4 z-3 small">
      z-3, static (ignored)
    </div>
  </div>
  <div class="col-6">
    <div class="bg-info-subtle border rounded-lg p-4 z-3 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.

$51.32

<div class="relative rounded-xl overflow-hidden border" style="max-width:16rem">
  <img src="../assets/img/product-11.svg" alt="Hand cream" class="w-full block"> <span class="absolute bottom-0 start-0 m-2 badge text-bg-dark z-1">$51.32</span> 
  <button type="button" class="btn btn-light btn-sm rounded-full absolute top-0 end-0 m-2 z-2" aria-label="Save"><i class="bi bi-heart-fill" 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

Start in minutes and get help from a real person whenever you need it. We measure success by how many shoppers come back and tell their friends.

<div class="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="absolute list-unstyled bg-page border rounded-lg shadow-md py-1 mt-1 z-3 small mb-0" style="width:11rem">
    <li class="px-4 py-1">Newest</li>
    <li class="px-4 py-1 bg-primary-subtle">Price low to high</li>
    <li class="px-4 py-1">Rating</li>
  </ul>
  <div class="bg-surface-3 border rounded-lg p-4 mt-2 small">
    Start in minutes and get help from a real person whenever you need it. We measure success by how many shoppers come back and tell their friends.
  </div>
</div>