CSS 'object-fit' Property: Complete Reference

What Is the `object-fit` Property?

The object-fit property in CSS controls how a replaced element’s content (such as an <img> or <video>) is resized to fit inside its container. It behaves similarly to the background-size property but is applied directly to the replaced element itself rather than its background.

This property is especially useful when you have a fixed-size container (e.g., a square thumbnail grid) and need to display images of varying aspect ratios without distortion or cropping.

Why `object-fit` Matters

Without object-fit, replaced elements are stretched or squashed to fill their container’s dimensions by default, which often results in ugly distortions. object-fit gives you five distinct behaviors:

fill – Stretches the content to exactly fill the container (distortion may occur).
contain – Scales the content to fit within the container while preserving its aspect ratio; may leave empty space (letterboxing).
cover – Scales the content to cover the entire container, preserving aspect ratio; parts may be cropped.
none – Displays the content at its original size; may overflow or leave gaps.
scale-down – Acts like none or contain, whichever results in a smaller image.

This makes object-fit essential for responsive image grids, video backgrounds, user avatars, and any layout where the container’s size is fixed but the media’s aspect ratio varies.

How to Use `object-fit`

Basic Syntax

/* Target the replaced element */
img {
  width: 200px;
  height: 200px;
  object-fit: cover;
}

Complete Example with All Values

<!DOCTYPE html>
<html>
<head>
  <style>
    .container {
      display: flex;
      gap: 20px;
      flex-wrap: wrap;
    }
    .box {
      width: 200px;
      height: 200px;
      border: 2px solid #333;
      overflow: hidden; /* helps visualise cropping */
    }
    .box img {
      width: 100%;
      height: 100%;
      display: block;
    }
    .fill img     { object-fit: fill; }
    .contain img  { object-fit: contain; background: #eee; }
    .cover img    { object-fit: cover; }
    .none img     { object-fit: none; }
    .scale-down img { object-fit: scale-down; }
  </style>
</head>
<body>
  <h3>object-fit Demos</h3>
  <div class="container">
    <div class="box fill">
      <img src="https://via.placeholder.com/400x300/ff7f7f" alt="fill">
      <p>fill</p>
    </div>
    <div class="box contain">
      <img src="https://via.placeholder.com/400x300/7fbfff" alt="contain">
      <p>contain</p>
    </div>
    <div class="box cover">
      <img src="https://via.placeholder.com/400x300/7fff7f" alt="cover">
      <p>cover</p>
    </div>
    <div class="box none">
      <img src="https://via.placeholder.com/400x300/ffbf7f" alt="none">
      <p>none</p>
    </div>
    <div class="box scale-down">
      <img src="https://via.placeholder.com/400x300/bf7fff" alt="scale-down">
      <p>scale-down</p>
    </div>
  </div>
</body>
</html>

In the example above, each .box is a 200×200 pixel square. The images used are 400×300 (landscape orientation). Notice how fill distorts the image, contain shows white space (letterboxing), cover crops the sides, none shows the original size (overflowing), and scale-down behaves like contain (since the container is smaller than the image).

Using `object-fit` with `<video>`

video {
  width: 100%;
  height: 400px;
  object-fit: cover;
}

This makes the video fill the container while cropping to maintain aspect ratio – ideal for video backgrounds.

Combining with `object-position`

The object-position property works together with object-fit to control the alignment of the content within the element’s box. By default it is 50% 50% (center).

img {
  width: 300px;
  height: 300px;
  object-fit: cover;
  object-position: 20% 80%; /* shifts focus to top-left area */
}

Best Practices

Always set explicit dimensions on the replaced element (width and height) – object-fit only works when the element has a defined size.
Use overflow: hidden on the parent when using cover or none to prevent content spilling outside the box.
Combine with object-position to fine-tune the visible area (especially important for faces in user avatars).
Avoid fill for images unless you intentionally want distortion – it rarely looks good.
For responsive layouts, set the container dimensions using relative units (%, vw, vh) and let object-fit handle the scaling.
Test across browsers – object-fit is supported in all modern browsers, but older versions of Internet Explorer do not support it. Consider a polyfill or fallback for legacy support.
Use scale-down with caution – it can produce unexpected results if the original image is smaller than the container; the image will not be scaled up.

Conclusion

The CSS object-fit property is a powerful tool for controlling how images, videos, and other replaced elements are displayed within their containers. By choosing the right value—fill, contain, cover, none, or scale-down—you can avoid distortion, maintain aspect ratios, and create visually consistent layouts. Combined with object-position, it gives you fine-grained control over media presentation. Mastering object-fit is essential for modern responsive web design and ensures that your media assets behave predictably across different screen sizes and container shapes.