Recipe Book0.6.0

4.2React reference

Image

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

§ 4.25 min readView as Markdown

<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>.

Buttermilk pancakes

The demo’s image is decorative, 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 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. 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. See 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.

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
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, 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
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
'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
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:

Text
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
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 when it isn’t inside <Recipe.Root>:

Text
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'.

Contents