The object-fit property specifies how the contents of a replaced element should be fitted to the box established by its used height and width.
What Is A Replaced Element?
A replaced element is an element whose dimensions and content are defined outside the scope of CSS. Replaced elements often have intrinsic dimensions—the width and height as defined by the element itself, not imposed by the surroundings or defined in CSS. For example, a bitmap image has an intrinsic width and an intrinsic height specified in absolute units, and from which the intrinsic ratio can be determined.
Dudley Storey puts it nicely when he says that ‘another way of thinking of replaced elements is “any tag that has its content replaced by an outside source”. <img> and <video> are obvious examples’.
Other examples of replaced elements are embedded documents, <textarea>s and <input> elements.
Sizing Replaced Elements Using object-fit
Sometimes, you may want or need to have all images (or videos, or inputs, etc.) on a page have the same height and width values. An example of this is avatar images in user profiles or testimonials.
The images you end up using on the page may not have the same dimensions, let alone the same aspect ratio. This is particularly common in applications where the user gets to upload and use their own images that need to be made to fit into specific spots with predefined dimesions.
Using the object-fit property, you can fit the contents of an image into the dimensions you specify in your style sheet.
The contents can be set to scale up or down, shrink or stretch as necessary to fit into the width and height you specify, using the different values of the property.
See the Values section below for a list of values and a visual illustration of the different values’ effects.
Trivia & Notes
The way the object-fit property sizes the contents of an element is very similar to the way the preserveAspectRatio attribute sizes elements in SVG using the <meetOrSlice> parameter. You can read more about how preserveAspectRatio works in SVG in this article.
After the contents of the image have been sized with object-fit, you can position them inside the image using the object-position property. The object-position property works similar to the way the <align> parameter of the preserveAspectRatio works in SVG. Refer to the object-position property’s entry for more information.
Official Syntax
-
Syntax:
object-fit: fill | contain | cover | none | scale-down - Initial: fill
- Applies To: replaced elements
- Animatable: no
Values
- fill
-
The replaced element’s content is sized (scaled up or down, stretched or shrunk) to fill the element’s content box defined using the
widthandheightproperties. The aspect ratio of the content is not preserved while it is sized to fill the element. - contain
- The aspect ratio of the replaced element’s content is preserved, and it is scaled up as much as possible while remaining contained within the boundaries of the element, defined by its height and width.
- cover
- The aspect ratio of the replaced element’s content is preserved, and it is scaled up just enough to fill the element’s entire content box defined by the width and height.
- none
- The replaced content is not resized to fit inside the element’s content box.
- scale-down
-
Size the content as if
noneorcontainwere specified, whichever would result in a smaller concrete object size.According to the specification: The concrete object size is the result of combining an object’s intrinsic dimensions and specified size with the default object size of the context it’s used in, producing a rectangle with a definite width and height.
The following image shows the different object-fit values as applied to an image whose aspect ratio is different from the aspect ratio of the element that is referencing it (the <img> tag):
object-fit property in action.Notes
If the content does not completely fill the replaced element’s content box, the unfilled space shows the replaced element’s background—i.e. the element’s container.
Also, Since replaced elements always clip their contents to the content box, the content will never overflow.
Examples
The following example sets the dimensions of an <img> element, and then uses the object-fit property to fit the contents of that image (the referenced image in the src attribute) to these dimensions:
.bio--avatar {
width: 5em;
height: 5em;
object-fit: cover;
}
Live Demo
View this demo on the Codrops PlaygroundBrowser Support
CSS3 object-fit/object-position
Method of specifying how an object (image or video) should fit inside its box. object-fit options include "contain" (fit according to aspect ratio), "fill" (stretches object to fill) and "cover" (overflows box but maintains ratio), where object-position allows the object to be repositioned like background-image does.
W3C Candidate Recommendation
Supported from the following versions:
Desktop
- 32
- 36
- No
- 19
- 10
Mobile / Tablet
- 10
- 4.4
- all*
- 131
- 132
