---
title: Image Optimization with SanityPicture
impact: CRITICAL
impactDescription: project-specific image component for Sanity CMS
tags: image, sanity, picture, video, optimization, custom
---

# Image Optimization with SanityPicture

Always use `SanityPicture` for images from Sanity CMS. Never use raw `<img>` tags.

## Basic Usage

```tsx
import { SanityPicture } from '@local/ui/components'

// Above the fold — prioritize
<SanityPicture image={data.image} priority />

// Below the fold — lazy load (default)
<SanityPicture image={data.image} />
```

## Art Direction (Different Aspect Ratios)

When the design specifies a fixed aspect ratio, pass `desktopSize` and `mobileSize`:

```tsx
// Fixed aspect ratio per breakpoint
<SanityPicture
  image={data.image}
  desktopSize={{ width: 1440, height: 800 }}
  mobileSize={{ width: 768, height: 1024 }}
  priority
/>

// Width only (preserves original aspect ratio)
<SanityPicture
  image={data.image}
  desktopSize={{ width: 1440 }}
  mobileSize={{ width: 768 }}
/>
```

## Different Desktop/Mobile Images

```tsx
<SanityPicture
  image={data.desktopImage}
  imageMobile={data.mobileImage}
  desktopSize={{ width: 1440, height: 800 }}
  mobileSize={{ width: 768, height: 1024 }}
/>
```

## Fill Mode (Backgrounds)

```tsx
<SanityPicture
  image={data.backgroundImage}
  alt=""
  fill
  priority
  className="absolute inset-0"
/>
```

## VideoOrImage (Mixed Media)

For media that can be either video or image (backgrounds, hero sections):

```tsx
import { VideoOrImage } from '@local/ui/components'

<VideoOrImage
  media={data.backgroundMedia}
  desktopSize={{ width: 1920, height: 1080 }}
  mobileSize={{ width: 768, height: 1024 }}
  priority
/>
```

## Sizing Guidelines

| Context          | `desktopSize` width | `mobileSize` width |
| ---------------- | ------------------- | ------------------ |
| Full-width hero  | 1920                | 768                |
| Card image       | 600                 | 400                |
| Square thumbnail | 300                 | 200                |

## Size Type Reference

```typescript
type Size = {
  width: number
  height?: number // Optional — omit to preserve original aspect ratio
}
```