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.
<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.
<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.
<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.
Three days that change how you work
A powerful community makes data easy to understand without extra tools.
<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">Three days that change how you work</h3>
<p class="small mb-0">A powerful community makes data easy to understand without extra tools.</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="Kenji Mensah" width="44" height="44" class="rounded-full border border-2 border-white relative z-3"> <img src="../assets/img/avatar-7.svg" alt="Noah Carter" 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="Ava Varga" 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="Liam Fischer" 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.
<div class="relative rounded-xl overflow-hidden" style="max-width:20rem">
<img src="../assets/img/photo-11.svg" alt="The focused release checklist" 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.
<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 921</span>
</div>9Sticky header layer
A sticky header with z-2 stays above rows that have their own positioned badges.
<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">
Kenji Larsen <span class="badge text-bg-success relative z-1">new</span>
</div>
<div class="px-4 py-2 border-b">
Ella Okafor
</div>
<div class="px-4 py-2 border-b">
Freya Hughes
</div>
<div class="px-4 py-2 border-b">
Jonah Varga
</div>
<div class="px-4 py-2">
Isla Delgado
</div>
</div>10Cards in a fan
Rotated cards stacked with z-1 to z-3.
z-1z-2z-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.
Experiences people talk about
Our sponsorship helps decisions quicker and clearer with friendly support.
<div class="relative z-0 rounded-xl overflow-hidden p-6 text-white" style="min-height:180px">
<img src="../assets/img/wide-3.svg" 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">Experiences people talk about</h3>
<p class="mb-0 small">Our sponsorship helps decisions quicker and clearer with friendly support.</p>
</div>12Focus ring over siblings
List group items lift their active item with z-1 so its border shows on both edges.
- Panel
- Webinar
- Webinar
<ul class="list-unstyled mb-0" style="max-width:18rem">
<li class="border px-4 py-2 rounded-t-md relative">Panel</li>
<li class="border border-primary bg-primary-subtle px-4 py-2 relative z-1" style="margin-top:-1px">Webinar</li>
<li class="border px-4 py-2 rounded-b-md relative" style="margin-top:-1px">Webinar</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">51</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.
<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">
Meetup
</div>
<div class="small text-muted">
38 documents
</div>
</div>
</div>15Overlapping sections
A card with z-1 overlaps the coloured band above it via a negative top offset.
Three days that change how you work
<div>
<div class="text-bg-primary rounded-t-xl p-6 pb-12">
<h3 class="h5 mb-0">Three days that change how you work</h3>
</div>
<div class="relative z-1 bg-page border rounded-xl shadow-sm p-4 mx-4" style="margin-top:-2rem">
The new world-class speakers keeps complex tasks into simple steps for teams of every size.
</div>
</div>16Corner ribbon above a border
A z-2 ribbon overlaps the card border.
<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">Overdue</span>
<div class="font-semibold">
Ticketing
</div>
<div class="small text-muted">
Our ticketing keeps new ideas to life on any device.
</div>
</div>17Hover card layer (static preview)
A preview popover on z-3 overlapping a list.
- Amara Patel
- Kenji Ortega
- Mason Moreau
<div class="relative" style="height:150px">
<ul class="list-unstyled border rounded-lg mb-0">
<li class="px-4 py-2 border-b">Amara Patel</li>
<li class="px-4 py-2 border-b">Kenji Ortega</li>
<li class="px-4 py-2">Mason Moreau</li>
</ul>
<div class="absolute bg-page border rounded-lg shadow-md p-4 z-3 small" style="top:20px;left:40%;width:13rem">
The new certificates keeps results you can measure all year round.
</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.
<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.
<div class="relative rounded-xl overflow-hidden border" style="max-width:16rem">
<img src="../assets/img/product-11.svg" alt="Workshop ticket" class="w-full block"> <span class="absolute bottom-0 start-0 m-2 badge text-bg-dark z-1">$14.91</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
<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">
This elegant dashboard lets you focused on what matters from the very first day. The new networking lounges guides the whole team on the same page for teams of every size.
</div>
</div>