The ratio helper keeps a box at a fixed aspect ratio whatever its width, which is perfect for media placeholders, thumbnails, galleries and banners. Pick ratio-1x1, ratio-4x3, ratio-16x9 or ratio-21x9, or set any ratio with the --ui-aspect-ratio variable.
1The four built-in ratios
ratio-1x1, ratio-4x3, ratio-16x9 and ratio-21x9 next to each other, filled with a plain div.
1:1
4:3
16:9
21:9
<div class="row g-3">
<div class="col-6 col-md-3">
<div class="ratio ratio-1x1">
<div class="flex items-center justify-center bg-primary-subtle text-primary-emphasis border border-primary/30 rounded-md font-semibold">
1:1
</div>
</div>
</div>
<div class="col-6 col-md-3">
<div class="ratio ratio-4x3">
<div class="flex items-center justify-center bg-primary-subtle text-primary-emphasis border border-primary/30 rounded-md font-semibold">
4:3
</div>
</div>
</div>
<div class="col-6 col-md-3">
<div class="ratio ratio-16x9">
<div class="flex items-center justify-center bg-primary-subtle text-primary-emphasis border border-primary/30 rounded-md font-semibold">
16:9
</div>
</div>
</div>
<div class="col-6 col-md-3">
<div class="ratio ratio-21x9">
<div class="flex items-center justify-center bg-primary-subtle text-primary-emphasis border border-primary/30 rounded-md font-semibold">
21:9
</div>
</div>
</div>
</div>2Video placeholder
A 16:9 poster image with a centred play button, ready for a video player of your choice.
<div class="ratio ratio-16x9 rounded-md overflow-hidden" style="max-width:36rem">
<div>
<img src="https://images.unsplash.com/photo-1529260830199-42c24126f198?auto=format&fit=crop&w=1600&h=700&q=70" alt="Video poster" class="w-full h-full object-cover">
<button type="button" class="btn btn-light rounded-full absolute top-1/2 start-1/2 -translate-x-1/2 -translate-y-1/2 shadow-md" aria-label="Play video"><i class="bi bi-play-fill" aria-hidden="true"></i></button>
</div>
</div>3Square product thumbnails
ratio-1x1 with object-fit-cover gives every product the same tile, whatever the photo size.
Surf camp
Old town walk
Vineyard stay
Food tour
Weekend getaway
Ocean view suite
<div class="row g-2">
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-md overflow-hidden border">
<img src="../assets/img/product-12.svg" alt="Surf camp" class="object-cover">
</div>
<p class="small truncate mt-1 mb-0">Surf camp</p>
</div>
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-md overflow-hidden border">
<img src="../assets/img/product-11.svg" alt="Old town walk" class="object-cover">
</div>
<p class="small truncate mt-1 mb-0">Old town walk</p>
</div>
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-md overflow-hidden border">
<img src="../assets/img/product-9.svg" alt="Vineyard stay" class="object-cover">
</div>
<p class="small truncate mt-1 mb-0">Vineyard stay</p>
</div>
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-md overflow-hidden border">
<img src="../assets/img/product-7.svg" alt="Food tour" class="object-cover">
</div>
<p class="small truncate mt-1 mb-0">Food tour</p>
</div>
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-md overflow-hidden border">
<img src="../assets/img/product-6.svg" alt="Weekend getaway" class="object-cover">
</div>
<p class="small truncate mt-1 mb-0">Weekend getaway</p>
</div>
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-md overflow-hidden border">
<img src="../assets/img/product-1.svg" alt="Ocean view suite" class="object-cover">
</div>
<p class="small truncate mt-1 mb-0">Ocean view suite</p>
</div>
</div>4Cinematic hero banner
ratio-21x9 for a wide banner with a headline overlay.
Weekends you will talk about for years
<div class="ratio ratio-21x9 rounded-lg overflow-hidden">
<div>
<img src="https://images.unsplash.com/photo-1682686580036-b5e25932ce9a?auto=format&fit=crop&w=1600&h=700&q=70" alt="" class="w-full h-full object-cover">
<div class="absolute bottom-0 start-0 p-4 md:p-6 text-white" style="background:rgba(0,0,0,.45)">
<h3 class="h4 mb-1">Weekends you will talk about for years</h3>
<p class="small mb-0 hidden sm:block">Every hotel on our list is visited and reviewed by our own travel team.</p>
</div>
</div>
</div>5Map placeholder
A 4:3 box reserved for a map, showing the address until the map loads.
Orbiora431 Maple Avenue, Melbourne
<div class="ratio ratio-4x3" style="max-width:24rem">
<div class="flex flex-col items-center justify-center bg-surface-3 border rounded-md text-center p-4">
<span class="text-4xl text-primary-ink"><i class="bi bi-geo-alt-fill" aria-hidden="true"></i></span><strong>Orbiora</strong><span class="small text-muted">431 Maple Avenue, Melbourne</span>
</div>
</div>6Custom 3:2 photo
Any ratio works with the --ui-aspect-ratio variable: 2 / 3 = 66.67% for classic photo prints.
<figure class="mb-0" style="max-width:28rem">
<div class="ratio rounded-md overflow-hidden" style="--ui-aspect-ratio:66.67%">
<img src="https://images.unsplash.com/photo-1554366347-897a5113f6ab?auto=format&fit=crop&w=1200&h=800&q=70" alt="Five things we learned this year" class="object-cover">
</div>
<figcaption class="small text-muted mt-1">3:2 · How to pack for two weeks with one bag</figcaption>
</figure>7Portrait team cards
A 3:4 portrait ratio (133.33%) for team photos in cards.
Ethan Alvarez
Sales Executive
Hana Varga
Content Writer
Nadia Okafor
Data Analyst
<div class="row g-3">
<div class="col-6 col-md-4">
<div class="card h-full">
<div class="ratio card-img-top overflow-hidden" style="--ui-aspect-ratio:133.33%">
<img src="https://images.unsplash.com/photo-1553355202-f869c36581ca?auto=format&fit=crop&w=1200&h=800&q=70" alt="Ethan Alvarez" class="object-cover">
</div>
<div class="card-body py-2">
<h3 class="h6 mb-0">Ethan Alvarez</h3>
<p class="small text-muted mb-0">Sales Executive</p>
</div>
</div>
</div>
<div class="col-6 col-md-4">
<div class="card h-full">
<div class="ratio card-img-top overflow-hidden" style="--ui-aspect-ratio:133.33%">
<img src="https://images.unsplash.com/photo-1578894381163-e72c17f2d45f?auto=format&fit=crop&w=1200&h=800&q=70" alt="Hana Varga" class="object-cover">
</div>
<div class="card-body py-2">
<h3 class="h6 mb-0">Hana Varga</h3>
<p class="small text-muted mb-0">Content Writer</p>
</div>
</div>
</div>
<div class="col-6 col-md-4">
<div class="card h-full">
<div class="ratio card-img-top overflow-hidden" style="--ui-aspect-ratio:133.33%">
<img src="https://images.unsplash.com/photo-1578894381163-e72c17f2d45f?auto=format&fit=crop&w=1200&h=800&q=70" alt="Nadia Okafor" class="object-cover">
</div>
<div class="card-body py-2">
<h3 class="h6 mb-0">Nadia Okafor</h3>
<p class="small text-muted mb-0">Data Analyst</p>
</div>
</div>
</div>
</div>8Vertical stories
A 9:16 ratio (177.78%) for phone sized stories or short clips in a scrolling row.
Nora
Freya
NoahMateo<div class="flex gap-2 overflow-auto pb-1">
<div class="shrink-0" style="width:7rem">
<div class="ratio rounded-lg overflow-hidden" style="--ui-aspect-ratio:177.78%">
<div>
<img src="https://images.unsplash.com/photo-1606922183036-62e19495eaab?auto=format&fit=crop&w=1200&h=800&q=70" alt="Story by Nora Brennan" class="w-full h-full object-cover"><span class="absolute bottom-0 start-0 m-1 badge text-bg-dark">Nora</span>
</div>
</div>
</div>
<div class="shrink-0" style="width:7rem">
<div class="ratio rounded-lg overflow-hidden" style="--ui-aspect-ratio:177.78%">
<div>
<img src="https://images.unsplash.com/photo-1682686580036-b5e25932ce9a?auto=format&fit=crop&w=1200&h=800&q=70" alt="Story by Freya Kim" class="w-full h-full object-cover"><span class="absolute bottom-0 start-0 m-1 badge text-bg-dark">Freya</span>
</div>
</div>
</div>
<div class="shrink-0" style="width:7rem">
<div class="ratio rounded-lg overflow-hidden" style="--ui-aspect-ratio:177.78%">
<div>
<img src="https://images.unsplash.com/photo-1727622765649-1af1d87ee018?auto=format&fit=crop&w=1200&h=800&q=70" alt="Story by Noah Quinn" class="w-full h-full object-cover"><span class="absolute bottom-0 start-0 m-1 badge text-bg-dark">Noah</span>
</div>
</div>
</div>
<div class="shrink-0" style="width:7rem">
<div class="ratio rounded-lg overflow-hidden" style="--ui-aspect-ratio:177.78%">
<div>
<img src="https://images.unsplash.com/photo-1578894381163-e72c17f2d45f?auto=format&fit=crop&w=1200&h=800&q=70" alt="Story by Mateo Kowalski" class="w-full h-full object-cover"><span class="absolute bottom-0 start-0 m-1 badge text-bg-dark">Mateo</span>
</div>
</div>
</div>
</div>9Chart area
A 16:9 box that keeps a simple bar chart in proportion on every screen.
Monthly bookings
Jan
Feb
Mar
Apr
May
Jun
Jul
Aug
<div class="card" style="max-width:36rem">
<div class="card-header small font-semibold">
Monthly bookings
</div>
<div class="card-body">
<div class="ratio ratio-16x9">
<div class="flex items-end gap-2" role="img" aria-label="Bar chart of monthly bookings">
<div class="flex-auto flex flex-col justify-end items-center h-full">
<div class="w-full bg-primary rounded-t-md" style="height:36%">
</div>
<span class="small text-muted">Jan</span>
</div>
<div class="flex-auto flex flex-col justify-end items-center h-full">
<div class="w-full bg-primary rounded-t-md" style="height:48%">
</div>
<span class="small text-muted">Feb</span>
</div>
<div class="flex-auto flex flex-col justify-end items-center h-full">
<div class="w-full bg-primary rounded-t-md" style="height:45%">
</div>
<span class="small text-muted">Mar</span>
</div>
<div class="flex-auto flex flex-col justify-end items-center h-full">
<div class="w-full bg-primary rounded-t-md" style="height:73%">
</div>
<span class="small text-muted">Apr</span>
</div>
<div class="flex-auto flex flex-col justify-end items-center h-full">
<div class="w-full bg-primary rounded-t-md" style="height:49%">
</div>
<span class="small text-muted">May</span>
</div>
<div class="flex-auto flex flex-col justify-end items-center h-full">
<div class="w-full bg-primary rounded-t-md" style="height:31%">
</div>
<span class="small text-muted">Jun</span>
</div>
<div class="flex-auto flex flex-col justify-end items-center h-full">
<div class="w-full bg-primary rounded-t-md" style="height:69%">
</div>
<span class="small text-muted">Jul</span>
</div>
<div class="flex-auto flex flex-col justify-end items-center h-full">
<div class="w-full bg-primary rounded-t-md" style="height:25%">
</div>
<span class="small text-muted">Aug</span>
</div>
</div>
</div>
</div>
</div>10Blog card cover
ratio-16x9 as a card image keeps every post card in a grid the same height.
how-to
Our favourite tips for busy weeks
Jul 14, 2026
<div class="card" style="max-width:22rem">
<div class="ratio ratio-16x9 card-img-top overflow-hidden">
<img src="https://images.unsplash.com/photo-1682686580036-b5e25932ce9a?auto=format&fit=crop&w=1200&h=800&q=70" alt="Hidden beaches of the Mediterranean" class="object-cover">
</div>
<div class="card-body">
<span class="badge text-bg-light border mb-2">how-to</span>
<h3 class="h6">Our favourite tips for busy weeks</h3>
<p class="small text-muted mb-0">Jul 14, 2026</p>
</div>
</div>11Caption over a gradient
A 4:3 image with a gradient overlay so white caption text stays readable.
SingaporeCar rental
<div class="ratio ratio-4x3 rounded-lg overflow-hidden" style="max-width:24rem">
<div>
<img src="https://images.unsplash.com/photo-1578894381163-e72c17f2d45f?auto=format&fit=crop&w=1200&h=800&q=70" alt="" class="w-full h-full object-cover">
<div class="absolute bottom-0 w-full p-4 text-white" style="background:linear-gradient(transparent,rgba(0,0,0,.7))">
<strong class="block">Singapore</strong><span class="small">Car rental</span>
</div>
</div>
</div>12Mixed ratio gallery
Combining 1:1, 4:3 and 16:9 tiles in one responsive grid.
<div class="row g-2">
<div class="col-md-6">
<div class="ratio ratio-4x3 rounded-md overflow-hidden">
<img src="https://images.unsplash.com/photo-1783443076547-fb9cb67224a0?auto=format&fit=crop&w=1200&h=800&q=70" alt="Gallery photo 1" class="object-cover">
</div>
</div>
<div class="col-md-6">
<div class="row g-2">
<div class="col-6">
<div class="ratio ratio-1x1 rounded-md overflow-hidden">
<img src="https://images.unsplash.com/photo-1605130284535-11dd9eedc58a?auto=format&fit=crop&w=800&h=800&q=70" alt="Gallery photo 2" class="object-cover">
</div>
</div>
<div class="col-6">
<div class="ratio ratio-1x1 rounded-md overflow-hidden">
<img src="https://images.unsplash.com/photo-1553355202-f869c36581ca?auto=format&fit=crop&w=800&h=800&q=70" alt="Gallery photo 3" class="object-cover">
</div>
</div>
<div class="col-12">
<div class="ratio ratio-21x9 rounded-md overflow-hidden">
<img src="https://images.unsplash.com/photo-1578894381163-e72c17f2d45f?auto=format&fit=crop&w=1600&h=700&q=70" alt="Gallery photo 4" class="object-cover">
</div>
</div>
</div>
</div>
</div>13Thumbnails in table cells
A small ratio-1x1 box keeps order line images square inside a table.
| Image | Item | Price |
|---|---|---|
| Old town walk | $33.00 |
 | City break | $197.00 |
| Surf camp | $533.00 |
<table class="table align-middle mb-0">
<thead>
<tr>
<th scope="col"><span class="sr-only">Image</span></th>
<th scope="col">Item</th>
<th scope="col" class="text-end">Price</th>
</tr>
</thead>
<tbody>
<tr>
<td style="width:4rem"><div class="ratio ratio-1x1 rounded-md overflow-hidden"><img src="../assets/img/product-11.svg" alt="Old town walk" class="object-cover"></div></td>
<td class="align-middle">Old town walk</td>
<td class="align-middle text-end">$33.00</td>
</tr>
<tr>
<td style="width:4rem"><div class="ratio ratio-1x1 rounded-md overflow-hidden"><img src="../assets/img/product-2.svg" alt="City break" class="object-cover"></div></td>
<td class="align-middle">City break</td>
<td class="align-middle text-end">$197.00</td>
</tr>
<tr>
<td style="width:4rem"><div class="ratio ratio-1x1 rounded-md overflow-hidden"><img src="../assets/img/product-12.svg" alt="Surf camp" class="object-cover"></div></td>
<td class="align-middle">Surf camp</td>
<td class="align-middle text-end">$533.00</td>
</tr>
</tbody>
</table>14Empty cover placeholder
A dashed 4:3 area that reserves space for an image that has not been chosen yet.
No cover image yet
<div class="ratio ratio-4x3" style="max-width:20rem">
<div class="flex flex-col items-center justify-center border border-2 border-secondary/30 rounded-lg text-muted wt-border-dashed">
<span class="text-3xl"><i class="bi bi-image-fill" aria-hidden="true"></i></span><span class="small">No cover image yet</span>
</div>
</div>15Colour swatches
Empty square ratios make perfect colour swatches for a style guide.
primary
primary
secondary
secondary
success
success
info
info
warning
warning
danger
danger
<div class="row g-2">
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-lg bg-primary">
<span class="sr-only">primary</span>
</div>
<p class="small text-center mt-1 mb-0">primary</p>
</div>
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-lg bg-secondary">
<span class="sr-only">secondary</span>
</div>
<p class="small text-center mt-1 mb-0">secondary</p>
</div>
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-lg bg-success">
<span class="sr-only">success</span>
</div>
<p class="small text-center mt-1 mb-0">success</p>
</div>
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-lg bg-info">
<span class="sr-only">info</span>
</div>
<p class="small text-center mt-1 mb-0">info</p>
</div>
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-lg bg-warning">
<span class="sr-only">warning</span>
</div>
<p class="small text-center mt-1 mb-0">warning</p>
</div>
<div class="col-4 col-md-2">
<div class="ratio ratio-1x1 rounded-lg bg-danger">
<span class="sr-only">danger</span>
</div>
<p class="small text-center mt-1 mb-0">danger</p>
</div>
</div>16Video thumbnails with badges
Duration and status badges positioned over 16:9 thumbnails.
4:02NewLooking back at a busy season
4:18Our favourite small hotels this year
6:54Ten weekend escapes within two hours of home
<div class="row g-3">
<div class="col-md-4">
<div class="ratio ratio-16x9 rounded-md overflow-hidden">
<div>
<img src="https://images.unsplash.com/photo-1584467541268-b040f83be3fd?auto=format&fit=crop&w=1200&h=800&q=70" alt="" class="w-full h-full object-cover"><span class="absolute bottom-0 end-0 m-2 badge text-bg-dark">4:02</span><span class="absolute top-0 start-0 m-2 badge text-bg-danger">New</span>
</div>
</div>
<p class="small font-semibold mt-1 mb-0">Looking back at a busy season</p>
</div>
<div class="col-md-4">
<div class="ratio ratio-16x9 rounded-md overflow-hidden">
<div>
<img src="https://images.unsplash.com/photo-1529260830199-42c24126f198?auto=format&fit=crop&w=1200&h=800&q=70" alt="" class="w-full h-full object-cover"><span class="absolute bottom-0 end-0 m-2 badge text-bg-dark">4:18</span>
</div>
</div>
<p class="small font-semibold mt-1 mb-0">Our favourite small hotels this year</p>
</div>
<div class="col-md-4">
<div class="ratio ratio-16x9 rounded-md overflow-hidden">
<div>
<img src="https://images.unsplash.com/photo-1606922183036-62e19495eaab?auto=format&fit=crop&w=1200&h=800&q=70" alt="" class="w-full h-full object-cover"><span class="absolute bottom-0 end-0 m-2 badge text-bg-dark">6:54</span>
</div>
</div>
<p class="small font-semibold mt-1 mb-0">Ten weekend escapes within two hours of home</p>
</div>
</div>17Media list
Fixed width 4:3 thumbnails beside article titles in a reading list.
Three days in Lisbon, hour by hour
Oct 6, 2025 · 5 min read
How to choose the right trip
Nov 14, 2025 · 5 min read
What our travellers asked us most
Jan 29, 2026 · 4 min read
<ul class="list-unstyled mb-0 vstack gap-4">
<li class="flex gap-4"><div class="shrink-0" style="width:6rem"><div class="ratio ratio-4x3 rounded-md overflow-hidden"><img src="https://images.unsplash.com/photo-1727622765649-1af1d87ee018?auto=format&fit=crop&w=1200&h=800&q=70" alt="" class="object-cover"></div></div><div><h3 class="h6 mb-1">Three days in Lisbon, hour by hour</h3><p class="small text-muted mb-0">Oct 6, 2025 · 5 min read</p></div></li>
<li class="flex gap-4"><div class="shrink-0" style="width:6rem"><div class="ratio ratio-4x3 rounded-md overflow-hidden"><img src="https://images.unsplash.com/photo-1578894381163-e72c17f2d45f?auto=format&fit=crop&w=1200&h=800&q=70" alt="" class="object-cover"></div></div><div><h3 class="h6 mb-1">How to choose the right trip</h3><p class="small text-muted mb-0">Nov 14, 2025 · 5 min read</p></div></li>
<li class="flex gap-4"><div class="shrink-0" style="width:6rem"><div class="ratio ratio-4x3 rounded-md overflow-hidden"><img src="https://images.unsplash.com/photo-1605130284535-11dd9eedc58a?auto=format&fit=crop&w=1200&h=800&q=70" alt="" class="object-cover"></div></div><div><h3 class="h6 mb-1">What our travellers asked us most</h3><p class="small text-muted mb-0">Jan 29, 2026 · 4 min read</p></div></li>
</ul>18Responsive ratio
A small custom class changes --ui-aspect-ratio per breakpoint: square on phones, 21:9 on tablets and up.
<div class="ratio hp-ratio-resp rounded-lg overflow-hidden">
<img src="https://images.unsplash.com/photo-1553355202-f869c36581ca?auto=format&fit=crop&w=1600&h=700&q=70" alt="Hand-picked stays in beautiful places" class="object-cover">
</div>19Round avatars
ratio-1x1 with rounded-circle keeps profile pictures perfectly round even when the source is not square.
<div class="flex flex-wrap gap-4">
<div class="text-center" style="width:5rem">
<div class="ratio ratio-1x1 rounded-full overflow-hidden border border-2 border-primary">
<img src="../assets/img/avatar-2.svg" alt="Zoe Nguyen" class="object-cover">
</div>
<span class="small block truncate mt-1">Zoe</span>
</div>
<div class="text-center" style="width:5rem">
<div class="ratio ratio-1x1 rounded-full overflow-hidden border border-2 border-primary">
<img src="../assets/img/avatar-12.svg" alt="Priya Ashford" class="object-cover">
</div>
<span class="small block truncate mt-1">Priya</span>
</div>
<div class="text-center" style="width:5rem">
<div class="ratio ratio-1x1 rounded-full overflow-hidden border border-2 border-primary">
<img src="../assets/img/avatar-5.svg" alt="Mia Tanaka" class="object-cover">
</div>
<span class="small block truncate mt-1">Mia</span>
</div>
<div class="text-center" style="width:5rem">
<div class="ratio ratio-1x1 rounded-full overflow-hidden border border-2 border-primary">
<img src="../assets/img/avatar-1.svg" alt="Ravi Harlow" class="object-cover">
</div>
<span class="small block truncate mt-1">Ravi</span>
</div>
</div>20Loading skeleton
A 16:9 placeholder block with placeholder-glow while the real image and text load.
The skeleton reserves the exact space, so the page does not jump when content arrives.
<div class="card" style="max-width:22rem" aria-hidden="true">
<div class="ratio ratio-16x9 placeholder-glow">
<span class="placeholder"></span>
</div>
<div class="card-body placeholder-glow">
<span class="placeholder col-7 mb-2"></span><span class="placeholder col-4"></span>
</div>
</div>
<p class="small text-muted mt-2 mb-0">The skeleton reserves the exact space, so the page does not jump when content arrives.</p>