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.

Simple dishes, honest ingredients

We listen first, then build a plan around what you actually need.

<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">Simple dishes, honest ingredients</h3>
  <p class="small mb-0">We listen first, then build a plan around what you actually need.</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="Felix Ortega" width="44" height="44" class="rounded-full border border-2 border-white relative z-3"> <img src="../assets/img/avatar-7.svg" alt="Elena Sato" 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="Leo Carter" 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="Nora Moreau" 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.

release

<div class="relative rounded-xl overflow-hidden" style="max-width:20rem">
  <img src="https://images.unsplash.com/photo-1538333581680-29dd4752ddf2?auto=format&fit=crop&w=1200&h=800&q=70" alt="The story of our wood-fired oven" 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">release</span> 
</div>

8Floating label above a chart

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

Peak 800

<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 800</span> 
</div>

9Sticky header layer

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

Team

Kai Ashford new

Lea Harlow

Freya Moreau

Nadia Alvarez

Aria Kowalski

<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">
    Kai Ashford <span class="badge text-bg-success relative z-1">new</span>
  </div>
  <div class="px-4 py-2 border-b">
    Lea Harlow
  </div>
  <div class="px-4 py-2 border-b">
    Freya Moreau
  </div>
  <div class="px-4 py-2 border-b">
    Nadia Alvarez
  </div>
  <div class="px-4 py-2">
    Aria Kowalski
  </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.

Fresh flavours, made every day

Cooking classes on Saturday mornings teach you our favourite recipes.

<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-1494346480775-936a9f0d0877?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">Fresh flavours, made every day</h3>
  <p class="mb-0 small">Cooking classes on Saturday mornings teach you our favourite recipes.</p>
</div>

12Focus ring over siblings

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

Specials
Desserts
Drinks

<ul class="list-unstyled mb-0" style="max-width:18rem">
  <li class="border px-4 py-2 rounded-t-md relative">Specials</li>
  <li class="border border-primary bg-primary-subtle px-4 py-2 relative z-1" style="margin-top:-1px">Desserts</li>
  <li class="border px-4 py-2 rounded-b-md relative" style="margin-top:-1px">Drinks</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">66</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.

Drinks

30 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">
      Drinks
    </div>
    <div class="small text-muted">
      30 documents
    </div>
  </div>
</div>

15Overlapping sections

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

A table for every occasion

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

<div>
  <div class="text-bg-primary rounded-t-xl p-6 pb-12">
    <h3 class="h5 mb-0">A table for every occasion</h3>
  </div>
  <div class="relative z-1 bg-page border rounded-xl shadow-sm p-4 mx-4" style="margin-top:-2rem">
    Our team has done this many times, so you never have to guess.
  </div>
</div>

16Corner ribbon above a border

A z-2 ribbon overlaps the card border.

Cancelled

Wine pairing

Children are always welcome, with a menu made just for them.

<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">Cancelled</span> 
  <div class="font-semibold">
    Wine pairing
  </div>
  <div class="small text-muted">
    Children are always welcome, with a menu made just for them.
  </div>
</div>

17Hover card layer (static preview)

A preview popover on z-3 overlapping a list.

Isla Ortega
Owen Rossi
Maya Hughes

Our terrace is open from spring to autumn, with heaters for cooler evenings.

<div class="relative" style="height:150px">
  <ul class="list-unstyled border rounded-lg mb-0">
    <li class="px-4 py-2 border-b">Isla Ortega</li>
    <li class="px-4 py-2 border-b">Owen Rossi</li>
    <li class="px-4 py-2">Maya Hughes</li>
  </ul>
  <div class="absolute bg-page border rounded-lg shadow-md p-4 z-3 small" style="top:20px;left:40%;width:13rem">
    Our terrace is open from spring to autumn, with heaters for cooler evenings.
  </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.

$16.73

<div class="relative rounded-xl overflow-hidden border" style="max-width:16rem">
  <img src="../assets/img/product-11.svg" alt="Espresso martini" class="w-full block"> <span class="absolute bottom-0 start-0 m-2 badge text-bg-dark z-1">$16.73</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

Our sommelier has paired each dish with wines from small family vineyards. Bread is baked every morning and pasta is rolled by hand in our kitchen.

<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">
    Our sommelier has paired each dish with wines from small family vineyards. Bread is baked every morning and pasta is rolled by hand in our kitchen.
  </div>
</div>