<!DOCTYPE html>
<html lang="en" class="dark" data-page-mode="none">
<head>
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>Cover vs Contain Modes - Sanity Image</title>
<meta name="description" content="Learn the difference between cover and contain modes and when to use each one"/>
</head>
<body>
<div class="relative mx-auto flex min-h-screen w-full flex-col items-stretch">
<header>
<div><h1 class="text-3xl font-bold leading-[1.2] -tracking-[.019em] text-gray-950 [overflow-wrap:anywhere] dark:text-white md:text-4xl md:leading-200 [overflow-wrap:anywhere] font-bold">Cover vs Contain Modes</h1></div>
<div class="mt-2 text-lg prose prose-gray dark:prose-invert"><p>Learn the difference between cover and contain modes and when to use each one</p></div>
</header>
<div class="mdx-content relative mt-8 mb-14 prose prose-gray dark:prose-invert [contain:inline-size] isolate" data-page-title="Cover vs Contain Modes" data-page-href="/guides/modes" id="content">
<span data-as="p">The <code>mode</code> prop controls how <code>SanityImage</code> handles aspect ratio changes when you specify both <code>width</code> and <code>height</code>. Understanding the difference between <code>cover</code> and <code>contain</code> is essential for getting the exact image behavior you need.</span>
<h2 class="flex whitespace-pre-wrap group font-semibold" id="the-two-modes"><span class="cursor-pointer">The Two Modes</span></h2>
<h3 class="flex whitespace-pre-wrap group font-semibold" id="contain-mode-default"><span class="cursor-pointer">Contain Mode (Default)</span></h3>
<span data-as="p"><strong>Contain</strong> mode treats the dimensions you provide as boundaries, resizing the image to fit inside of them. The output image will match the aspect ratio of the original image—no cropping will occur.</span>
<div class="code-block mt-5 mb-8 not-prose rounded-2xl relative group min-w-0 text-gray-950 dark:text-gray-50 codeblock-light border border-gray-950/10 dark:border-white/10 dark:twoslash-dark bg-transparent dark:bg-transparent" numberOfLines="8" language="tsx"><div data-floating-buttons="true" class="absolute top-3 right-4 flex items-center gap-1.5"><div class="z-10 relative select-none"><button class="h-[26px] w-[26px] flex items-center justify-center rounded-md backdrop-blur peer group/copy-button" data-testid="copy-code-button" aria-label="Copy the contents from the code block"></button><div aria-hidden="true" class="absolute -top-3 left-1/2 transform whitespace-nowrap -translate-x-1/2 -translate-y-1/2 peer-hover:opacity-100 opacity-0 text-tooltip-foreground rounded-lg px-1.5 py-0.5 text-xs bg-primary-dark">Copy</div></div></div><div class="w-0 min-w-full max-w-full py-3.5 px-4 h-full dark:bg-codeblock relative text-sm leading-6 children:!my-0 children:!shadow-none children:!bg-transparent transition-[height] duration-300 ease-in-out code-block-background [&_*]:ring-0 [&_*]:outline-0 [&_*]:focus:ring-0 [&_*]:focus:outline-0 rounded-2xl bg-white overflow-x-auto scrollbar-thin scrollbar-thumb-rounded scrollbar-thumb-black/15 hover:scrollbar-thumb-black/20 active:scrollbar-thumb-black/20 dark:scrollbar-thumb-white/20 dark:hover:scrollbar-thumb-white/25 dark:active:scrollbar-thumb-white/25" data-component-part="code-block-root" tabindex="0" style="font-variant-ligatures:none;height:auto;background-color:#ffffff;--shiki-dark-bg:#0B0C0E"><div class="font-mono whitespace-pre leading-6"><pre class="shiki shiki-themes github-light-default dark-plus" style="background-color:#ffffff;--shiki-dark-bg:#0B0C0E;color:#1f2328;--shiki-dark:#D4D4D4" language="tsx"><code language="tsx" numberOfLines="8"><span class="line"><span style="color:#1F2328;--shiki-dark:#808080"><</span><span style="color:#116329;--shiki-dark:#4EC9B0">SanityImage</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> id</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#CF222E;--shiki-dark:#569CD6">{</span><span style="color:#1F2328;--shiki-dark:#9CDCFE">image</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">.</span><span style="color:#1F2328;--shiki-dark:#9CDCFE">_id</span><span style="color:#CF222E;--shiki-dark:#569CD6">}</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> baseUrl</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#0A3069;--shiki-dark:#CE9178">"https://cdn.sanity.io/images/abcd1234/production/"</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> width</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#CF222E;--shiki-dark:#569CD6">{</span><span style="color:#0550AE;--shiki-dark:#B5CEA8">500</span><span style="color:#CF222E;--shiki-dark:#569CD6">}</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> height</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#CF222E;--shiki-dark:#569CD6">{</span><span style="color:#0550AE;--shiki-dark:#B5CEA8">300</span><span style="color:#CF222E;--shiki-dark:#569CD6">}</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> mode</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#0A3069;--shiki-dark:#CE9178">"contain"</span><span style="color:#6E7781;--shiki-dark:#6A9955"> // or omit, as this is the default</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> alt</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#0A3069;--shiki-dark:#CE9178">"Product image"</span></span>
<span class="line"><span style="color:#1F2328;--shiki-dark:#808080">/></span></span>
</code></pre></div></div><div data-fade-overlay="true" aria-hidden="true" style="--fade-color-light:#ffffff;--fade-color-dark:#0B0C0E"></div></div>
<span data-as="p">With contain mode, if your original image is 1200×800 (3:2 ratio) and you request 500×300 (5:3 ratio), the image will be resized to fit within those boundaries while maintaining its 3:2 aspect ratio.</span>
<h3 class="flex whitespace-pre-wrap group font-semibold" id="cover-mode"><span class="cursor-pointer">Cover Mode</span></h3>
<span data-as="p"><strong>Cover</strong> mode treats the dimensions you provide as a container, resizing the image to completely fill the dimensions. The output image will match the aspect ratio of the dimensions you provide.</span>
<div class="code-block mt-5 mb-8 not-prose rounded-2xl relative group min-w-0 text-gray-950 dark:text-gray-50 codeblock-light border border-gray-950/10 dark:border-white/10 dark:twoslash-dark bg-transparent dark:bg-transparent" numberOfLines="8" language="tsx"><div data-floating-buttons="true" class="absolute top-3 right-4 flex items-center gap-1.5"><div class="z-10 relative select-none"><button class="h-[26px] w-[26px] flex items-center justify-center rounded-md backdrop-blur peer group/copy-button" data-testid="copy-code-button" aria-label="Copy the contents from the code block"></button><div aria-hidden="true" class="absolute -top-3 left-1/2 transform whitespace-nowrap -translate-x-1/2 -translate-y-1/2 peer-hover:opacity-100 opacity-0 text-tooltip-foreground rounded-lg px-1.5 py-0.5 text-xs bg-primary-dark">Copy</div></div></div><div class="w-0 min-w-full max-w-full py-3.5 px-4 h-full dark:bg-codeblock relative text-sm leading-6 children:!my-0 children:!shadow-none children:!bg-transparent transition-[height] duration-300 ease-in-out code-block-background [&_*]:ring-0 [&_*]:outline-0 [&_*]:focus:ring-0 [&_*]:focus:outline-0 rounded-2xl bg-white overflow-x-auto scrollbar-thin scrollbar-thumb-rounded scrollbar-thumb-black/15 hover:scrollbar-thumb-black/20 active:scrollbar-thumb-black/20 dark:scrollbar-thumb-white/20 dark:hover:scrollbar-thumb-white/25 dark:active:scrollbar-thumb-white/25" data-component-part="code-block-root" tabindex="0" style="font-variant-ligatures:none;height:auto;background-color:#ffffff;--shiki-dark-bg:#0B0C0E"><div class="font-mono whitespace-pre leading-6"><pre class="shiki shiki-themes github-light-default dark-plus" style="background-color:#ffffff;--shiki-dark-bg:#0B0C0E;color:#1f2328;--shiki-dark:#D4D4D4" language="tsx"><code language="tsx" numberOfLines="8"><span class="line"><span style="color:#1F2328;--shiki-dark:#808080"><</span><span style="color:#116329;--shiki-dark:#4EC9B0">SanityImage</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> id</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#CF222E;--shiki-dark:#569CD6">{</span><span style="color:#1F2328;--shiki-dark:#9CDCFE">image</span><span style="color:#1F2328;--shiki-dark:#D4D4D4">.</span><span style="color:#1F2328;--shiki-dark:#9CDCFE">_id</span><span style="color:#CF222E;--shiki-dark:#569CD6">}</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> baseUrl</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#0A3069;--shiki-dark:#CE9178">"https://cdn.sanity.io/images/abcd1234/production/"</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> width</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#CF222E;--shiki-dark:#569CD6">{</span><span style="color:#0550AE;--shiki-dark:#B5CEA8">500</span><span style="color:#CF222E;--shiki-dark:#569CD6">}</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> height</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#CF222E;--shiki-dark:#569CD6">{</span><span style="color:#0550AE;--shiki-dark:#B5CEA8">300</span><span style="color:#CF222E;--shiki-dark:#569CD6">}</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> mode</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#0A3069;--shiki-dark:#CE9178">"cover"</span></span>
<span class="line"><span style="color:#0550AE;--shiki-dark:#9CDCFE"> alt</span><span style="color:#CF222E;--shiki-dark:#D4D4D4">=</span><span style="color:#0A3069;--shiki-dark:#CE9178">"Product image"</span></span>
<span class="line"><span style="color:#1F2328;--shiki-dark:#808080">/></span></span>
</code></pre></div></div><div data-fade-overlay="true" aria-hidden="true" style="--fade-color-light:#ffffff;--fade-color-dark:#0B0C0E"></div></div>
<span data-as="p">With cover mode, if your original image is 1200×800 (3:2 ratio) and you request 500×300 (5:3 ratio), the image will be cropped to exactly 500×300 to match your requested aspect ratio.</span>
<h2 class="flex whitespace-pre-wrap group font-semibold" id="choosing-the-right-mode"><span class="cursor-pointer">Choosing the Right Mode</span></h2>
<span data-as="p">Use <strong>contain</strong> when:</span>
<ul>
<li>You want to preserve the full image without any cropping</li>
<li>The image might have a different aspect ratio than the display area</li>
<li>You are displaying photos where every part of the image matters</li>
</ul>
<span data-as="p">Use <strong>cover</strong> when:</span>
<ul>
<li>You need the image to fill a specific area completely</li>
<li>Some cropping is acceptable</li>
<li>You are creating thumbnails or hero images with fixed dimensions</li>
</ul>
<h2 class="flex whitespace-pre-wrap group font-semibold" id="next-steps"><span class="cursor-pointer">Next Steps</span></h2>
<div class="columns card-group prose dark:prose-dark grid gap-x-4 sm:grid-cols-2"><a class="card block font-normal group relative my-2 ring-2 ring-transparent rounded-2xl bg-white dark:bg-background-dark border border-gray-950/10 dark:border-white/10 overflow-hidden w-full cursor-pointer hover:!border-primary dark:hover:!border-primary-light" href="/guides/styling"><div class="px-6 py-5 relative" data-component-part="card-content-container"><div class="h-6 w-6 fill-gray-800 dark:fill-gray-100 text-gray-800 dark:text-gray-100" data-component-part="card-icon"></div><div class="w-full"><h2 class="not-prose font-semibold text-base text-gray-800 dark:text-white mt-4" contentEditable="false" data-component-part="card-title">Image Styling</h2><div class="prose mt-1 font-normal text-base leading-6 text-gray-600 dark:text-gray-400" data-component-part="card-content"><span data-as="p">Learn CSS best practices for responsive images</span></div></div></div></a><a class="card block font-normal group relative my-2 ring-2 ring-transparent rounded-2xl bg-white dark:bg-background-dark border border-gray-950/10 dark:border-white/10 overflow-hidden w-full cursor-pointer hover:!border-primary dark:hover:!border-primary-light" href="/guides/groq-queries"><div class="px-6 py-5 relative" data-component-part="card-content-container"><div class="h-6 w-6 fill-gray-800 dark:fill-gray-100 text-gray-800 dark:text-gray-100" data-component-part="card-icon"></div><div class="w-full"><h2 class="not-prose font-semibold text-base text-gray-800 dark:text-white mt-4" contentEditable="false" data-component-part="card-title">GROQ Queries</h2><div class="prose mt-1 font-normal text-base leading-6 text-gray-600 dark:text-gray-400" data-component-part="card-content"><span data-as="p">Fetch hotspot and crop data from Sanity</span></div></div></div></a></div>
</div>
<div id="pagination" class="grid lg:grid-cols-2 gap-4"><a class="border border-gray-200/70 dark:border-gray-800/70 group flex items-center rounded-xl py-3 px-4 hover:border-gray-300 dark:hover:border-gray-700 justify-start" href="/quickstart"><div class="space-y-1"><div class="font-medium text-gray-900 dark:text-gray-200">Quick start</div><div class="flex items-center text-sm text-gray-500 dark:text-gray-500 group-hover:text-gray-600 dark:group-hover:text-gray-400 gap-x-1"><span class="font-medium">Previous</span></div></div></a><a class="border border-gray-200/70 dark:border-gray-800/70 group flex items-center rounded-xl py-3 px-4 hover:border-gray-300 dark:hover:border-gray-700 justify-end" href="/guides/styling"><div class="space-y-1"><div class="font-medium text-gray-900 dark:text-gray-200 text-right">Image Styling Guide</div><div class="flex items-center text-sm text-gray-500 dark:text-gray-500 group-hover:text-gray-600 dark:group-hover:text-gray-400 gap-x-1 flex-row-reverse"><span class="font-medium">Next</span></div></div></a></div>
</div>
</body>
</html>