CSS object-fit decides how an image is fitted into a box of a fixed size.
The short answer: if you only want an image to fill the width of its parent, you do not need object-fit at all. width: 100% and height: auto are enough. You need object-fit when the height has to match too, meaning images with different aspect ratios must sit in identically sized boxes.
This article covers the five values, how to fill the width, how to crop while keeping the ratio, and how to move the crop.
Sponsored
What does object-fit actually do?
The short answer: it decides whether an image that does not match its box gets clipped, shrunk to fit, or stretched.
If you set both width and height on an <img> and the ratios do not match, the image is squashed. object-fit is how you stop that.
/* A tall image in a square box is distorted without this */
img {
width: 300px;
height: 300px;
object-fit: cover; /* keep the ratio, clip the overflow */
}
It only applies to replaced elements such as <img> and <video>. Writing it on a <div> does nothing; for a background image use background-size instead.
It does nothing unless the box has a fixed size
The short answer: object-fit only works when both width and height are determined.
With height: auto the image keeps its natural ratio, so nothing overflows and nothing is left over. Adding object-fit changes nothing visible. If it seems to have no effect, check the height first.
What are the five object-fit values?
The short answer: fill, contain, cover, none and scale-down, with fill as the initial value.
| Value | Aspect ratio | Result |
|---|---|---|
fill (initial) |
Not kept | Stretched to fill the box. The image distorts |
contain |
Kept | Shrunk until it fits. Leaves space on two sides |
cover |
Kept | Scaled until the box is full. Overflow is clipped |
none |
Kept | Natural size, no scaling. Clipped if larger than the box |
scale-down |
Kept | Whichever of none and contain comes out smaller |
The everyday split is simple: cover for thumbnail grids where sizes must match, and contain for product shots or logos that must not be cut.
Sponsored
How do you make an image fill the parent width?
The short answer: two lines. No object-fit and no wrapper div.
img {
width: 100%;
height: auto;
}
height: auto stops the image being squashed vertically by the width and height attributes in the HTML.
Do not delete those attributes though. Browsers use them to know the aspect ratio before the image loads, which prevents layout shift.
<img src="/images/sample.jpg" alt="Sample image" width="1200" height="800">
How do you keep the width at 100% but match the heights?
The short answer: combine aspect-ratio with object-fit: cover.
img {
width: 100%;
aspect-ratio: 16 / 9;
object-fit: cover;
}
Every image, portrait or landscape, is now cropped into a 16:9 box. This is the standard shape for card grids and blog thumbnails.
Change the ratio by changing the value: 1 / 1 for a square, 4 / 3 for four-by-three.
aspect-ratio reached Baseline across the major browsers in September 2021, so it needs no special handling today.
The padding-bottom hack for older browsers
The short answer: where aspect-ratio is unavailable, create the height with padding-bottom on a wrapper and position the image absolutely.
<div class="image-container">
<img src="/images/sample.jpg" alt="Sample image">
</div>
.image-container {
position: relative;
width: 100%;
height: 0;
padding-bottom: 56.25%; /* 16:9 -> 9 / 16 = 0.5625 */
overflow: hidden;
}
.image-container img {
position: absolute;
top: 0;
left: 0;
width: 100%;
height: 100%;
object-fit: cover;
}
A percentage padding-bottom is calculated from the parent’s width. So 100% gives a square and 16:9 needs 56.25%. Recalculating that number for every ratio is exactly what makes this approach tedious.
Sponsored
How do you move the crop?
The short answer: object-fit: cover keeps the centre by default. Use object-position when that cuts off a face.
img {
width: 100%;
aspect-ratio: 16 / 9;
object-fit: cover;
object-position: top; /* keep the top of the image */
}
object-position accepts top, bottom, left, right and center, or coordinates such as 50% 20%. The first value is horizontal, the second vertical.
Why is object-fit not working?
The short answer: almost always the height is not fixed, it is on the wrong element, or the ratios already match.
- Is the height still
auto? Fix it withheightoraspect-ratio - Is it on a
<div>?object-fitis for replaced elements only. For a background image usebackground-size: cover - Do the box and the image share a ratio? Then no value changes anything
When you lay images out in a grid and need the gaps to behave as well, the 2024 CSS Grid updates covers the layout side. If you are also deferring image loading, pair this with the right way to hide and show elements in CSS so hidden images do not stay in the accessibility tree.
