# Image

> Reference for <Recipe.Image>, which renders the recipe's image as an img element or with your own image component.

Source: https://recipe-book.siraj.page/reference/react/image/

`<Recipe.Image>` renders the recipe's image as an `<img>`, with the recipe's name as its alt text, and renders nothing when the recipe has no `image`, or one that is empty or only whitespace. It can render another image component instead, such as Next.js's `Image`. It must be inside [`<Recipe.Root>`](https://recipe-book.siraj.page/reference/react/root.md).

[Try the live demo of Recipe.Image](https://recipe-book.siraj.page/reference/react/image/)

The demo's image is [decorative](https://recipe-book.siraj.page/reference/react/image.md#decorative-images), with `alt=""`, because the recipe's name is the heading below it.

## `Image`

```tsx
import { parseRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'

const result = parseRecipe({
  name: 'Buttermilk pancakes',
  image: '/images/pancakes.jpg',
  ingredients: [{ name: 'all-purpose flour', quantity: '1 ½ cups' }],
  steps: ['Whisk the dry ingredients in a large bowl.'],
})
if (!result.success) throw result.error
const recipe = result.data

export function RecipeHero() {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Image className="hero" />
    </Recipe.Root>
  )
}
```

`RecipeHero` renders:

```html
<img class="hero" src="/images/pancakes.jpg" alt="Buttermilk pancakes" data-recipe-image=""/>
```

A `ref` reaches the `<img>` element, and stays `null` when the recipe has no image, or one that is empty or only whitespace. Style it with `className`, or select the `data-recipe-image` attribute, which it always sets. [Style a recipe](https://recipe-book.siraj.page/guides/style-a-recipe.md#data-attributes) lists every data attribute that the parts set.

| Name  | Type                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `as`  | `ElementType \| undefined` | A custom image component to render instead of `<img>`, such as Next.js's `Image`. Its `src` and `alt` props must take a string, and its other required props are required on `<Recipe.Image>`, or one member's when its props are a union. See [Render another component](https://recipe-book.siraj.page/reference/react/image.md#render-another-component). Defaults to `'img'`.                                                                                   |
| `src` | `string \| undefined`      | Replaces the recipe's `image`, such as with a CDN URL; nothing renders when the recipe has no `image`, or one that is empty or only whitespace, even with `src`. With `as`, its type is that component's `src` type, such as `string \| StaticImport` for Next.js's `Image`. If that component's props are a union, `src` must fit the member the other props fit, and a member whose `src` doesn't take a string needs it, since the recipe's `image` is a string. |
| `alt` | `string \| undefined`      | The alt text. Defaults to the recipe's `name`. Pass `''` for a [decorative image](https://recipe-book.siraj.page/reference/react/image.md#decorative-images). See [Choose alt text](https://recipe-book.siraj.page/guides/make-a-recipe-accessible.md#choose-alt-text).                                                                                                                                                                                             |

Any other prop of the `<img>`, or of the `as` component, passes through unchanged, such as `className`, `width`, `height`, or `loading`. `@recipe-book/react` exports the props type as `RecipeImageProps`; see [Type a wrapper](https://recipe-book.siraj.page/reference/react/image.md#type-a-wrapper).

On React 19, a server render also preloads the image: React adds a `<link rel="preload" as="image">` for it to the page, unless the `<img>` has `loading="lazy"` or `fetchPriority="low"`, sits inside a `<picture>` or `<noscript>`, or has a `data:` URL. React 18 doesn't, but from Next.js 13.4.15 the App Router preloads the image with React 18 too, because it renders with its own build of React. Through Next.js 14, that build also preloads an image inside a `<noscript>`, and on 13.4, inside a `<picture>`. From Next.js 15, the App Router sends the preload as a `Link` response header instead when it renders the image before it starts the response: on a page it renders on request, or, from Next.js 16, in the part of a page that `cacheComponents: true` prerenders. From 15.2, an `<img>` with a `srcSet` keeps the tag. The Pages Router keeps the tag for every image, even on a page with `getServerSideProps`. Pass `loading="lazy"` for an image below the fold.

## Decorative images

When text next to the image already names the recipe, pass `alt=""` so screen readers skip the image:

```tsx {7-8}
import type { ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'

export function RecipeHeader({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Image alt="" />
      <h1>{recipe.name}</h1>
    </Recipe.Root>
  )
}
```

```html
<img src="/images/pancakes.jpg" alt="" data-recipe-image=""/><h1>Buttermilk pancakes</h1>
```

## Render another component

The `as` component receives `src`, `alt`, `data-recipe-image`, the `ref`, and your other props. `<Recipe.Image>` takes that component's props, so TypeScript checks them against it, and the `ref` has that component's ref type. `<Recipe.Image>` takes `as`, not [`asChild`](https://recipe-book.siraj.page/reference/react/system-toggle.md#render-your-own-elements), so a component such as Next.js's `Image` gets `src` and `alt` from the recipe. Use `as` to render Next.js's `Image`:

```tsx {8}
import type { ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
import NextImage from 'next/image'

export function RecipeHero({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Image as={NextImage} width={1200} height={800} preload />
    </Recipe.Root>
  )
}
```

With Next.js's default image settings, `RecipeHero` renders:

```html
<img alt="Buttermilk pancakes" data-recipe-image="" width="1200" height="800" decoding="async" data-nimg="1" style="color:transparent" srcSet="/_next/image?url=%2Fimages%2Fpancakes.jpg&amp;w=1200&amp;q=75 1x, /_next/image?url=%2Fimages%2Fpancakes.jpg&amp;w=3840&amp;q=75 2x" src="/_next/image?url=%2Fimages%2Fpancakes.jpg&amp;w=3840&amp;q=75"/>
```

`preload` also adds a `<link rel="preload" as="image">` to the page's `<head>`. Before Next.js 16, pass `priority` instead, because `preload` fails `next build`'s type check there. On Next.js 15, `priority` renders the same `<img>` and `<link>`, though before 15.2 the App Router sends the `<link>` as a `Link` header on a page it renders on request. On 13.4.11 through 14, both also get `fetchpriority="high"`. On 13.3 through 13.4.10, the `<img>` does, but the App Router renders no `<link>`. Next.js's `Image` forwards the `ref` to its `<img>`.

Your own component works the same way. A Server Component can pass only a Client Component as `as`: one from a file that starts with `'use client'`, as Next.js's `Image` is. `RecipeHero` has no `'use client'`, so in the App Router it renders on the server, and your component needs its own file:

cdn-image.tsx
```tsx title="cdn-image.tsx" {1}
'use client'

import type { ComponentProps } from 'react'

const widths = [640, 1280, 1920]

function cdn(src: string, width: number) {
  return `https://cdn.example.com/?url=${encodeURIComponent(src)}&w=${width}`
}

export function CdnImage({
  src,
  ...props
}: ComponentProps<'img'> & { src: string }) {
  return (
    <img
      {...props}
      src={cdn(src, 1280)}
      srcSet={widths.map((width) => `${cdn(src, width)} ${width}w`).join(', ')}
    />
  )
}
```

recipe-hero.tsx
```tsx title="recipe-hero.tsx" {3,8}
import type { ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
import { CdnImage } from './cdn-image'

export function RecipeHero({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Image as={CdnImage} width={1200} height={800} />
    </Recipe.Root>
  )
}
```

If you define `CdnImage` in `recipe-hero.tsx` instead, the render fails, and `next dev` logs:

```txt
Error: Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server". Or maybe you meant to call this function rather than return it.
  <... as={function CdnImage} width=... height=...>
          ^^^^^^^^^^^^^^^^^^^
```

A Client Component can pass a component defined anywhere.

## Type a wrapper

`RecipeImageProps<C>` is the props of `C` without its `ref`, with `src` and `alt` optional, plus `as`. If `C`'s props are a union, a member whose `src` doesn't take a string still needs `src`, since the recipe's `image` is a string. If `C` is a union of components, such as `typeof NextImage | typeof CdnImage`, it's every component's props, with values every component takes, since either can render. With no type argument, `C` is `'img'`. So `RecipeImageProps<typeof NextImage>` types a wrapper that takes what `<Recipe.Image as={NextImage}>` takes:

```tsx {4}
import * as Recipe from '@recipe-book/react'
import NextImage from 'next/image'

export function Hero(props: Recipe.RecipeImageProps<typeof NextImage>) {
  return <Recipe.Image {...props} as={NextImage} className="hero" />
}
```

`<Hero width={1200} height={800} preload />` and `<Hero fill sizes="100vw" />` type-check. A misspelled prop, or a `src` that Next.js's `Image` doesn't take, doesn't.

## Errors

Throws [`missing_parent`](https://recipe-book.siraj.page/errors/missing_parent.md) when it isn't inside `<Recipe.Root>`:

```txt
RecipeBookError: <Recipe.Image> must be rendered inside <Recipe.Root>.
See https://recipe-book.siraj.page/errors/missing_parent/
```

## Named imports

To import `<Recipe.Image>` by name, import `Image`. If the name clashes with one of yours, alias it, as in `import { Image as RecipeImage } from '@recipe-book/react'`.
