CSS object-fit Property

What You’ll Learn

The object-fit property controls how images, videos, and other replaced content fit inside a container. It is one of the most useful tools for responsive layouts because it prevents awkward stretching while keeping media looking polished.

Introduction

The object-fit property in CSS is used to control how the content of a replaced element, such as an <img> or <video>, is resized to fit its container.

This property is particularly useful for maintaining aspect ratios and preventing distortion when images or videos are scaled to fit a specific size.

Definition and Usage

The object-fit CSS property tells the browser how replaced content should be sized relative to its box. You usually set explicit width and height on the image or its container, then choose a fit mode such as cover or contain.

This makes it easy to build card thumbnails, hero banners, profile photos, and video embeds that stay visually consistent across screen sizes.

📝 Syntax

The syntax for the object-fit property is straightforward. It can be applied to any replaced element, such as an image, video, or iframe:

element {
  object-fit: value;
}

Here, value determines how the content is resized to fit the container.

Basic Example

.container img {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

Syntax Rules

• Set a defined width and height on the media element or its container.
• Choose one keyword: fill, contain, cover, none, or scale-down.
• Pair with object-position when you need to control cropping focus.
• Use overflow: hidden on the container when cropped edges should not spill out.

🎯 Default Value

The default value of the object-fit property is fill. This means the content will stretch to fill the entire container, which can sometimes result in distortion if the aspect ratio of the content does not match the container.

That is why many responsive layouts explicitly set object-fit: cover or object-fit: contain instead of relying on the default.

💎 Property Values

The object-fit property accepts five keyword values. Each one changes how content is scaled inside its box.

Supported Elements

object-fit is designed for replaced elements — content whose size comes from an external resource rather than CSS text flow:

• <img> — the most common use case for cards, galleries, and avatars.
• <video> — useful for background videos and fixed-ratio players.
• <iframe> — can help embedded content fit responsive frames.

For best results, give the element a defined box using width, height, or a parent container with a fixed aspect ratio.

Examples Gallery

Use object-fit to control how images and videos behave inside fixed-size containers.

🖼️ Responsive Images

These patterns appear constantly in card grids, profile photos, and hero sections.

Example 1 — Card Thumbnail with cover

In this example, an image fills a fixed-size container while keeping its aspect ratio. Extra edges are cropped instead of stretching.

cover-thumbnail.html

Copy

<style>
  .container {
    width: 300px;
    height: 200px;
    border: 1px solid #ddd;
    overflow: hidden;
  }

  .container img {
    width: 100%;
    height: 100%;
    object-fit: cover;
  }
</style>

<div class="container">
  <img src="/images/bg-image.webp" alt="Example image">
</div>

View Output Try It Yourself

📤 Output:

How It Works

The image fills the container completely. Because cover preserves aspect ratio, the browser crops overflow instead of stretching the photo.

Example 2 — Logo Box with contain

Use contain when the entire image must stay visible, such as logos or product photos inside a fixed frame.

contain-logo.css

Copy

.logo-box {
  width: 160px;
  height: 100px;
  background: #f8fafc;
  border: 1px solid #e2e8f0;
}

.logo-box img {
  width: 100%;
  height: 100%;
  object-fit: contain;
}

View Output Try It Yourself

📤 Output:

How It Works

The image scales down to fit inside the box. Empty space may appear on the sides or top and bottom, but nothing is cropped.

📐 Fit Modes

Compare stretching, original sizing, and shrink-only behavior when a container is smaller than the media.

Example 3 — Default fill Behavior

This shows the default fill behavior. The image stretches to match the container even when that distorts the aspect ratio.

fill-stretch.css

Copy

.banner img {
  width: 100%;
  height: 180px;
  object-fit: fill;
}

View Output Try It Yourself

📤 Output:

How It Works

Both width and height are forced to match the container. This is rarely ideal for photos, which is why cover and contain are more common.

Example 4 — Responsive Video Frame

Combine a sized container with object-fit: cover so videos behave like polished media cards.

video-frame.css

Copy

.video-frame {
  width: 100%;
  aspect-ratio: 16 / 9;
  overflow: hidden;
  border-radius: 0.75rem;
}

.video-frame video {
  width: 100%;
  height: 100%;
  object-fit: cover;
}

View Output Try It Yourself

📤 Output:

16:9 media frame

How It Works

The frame keeps a 16 / 9 ratio, and the video fills it without letterboxing when cover is used.

Pair with object-position

When you use object-fit: cover, part of the image may be cropped. The related object-position property lets you choose which area stays visible, such as object-position: top center for portrait photos or product shots.

.avatar img {
  width: 100%;
  height: 100%;
  object-fit: cover;
  object-position: top center;
}

♿ Accessibility

• Always provide alt text — Cropping with cover can hide important visual details, so describe the image meaningfully.
• Do not hide critical content — If text or key subject matter gets cropped, adjust the frame ratio or use object-position.
• Avoid distortion — Stretched images from fill can look unclear and reduce readability of embedded text or logos.
• Test responsive layouts — A crop that looks fine on desktop may remove important content on mobile.

💡 Best Practices