Codectionary / Developer documentation / CSS

object-fit and object-position

object-fit controls how a replaced element's content (like an <img> or <video>) is resized to fit its box, similar to background-size but for actual media elements. cover crops to fill the box, contain scales to fit entirely within it, and object-position controls which part of the content stays visible when cropping occurs.

Syntax

object-fit: cover | contain | fill;
object-position: value;

Examples

object-fit: cover for Consistent Thumbnails

Filling a fixed-size box without distorting the image's proportions.

/* Demo setup: sizing, structure or neutral surfaces. */
.thumbnail{border:2px solid #a16207;max-width:100%}

.thumbnail {
  width: 300px;
  height: 200px;
  object-fit: cover; /* fills the box completely, cropping as needed */
}
  1. The source illustration has a wider aspect ratio than the target box.
  2. cover fills the box without distorting the picture, cropping part of it as necessary.
  3. Change to contain and compare which parts of the sun and mountains stay visible.
HTML used by this example
<img class="thumbnail" src="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22240%22%20viewBox%3D%220%200%20480%20240%22%3E%3Crect%20width%3D%22480%22%20height%3D%22240%22%20fill%3D%22%23e0f2fe%22%2F%3E%3Ccircle%20cx%3D%22365%22%20cy%3D%2255%22%20r%3D%2230%22%20fill%3D%22%23fbbf24%22%2F%3E%3Cpath%20d%3D%22M0%20240%20135%2055%20280%20240%22%20fill%3D%22%230f766e%22%2F%3E%3Cpath%20d%3D%22m150%20240%20155-150%20175%20150%22%20fill%3D%22%235b21b6%22%2F%3E%3Ctext%20x%3D%2220%22%20y%3D%22218%22%20fill%3D%22white%22%20font-size%3D%2224%22%20font-family%3D%22sans-serif%22%3EOriginal%20landscape%3C%2Ftext%3E%3C%2Fsvg%3E" alt="A sun above green and purple mountains">

object-fit: contain and object-position

Showing an entire image without cropping, and controlling crop focus.

/* Demo setup: sizing, structure or neutral surfaces. */
.preview-row{display:flex;flex-wrap:wrap;gap:1rem;align-items:flex-start;margin-block:1rem}.logo,.portrait-crop{width:200px;height:100px;border:2px solid #a16207}.portrait-crop{width:100px;height:160px}figure{margin:.5rem}

.logo {
  width: 200px;
  height: 100px;
  object-fit: contain; /* shows the whole image, letterboxing if needed */
}

.portrait-crop {
  object-fit: cover;
  object-position: top; /* keeps the top of the image visible when cropping */
}
  1. Both examples use the same source image so fitting is the variable.
  2. contain preserves the whole image with unused space where the ratios differ.
  3. The portrait crop fills its taller box and aligns the cropped image to the requested position.
HTML used by this example
<div class="preview-row"><figure><img class="logo" src="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22240%22%20viewBox%3D%220%200%20480%20240%22%3E%3Crect%20width%3D%22480%22%20height%3D%22240%22%20fill%3D%22%23e0f2fe%22%2F%3E%3Ccircle%20cx%3D%22365%22%20cy%3D%2255%22%20r%3D%2230%22%20fill%3D%22%23fbbf24%22%2F%3E%3Cpath%20d%3D%22M0%20240%20135%2055%20280%20240%22%20fill%3D%22%230f766e%22%2F%3E%3Cpath%20d%3D%22m150%20240%20155-150%20175%20150%22%20fill%3D%22%235b21b6%22%2F%3E%3Ctext%20x%3D%2220%22%20y%3D%22218%22%20fill%3D%22white%22%20font-size%3D%2224%22%20font-family%3D%22sans-serif%22%3EOriginal%20landscape%3C%2Ftext%3E%3C%2Fsvg%3E" alt="A sun above green and purple mountains"><figcaption>contain: full illustration</figcaption></figure><figure><img class="portrait-crop" src="data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20width%3D%22480%22%20height%3D%22240%22%20viewBox%3D%220%200%20480%20240%22%3E%3Crect%20width%3D%22480%22%20height%3D%22240%22%20fill%3D%22%23e0f2fe%22%2F%3E%3Ccircle%20cx%3D%22365%22%20cy%3D%2255%22%20r%3D%2230%22%20fill%3D%22%23fbbf24%22%2F%3E%3Cpath%20d%3D%22M0%20240%20135%2055%20280%20240%22%20fill%3D%22%230f766e%22%2F%3E%3Cpath%20d%3D%22m150%20240%20155-150%20175%20150%22%20fill%3D%22%235b21b6%22%2F%3E%3Ctext%20x%3D%2220%22%20y%3D%22218%22%20fill%3D%22white%22%20font-size%3D%2224%22%20font-family%3D%22sans-serif%22%3EOriginal%20landscape%3C%2Ftext%3E%3C%2Fsvg%3E" alt="A sun above green and purple mountains"><figcaption>cover with top alignment</figcaption></figure></div>

Parameters and values

  • cover (keyword): Fills the box completely, cropping the content as needed
  • contain (keyword): Scales to fit entirely within the box, no cropping
  • fill (keyword): Stretches to fill the box exactly, ignoring original proportions (default)
  • object-position (position): Controls which part of the content remains visible when cropped

Best practices

  • Use object-fit: cover for consistent thumbnail grids where images come in varying original proportions
  • Use object-fit: contain for logos or images that must never be cropped, even if it means empty space around them
  • Combine object-position with cover to control exactly which part of an image stays visible when cropping occurs, like keeping faces in frame
  • Remember object-fit only applies to replaced elements like <img>, <video>, and <canvas> - it has no effect on regular elements like <div>

Browser compatibility

chrome
Yes
firefox
Yes
safari
Yes
edge
Yes

These are the existing reference’s support labels, not tested minimum versions. Individual values and APIs can have different support. Check the linked specification before choosing a browser target.

CSS specifications (modules)

Specifications & further reading