Modern CSS Layouts & Micro-InteractionsProduction-focused CSS patterns and architecture

object-fit and object-position: Images That Fit Any Box

Responsive layouts constantly ask images to fit boxes they were not shot for: a landscape photo in a square card thumbnail, a portrait headshot in a wide banner, a product shot in a fixed-height gallery row. Without guidance the browser stretches the image to the box, distorting it. object-fit tells a replaced element how to fit its content into its box, and object-position decides which part survives when the fit crops. This page covers each fit mode, how to choose a focal point, how to change the crop as the container changes size, and the accessibility and performance details that go with it. It belongs to Intrinsic Sizing Techniques in the Mastering Container Queries & Responsive Layouts guide.

Why the box and the image are separate

A replaced element such as <img> has two sizes. Its box is laid out by CSS — its width, height and aspect ratio. Its content, the image data, has an intrinsic size and ratio of its own. By default, object-fit: fill stretches the content to exactly fill the box, which is harmless when the ratios match and distorting when they do not.

That separation is useful. It means layout can decide the box — a square thumbnail, a 16:9 banner, a row of equal heights — using aspect-ratio for responsive media or grid tracks, while object-fit decides how the image behaves inside it. Designers get consistent card grids regardless of the photos editors upload.

Four fit modes for the same image and box fill stretches the landscape image to the square, distorting it. contain shrinks it to fit with bands above and below. cover enlarges it to fill the square and crops the sides. scale-down behaves like contain but never enlarges a small image. Landscape image, square box fill distorted contain bands top and bottom cover sides cropped scale-down never enlarged none (not shown) keeps the image at its natural size and crops it to the box.

The complete implementation

The gallery below uses cover with focal points for thumbnails, contain for product shots that must never be cropped, and changes the crop per container size. Drag the demo to see the focal point hold.

Live demoobject-fit and object-position on generated images
Each tile is the same wide SVG image: cover with the default centre, cover with a left focal point, and contain. Drag the frame to change the tile sizes. Drag the bottom-right corner to resize the frame in either direction. 
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>object-fit and object-position</title>
<style>
  body { font: 15px/1.5 system-ui, sans-serif; margin: 1rem; }

  .gallery {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(min(100%, 12rem), 1fr));
    gap: 0.75rem;
  }

  /* The box is decided by layout: full column width, square ratio. */
  .thumb {
    display: block;
    width: 100%;
    aspect-ratio: 1;
    /* The content fills the box, cropping the overflow... */
    object-fit: cover;
    /* ...keeping this point in view. Defaults to 50% 50% if omitted. */
    object-position: var(--focus, 50% 50%);
    border-radius: 8px;
    background: #e2e8f0;        /* shows while loading */
  }

  /* Per-image focal points supplied by the CMS as custom properties. */
  .thumb--portrait { --focus: 50% 20%; }     /* keep the face near the top */
  .thumb--left-subject { --focus: 25% 50%; }

  /* Product images must never be cropped: contain, with a neutral band. */
  .thumb--product {
    object-fit: contain;
    background: #f8fafc;
    padding: 0.5rem;
    box-sizing: border-box;
  }
</style>
</head>
<body>
  <div class="gallery">
    <img class="thumb thumb--portrait" src="/img/portrait.jpg" alt="Climber resting on a ledge" width="800" height="1200" loading="lazy">
    <img class="thumb thumb--left-subject" src="/img/boat.jpg" alt="Rowing boat drawn up on shingle" width="1600" height="900" loading="lazy">
    <img class="thumb thumb--product" src="/img/kettle.png" alt="Enamel camping kettle" width="1000" height="1000" loading="lazy">
  </div>
</body>
</html>

The width and height attributes on each <img> are not decoration. They give the browser the image's intrinsic ratio before it loads, and combined with the CSS aspect-ratio they guarantee the box never changes size when the image arrives, which avoids layout shift. The CSS then overrides the attribute-derived ratio with the square the design wants, and object-fit fits the image into it.

The key technique: object-position is a focal point

With cover, the image is scaled until it covers the box on both axes, so it overflows on one axis. object-position aligns the image within the box along that overflowing axis, exactly as background-position does for backgrounds. Percentages are the most useful form, because they describe a point in the image that is aligned with the same relative point in the box.

Choosing what survives a crop A tall image with a face near the top is placed in a wide box with object-fit cover. With the default 50% 50% position the middle of the image is shown and the face is cut off. With 50% 20% the upper part is shown and the face stays in frame. Tall portrait in a wide box, cover 50% 50%: face cropped 50% 20%: face kept

Because the position is a property of each image's content, the natural place to store it is alongside the image: a CMS field for the focal point, output as a custom property in a style attribute (style="--focus: 50% 20%"). The stylesheet reads var(--focus, 50% 50%), so images without a focal point use the centre.

Video, canvas and embeds

object-fit is not only for photographs. Any replaced element supports it, and the same reasoning applies.

Video. A background or hero video shot at 16:9 placed in a tall mobile hero will letterbox by default, with bars above and below. object-fit: cover fills the box and crops the sides, which is usually what a decorative video wants; object-position chooses which part of the frame stays visible. Poster images use the same fit, so the still frame and the playing video match exactly. Decorative autoplaying video also falls under WCAG 2.2.2 Pause, Stop, Hide if it runs longer than five seconds, so provide a pause control or stop it for reduced-motion users.

Canvas and generated images. A <canvas> whose internal resolution differs from its display box can use object-fit: contain to preserve its drawing's ratio without distortion when the layout resizes it.

Iframes and embeds. Embedded content is typically sized by its own document, and object-fit generally has no useful effect on an iframe's internal layout. For responsive embeds, size the iframe box with aspect-ratio and let the embedded page handle its own fit.

Scale-down for icons and logos. scale-down picks whichever of none and contain gives the smaller result, so small logos are never enlarged into blurry blobs while large ones still shrink to fit. It is the right choice for partner-logo grids and user-uploaded avatars of unknown size.

Art direction across container sizes

Sometimes a single focal point is not enough. A wide banner crop of a group photo might show everyone, while the square thumbnail of the same photo should show only the central figure. Container queries can change both the box and the focal point, so a component can choose a different crop depending on the space it has.

.hero-slot { container-type: inline-size; }

.hero-img {
  width: 100%;
  aspect-ratio: 4 / 3;               /* narrow: fairly tall crop */
  object-fit: cover;
  object-position: var(--focus-narrow, 50% 40%);
}

@container (width > 40rem) {
  .hero-img {
    aspect-ratio: 21 / 9;             /* wide: cinematic crop */
    object-position: var(--focus-wide, 50% 50%);
  }
}

For crops so different that one image cannot serve both, use <picture> with <source media> to swap files; media on <source> responds to the viewport, not the container, so it suits page-level heroes rather than reusable components. Animating between crops — transitioning object-position on hover to pan across an image — is possible and cheap on small thumbnails; see Smooth Hover Effects Without JavaScript for the hover patterns and keep such motion out of reduced-motion experiences.

Accessibility and performance notes

Cropping hides information. If the cropped part of an image carries meaning — text in a screenshot, the relevant part of a chart — cover can remove it. Use contain for informational images, and make sure the alt text describes the image as it matters, not just what survives the crop.

Serve appropriately sized files. object-fit crops visually but still downloads the whole image. With srcset and sizes, the browser can pick a file close to the displayed size; for square thumbnails of landscape photos, the chosen file is decided by the box width, so a 300-pixel-wide thumbnail downloads a 300-pixel-wide landscape file and crops its sides.

Reserve the box. Always give images a width and height or an aspect ratio so the page does not shift as they load.

Browser support

object-fit and object-position are supported in all current engines and have been for many years, for <img>, <video> and other replaced elements. aspect-ratio is supported in Chrome and Edge 88+, Firefox 89+ and Safari 15+. Container queries, used for art direction, are supported in Chrome and Edge 105+, Firefox 110+ and Safari 16+.

FAQ

What is the difference between object-fit: cover and contain?cover scales the image to fill the whole box, cropping whatever overflows. contain scales it to fit entirely inside the box, leaving empty space on two sides if the ratios differ. cover guarantees no gaps; contain guarantees nothing is cut off.

How do I keep a person's face in frame when an image is cropped? Set object-position to the face's location as percentages, such as object-position: 40% 25%. When cover crops the image, it keeps that point as close to the same relative position as the crop allows, so the focal point stays visible.

Does object-fit work on background images? No. object-fit applies to replaced elements such as img, video, canvas-like embeds and iframes. The equivalent for background images is background-size: cover or contain, with background-position for the focal point.

Why is my image still distorted with object-fit: cover? Usually because the img element itself has no definite box to fit into, so it takes the image's own ratio and object-fit has nothing to do. Give the element both a width and a height, or a width and an aspect-ratio, so the box ratio differs from the image ratio.

Related articles

More pages in the same section.