How to Use the CSS object-fit Property

Imagine you have a frame for a picture, but the picture doesn‘t fit perfectly inside the frame. Maybe it’s too tall, or too wide. In this case, you’d fold or trim the photo so it fits properly.

In CSS, you’ll probably come across a similar issue with images, and the object-fit property is the solution — it’s like telling the picture how it should behave within that frame.

In this post, we’ll show you when and how to use it to make your images and image grids look as professional as they can be. Plus, we’ll also see how the object-position property can be used in conjunction with object-fit. Let’s dive in.

What is object-fit in CSS?

Image sizing can be tricky in HTML. Say you have an image that you want to give a specific width and height. When rendering the HTML, the browser first creates a container for the image with the specified dimensions. Then, it adds the image into the container and stretches the image to fit the dimensions of the container.

For example, the below code features one image that is 300 pixels by 200 pixels, and then the same image resized to 250 pixels by 250 pixels:

See the Pen css object fit: stretch example by HubSpot (@hubspot) on CodePen.

Because the image’s container changed and the aspect ratio of the original image is not preserved, the resized image looks oddly warped, and we don’t want that.

Here’s where object-fit comes in. The CSS object-fit property tells the browser how to resize the image inside its container. Instead of stretching or squishing an image, object-fit proportionately changes the image. The final product is a properly sized photo without distortion.

Before we continue, you may be wondering why the property is called “object”-fit and not “image”-fit. This is because this property can be used on any object in HTML. In HTML, an object is any external resource — in other words, a file that is not in the HTML. Most commonly, these are images or videos. For the purposes of this article, we’ll use images in our examples.

CSS object-fit Values

object-fit can take one of five values:

• fill: The image resizes to fill its container, stretching and/or squashing if necessary. This is the default value and what happens if object-fit is not defined.
• contain: The image keeps its aspect ratio and is scaled to fit its container. The entire image will be visible, even if it doesn’t fill the entire container.
• cover: The image keeps its aspect ratio and is scaled to fill the entire container. This may result in the image being clipped.
• none: The image is displayed at its original size, regardless of the container's dimensions.
• scale-down: The image is scaled down to either contain or none, whichever is a smaller size.

Here’s a demo of how all values of object-fit work when applied to the same image. I’ve also added a green background to the images to show the container.

See the Pen css object fit: object fit examples 1 by HubSpot (@hubspot) on CodePen.

Here’s another example with a taller image:

See the Pen css object fit: object fit examples 2 by HubSpot (@hubspot) on CodePen.

And, as noted before, object-fit can also be applied to <video> elements in addition to <img> elements.

CSS object-position

If you’re going to use the object-fit property, it’s also useful to know about the object-position property. This property sets the position of the image inside of its container, which is useful if an image is cropped from resizing.

Notice that, in the previous examples, the resized images are all centered inside of their containers. This is the default behavior of the browser, but you can overwrite this with object-position.

object-position also targets the <img> (or <video>) tag and takes one position value consisting of 2 numbers. The first specifies the position of the image on the x-axis and the second specifies its position on the y-axis. Each of these numbers can be a percentage or pixel value. They can also be a string: left, right, or center. The default value is 50% 50%, which centers the image in its container.

Here’s an example of an image that has been resized with object-fit: cover with the image set to different positions:

See the Pen css object fit: object position by HubSpot (@hubspot) on CodePen.

CSS object-fit Example

One of the most common scenarios you’ll see object-fit being used is in image grids, in which each image needs to be the same size. In these cases, you can use object-fit to resize images of different sizes to fit in equal-sized boxes without warping the images.

See the Pen css object fit: grid example by HubSpot (@hubspot) on CodePen.

Make your images look professional with CSS.

Personally, working through the process of implementing “object-fit” reminded me of arranging photos in a photo album. Just as you would carefully adjust each picture to fit neatly within its allotted space while keeping the essence of the image intact, “object-fit” lets you achieve similar harmony in web design.

Now, it’s time for you to start building.