Object-fit: Browser Support, Values, Use Cases

What is object-fit?

object-fit is a CSS property defined by the W3C in CSS Images Module Level 3. It tells the browser how to size a replaced element, such as an img or video, inside its content box. The five allowed values are fill, contain, cover, none, and scale-down.

Which browsers does object-fit support?

object-fit ships by default in every modern engine. The Web Platform Baseline marks it as Widely Available across Chromium, Gecko, and WebKit, with Internet Explorer the only major engine that never added the property.

What are the object-fit property values?

object-fit accepts five keyword values that decide how the replaced element scales inside its content box. The default is fill, but most production code uses cover or contain to preserve the aspect ratio of images and videos.

• fill (default): Stretches the media to fill the entire content box. The aspect ratio is ignored, so a wide photo placed in a square box looks squashed. Use it when the source already matches the box.
• contain: Scales the media to fit fully inside the box while keeping the original aspect ratio. Empty letterbox or pillarbox bars appear when the ratios differ. Use it for product thumbnails where every pixel must be visible.
• cover: Scales the media to fill the box and crops any overflow, keeping the aspect ratio. No empty space appears but pixels at the edges are cut. Use it for hero images, avatars, and card cover photos.
• none: Keeps the media at its intrinsic size. The box may show only a slice of the image or surround it with empty space. Pair it with object-position to control which slice is visible.
• scale-down: Picks the smaller result between none and contain. Small images stay at their natural size while large ones shrink to fit. It is the safest pick for mixed asset libraries with unpredictable sizes.

Pair any value with object-position to shift the scaled media inside the box. The default is 50% 50%, which centers the content; object-position: top keeps the top of a portrait image visible after a cover crop.

/* 1. Cover: fill the box and crop overflow. Useful for hero images and avatars. */
.card-image {
    width: 320px;
    height: 200px;
    object-fit: cover;
    object-position: center;
}

/* 2. Contain: fit the whole image inside the box, even if bars appear. */
.product-thumb {
    width: 200px;
    height: 200px;
    object-fit: contain;
    background: #f5f5f5;
}

/* 3. None: keep the image at its intrinsic size and crop with the box. */
.fixed-icon {
    width: 64px;
    height: 64px;
    object-fit: none;
    object-position: 0 0;
}

/* 4. Detect support before shipping a fallback. */
@supports not (object-fit: cover) {
    .card-image {
        background-size: cover;
        background-position: center;
    }
}

What are the use cases of object-fit?

object-fit replaces a stack of older techniques such as background-image hacks, JavaScript resize scripts, and absolute-positioned img wrappers. Most teams adopt it on responsive media grids, product galleries, and any layout where a fixed box has to display arbitrary user-uploaded content.

• Responsive hero images: Use object-fit: cover with object-position: center on a full-width hero img so the artwork fills the viewport at every screen size without distortion.
• Avatars and profile pictures: Square avatar boxes with object-fit: cover crop arbitrary user uploads to a circle without forcing users to pre-crop their photos.
• Product thumbnail grids: object-fit: contain shows every product photo in full without cropping, which is critical for ecommerce where the entire item must be visible.
• Video player layouts: Apply object-fit: cover to a video tag so a 16:9 stream fills a 4:3 player on a tablet without black bars on the sides.
• Card layouts and CMS content: Mixed image dimensions from a CMS render uniformly when each card image has object-fit: cover and a fixed width and height, instead of breaking the grid layout.
• Replacing background-image hacks: object-fit on a real img tag preserves SEO, alt text, and lazy-loading attributes that a CSS background-image cannot provide.

What are the known issues with object-fit?

object-fit ships widely but still surprises teams that move from a JS-based crop to a pure CSS one. Most of the bugs come from missing dimensions on the img tag, video-tag gaps in Edge Legacy, and IE 11 traffic that needs a polyfill.

• No effect without a sized box: object-fit only changes how content fits an already sized box. An img with no width or height ignores the property and renders at its intrinsic size.
• Edge Legacy video gap: Edge 16 to 18 honored object-fit on img but not on video, so a video tag in those builds always renders with the default fill stretch.
• Internet Explorer has no support: IE 5.5 to 11 drop the declaration entirely. Use the object-fit-images polyfill for img tags or swap to a background-image fallback for IE traffic.
• iOS 9 video glitch: Safari iOS 8 to 9.3 supported object-fit on img only. A video tag with object-fit: cover in those builds stretches to fill the box instead of cropping.
• Conflicts with intrinsic sizing: Setting both width: 100% and height: auto on an img with object-fit: cover removes the cropping effect, because the box auto-resizes to the image. Pin both dimensions or use aspect-ratio.

In my experience, the trap that bites teams hardest is shipping a card grid with object-fit: cover and forgetting that one CMS template missing the height attribute on its img tag will quietly fall back to fill on every card it renders.

Citations

All object-fit version numbers and platform notes in this guide come from these primary sources:

• MDN Web Docs - object-fit: developer.mozilla.org/en-US/docs/Web/CSS/object-fit
• MDN Web Docs - object-position: developer.mozilla.org/en-US/docs/Web/CSS/object-position
• W3C CSS Images Module Level 3: www.w3.org/TR/css-images-3
• WebKit blog - Safari 10 release notes: webkit.org/blog/6928/new-webkit-features-in-safari-10
• Mozilla Firefox 36 release notes: mozilla.org/en-US/firefox/36.0/releasenotes
• Chrome Platform Status - object-fit: chromestatus.com/feature/5685905058086912
• Apple Developer - Safari 10 release notes: developer.apple.com/.../Safari_10_0
• Microsoft Learn - Microsoft Edge developer documentation: learn.microsoft.com/en-us/microsoft-edge/web-platform
• Wikipedia - Cascading Style Sheets: en.wikipedia.org/wiki/Cascading_Style_Sheets
• object-fit-images polyfill (Federico Brigante): github.com/fregante/object-fit-images