Recipe Book0.6.0

4.6React reference

Steps

Reference for <Recipe.Steps>, <Recipe.StepList>, <Recipe.Step>, <Recipe.StepName>, <Recipe.StepText>, and <Recipe.ConvertedStepText>, which render a recipe's steps.

§ 4.619 min readView as Markdown

Six parts render a recipe’s steps, from the list of sections down to each step’s name and text, numbered in one sequence across the sections.

  1. Whisk the dry ingredients in a large bowl.
  2. Whisk the buttermilk, eggs, and butter, then fold into the dry ingredients.
  3. Cook ¼-cup portions on a buttered griddle, 2–⁠3 minutes per side.

Anatomy

TSX
'use client'

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

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Steps>
        {(section) => (
          <Recipe.StepList section={section}>
            {(step) => (
              <Recipe.Step item={step}>
                <Recipe.StepName /> <Recipe.StepText />
              </Recipe.Step>
            )}
          </Recipe.StepList>
        )}
      </Recipe.Steps>
    </Recipe.Root>
  )
}

Every part must be inside <Recipe.Root>, and <Recipe.StepName>, <Recipe.StepText>, and <Recipe.ConvertedStepText> must be inside a <Recipe.Step>. The rest is optional: <Recipe.StepList> works without <Recipe.Steps>, <Recipe.Step> works without a list part, and a part without children renders its default content. Inside a <Recipe.Checklist>, each step’s default content follows a checkbox, so readers can tick off the steps as they cook.

By default, <Recipe.Steps>, <Recipe.StepList>, and <Recipe.Step> render each step’s text with <Recipe.StepText>, so temperatures are in the reader’s measurement system and each duration is marked with data-recipe-duration. Changing the servings or the system re-renders only those temperatures, not the steps.

Steps

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

const result = parseRecipe({
  name: 'Buttermilk pancakes',
  servings: 4,
  ingredients: [{ name: 'all-purpose flour', quantity: '1 ½ cups' }],
  steps: [
    'Whisk the dry ingredients in a large bowl.',
    {
      title: 'Cook',
      items: [
        'Heat a buttered griddle over medium heat.',
        'Cook ¼-cup portions, 2–3 minutes per side.',
      ],
    },
  ],
})
if (!result.success) throw result.error
const recipe = result.data

export function Method() {
  return (
    <Recipe.Root recipe={recipe}>
      <h2>Method</h2>
      <Recipe.Steps />
    </Recipe.Root>
  )
}

Method renders this HTML, indented here for reading:

HTML
<h2>Method</h2>
<div data-recipe-steps="">
  <div data-recipe-step-section="">
    <ol start="1" data-recipe-step-list="">
      <li id="buttermilk-pancakes-step-1" data-recipe-step=""><span data-recipe-step-text="">Whisk the dry ingredients in a large bowl.</span></li>
    </ol>
  </div>
  <section data-recipe-step-section="">
    <h3>Cook</h3>
    <ol start="2" data-recipe-step-list="">
      <li id="buttermilk-pancakes-step-2" data-recipe-step=""><span data-recipe-step-text="">Heat a buttered griddle over medium heat.</span></li>
      <li id="buttermilk-pancakes-step-3" data-recipe-step=""><span data-recipe-step-text="">Cook ¼-cup portions, <span data-recipe-duration="">2–⁠3 minutes</span> per side.</span></li>
    </ol>
  </section>
</div>

<Recipe.Steps> renders a <div> with one block for each of the recipe’s step sections that has steps. As with <Recipe.Ingredients>, a titled section is a <section> headed by its title, not a region landmark, and an untitled one is a <div>. A section with no steps has no block, title and all, as <Recipe.JsonLd> leaves it out. <Recipe.Steps> renders nothing when no section has steps, so hide a heading above it unless one does.

Name Type Description
headingLevel RecipeHeadingLevel | undefined The heading level of section titles in the default rendering. Defaults to 3, for steps under an <h2> as in the example. See Set heading levels.
checkboxes boolean | undefined Inside a <Recipe.Checklist>, whether each step has a checkbox. Defaults to the checkboxes of a list around it, or to true. See Lists without checkboxes.
children ((section: RecipeSection<RecipeStepItem>) => ReactNode) | undefined Renders each section instead of the default: a <section> headed by the section’s title, or a <div> for an untitled section, around a <Recipe.StepList> of its steps. See Render your own sections.

Any other <div> prop, such as className or aria-label, passes to the <div>, and a ref reaches it. It renders its own content, so it doesn’t take dangerouslySetInnerHTML. Style the parts with className, or select their data-recipe-* attributes. Style a recipe lists every data attribute that the parts set.

Render your own sections

The children function receives a RecipeSection of RecipeStepItems, for every section, including one with no steps. For that section, a <Recipe.StepList> renders nothing, but a heading you render stays: return null when the section’s items is empty to leave it out, as the default does. <Recipe.Steps> renders nothing only when the recipe has no sections. It keys each result by the section’s id, so an element or fragment you return needs no key. If you return an array, each of its elements needs its own key, as in any React list. The file that passes the function starts with 'use client':

TSX
'use client'

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

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Steps>
        {(section) => (
          <details open>
            <summary>{section.title ?? 'Prepare'}</summary>
            <Recipe.StepList section={section} />
          </details>
        )}
      </Recipe.Steps>
    </Recipe.Root>
  )
}

For the recipe in the first example, Method renders:

HTML
<div data-recipe-steps="">
  <details open="">
    <summary>Prepare</summary>
    <ol start="1" data-recipe-step-list="">
      <li id="buttermilk-pancakes-step-1" data-recipe-step=""><span data-recipe-step-text="">Whisk the dry ingredients in a large bowl.</span></li>
    </ol>
  </details>
  <details open="">
    <summary>Cook</summary>
    <ol start="2" data-recipe-step-list="">
      <li id="buttermilk-pancakes-step-2" data-recipe-step=""><span data-recipe-step-text="">Heat a buttered griddle over medium heat.</span></li>
      <li id="buttermilk-pancakes-step-3" data-recipe-step=""><span data-recipe-step-text="">Cook ¼-cup portions, <span data-recipe-duration="">2–⁠3 minutes</span> per side.</span></li>
    </ol>
  </details>
</div>

Without 'use client', Method runs as a Server Component when a page imports it, and rendering fails with the same error as <Recipe.Ingredients>.

StepList

TSX
import type { ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.StepList className="method" />
    </Recipe.Root>
  )
}

For the recipe in the first example, Method renders one list:

HTML
<ol class="method" start="1" data-recipe-step-list="">
  <li id="buttermilk-pancakes-step-1" data-recipe-step=""><span data-recipe-step-text="">Whisk the dry ingredients in a large bowl.</span></li>
  <li id="buttermilk-pancakes-step-2" data-recipe-step=""><span data-recipe-step-text="">Heat a buttered griddle over medium heat.</span></li>
  <li id="buttermilk-pancakes-step-3" data-recipe-step=""><span data-recipe-step-text="">Cook ¼-cup portions, <span data-recipe-duration="">2–⁠3 minutes</span> per side.</span></li>
</ol>

It renders an <ol> with a <Recipe.Step> for each step, or nothing when it has no steps to list, such as for a section with none.

Name Type Description
section RecipeSection<RecipeStepItem> | undefined The section to list, such as the one <Recipe.Steps> passes to its children. Defaults to every step in the recipe.
children ((step: RecipeStepItem) => ReactNode) | undefined Renders each step instead of the default, <Recipe.Step item={step} />. See Render your own steps.
start number | undefined The number of the first item, as on any <ol>. Defaults to the first step’s number. Pass 1 to number each section from 1.
checkboxes boolean | undefined Inside a <Recipe.Checklist>, whether each step has a checkbox. Defaults to the checkboxes of a list around it, or to true. See Lists without checkboxes.

Any other <ol> prop passes to the <ol>, and a ref reaches it. It renders its own content, so it doesn’t take dangerouslySetInnerHTML.

Render your own steps

Pass a function as children from a Client Component, as with <Recipe.Steps>. It receives a RecipeStepItem, and <Recipe.StepList> keys each result by the step’s id. Render a <Recipe.Step> with your own content to keep the <li>. Your content replaces the default children, checkbox included, so inside a <Recipe.Checklist>, place a <Recipe.StepCheckbox> where the box should go. This one labels each checkbox with the step’s number:

TSX
'use client'

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

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Checklist>
        <Recipe.StepList>
          {(step) => (
            <Recipe.Step item={step}>
              <label>
                <Recipe.StepCheckbox /> <span>{`Step ${step.number}`}</span>
              </label>
              <p><Recipe.StepText /></p>
            </Recipe.Step>
          )}
        </Recipe.StepList>
      </Recipe.Checklist>
    </Recipe.Root>
  )
}

For the recipe in the first example, Method renders:

HTML
<ol start="1" data-recipe-step-list="">
  <li id="buttermilk-pancakes-step-1" data-recipe-step=""><label><input autoComplete="off" type="checkbox" data-recipe-step-checkbox=""/> <span>Step 1</span></label><p><span data-recipe-step-text="">Whisk the dry ingredients in a large bowl.</span></p></li>
  <li id="buttermilk-pancakes-step-2" data-recipe-step=""><label><input autoComplete="off" type="checkbox" data-recipe-step-checkbox=""/> <span>Step 2</span></label><p><span data-recipe-step-text="">Heat a buttered griddle over medium heat.</span></p></li>
  <li id="buttermilk-pancakes-step-3" data-recipe-step=""><label><input autoComplete="off" type="checkbox" data-recipe-step-checkbox=""/> <span>Step 3</span></label><p><span data-recipe-step-text="">Cook ¼-cup portions, <span data-recipe-duration="">2–⁠3 minutes</span> per side.</span></p></li>
</ol>

Step

TSX
'use client'

import type { ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
import { useState } from 'react'

export function StepByStep({ recipe }: { recipe: ParsedRecipe }) {
  const [current, setCurrent] = useState(1)
  const count = recipe.steps.reduce((n, section) => n + section.items.length, 0)

  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.StepList>
        {(step) => (
          <Recipe.Step
            item={step}
            aria-current={step.number === current ? 'step' : undefined}
          />
        )}
      </Recipe.StepList>
      <button
        aria-disabled={current === count ? true : undefined}
        onClick={() => current < count && setCurrent(current + 1)}
      >
        Next step
      </button>
    </Recipe.Root>
  )
}

For the recipe in the first example, StepByStep marks the first step as current:

HTML
<ol start="1" data-recipe-step-list="">
  <li id="buttermilk-pancakes-step-1" aria-current="step" data-recipe-step=""><span data-recipe-step-text="">Whisk the dry ingredients in a large bowl.</span></li>
  <li id="buttermilk-pancakes-step-2" data-recipe-step=""><span data-recipe-step-text="">Heat a buttered griddle over medium heat.</span></li>
  <li id="buttermilk-pancakes-step-3" data-recipe-step=""><span data-recipe-step-text="">Cook ¼-cup portions, <span data-recipe-duration="">2–⁠3 minutes</span> per side.</span></li>
</ol>
<button>Next step</button>

Two clicks on Next step move aria-current to step 3. The button then has aria-disabled rather than disabled, so it keeps the keyboard focus.

<Recipe.Step> renders an <li>. Without children, or when children is null, undefined, true, or false, it renders its default children. A step written as { name: 'Autolyse', text: 'Mix the flour and water, then rest for 1 hour.' } renders:

HTML
<li id="buttermilk-pancakes-autolyse" data-recipe-step=""><b data-recipe-step-name="">Autolyse</b> <span data-recipe-step-text="">Mix the flour and water, then rest for <time data-recipe-duration="" dateTime="PT3600S">1 hour</time>.</span></li>
Name Type Description
item RecipeStepItem The step to render, with its number.
asChild boolean | undefined Renders the step as its only child instead of an <li>. See Render your own element. Defaults to false.
children ReactNode | undefined The content of the <li>. Defaults to <Recipe.StepName>, then a space if the step has a name other than '', then <Recipe.StepText>. Inside a <Recipe.Checklist>, those follow a <Recipe.StepCheckbox> and a space, in a <label>, unless a list around the step has checkboxes={false}.

Any other <li> prop passes to the <li>, and a ref reaches it. It renders its own content, so it doesn’t take dangerouslySetInnerHTML. Inside a Checklist, the <li> of a ticked step has data-checked, whatever its children.

<Recipe.Step> renders an id: the Root’s idPrefix, then the step’s id, such as buttermilk-pancakes-autolyse above, so the step URLs that <Recipe.JsonLd> writes point at the step. An id prop wins, and so does an asChild child’s id, but the step URL that <Recipe.JsonLd> writes then no longer points at the step. Pass id={undefined}, to the step or to an asChild child, to render none, such as for a step you render twice in one Root, which would otherwise give two elements one id.

To show the text as written, pass <Recipe.StepName /> {step.text} as the children. The step then has no <span data-recipe-step-text>, a temperature written as 350°F stays in Fahrenheit when the reader switches to metric, and its temperatures don’t enable the system toggle. Its durations are plain text, with no <time> or <span data-recipe-duration>. The page is no smaller. Keep a steps page small says why and how to make one smaller.

Render your own element

With asChild, <Recipe.Step> passes its id, data-recipe-step, your other props, and its ref to its only child. Use it for a component that must be the list item itself, such as an animated motion.li. Render an <li> or a component that renders one, so the list keeps its items. Its props and ref merge with the child’s as asChild on the system toggle describes, along with what a function component needs on React 18.

The child’s children are the step’s content. A child whose children are undefined, null, true, or false, such as <motion.li layout />, gets the default children: the step’s name and text, after a checkbox inside a Checklist. Any other children replace them, even '', [], or an empty Fragment, which render nothing. Here, Card stands in for a component like that:

TSX
'use client'

import type { ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
import type { ComponentProps } from 'react'

function Card(props: ComponentProps<'li'>) {
  return <li {...props} />
}

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.StepList>
        {(step) => (
          <Recipe.Step item={step} asChild className="step">
            <Card className="card" />
          </Recipe.Step>
        )}
      </Recipe.StepList>
    </Recipe.Root>
  )
}

For the recipe in the first example, Method renders:

HTML
<ol start="1" data-recipe-step-list="">
  <li class="step card" id="buttermilk-pancakes-step-1" data-recipe-step=""><span data-recipe-step-text="">Whisk the dry ingredients in a large bowl.</span></li>
  <li class="step card" id="buttermilk-pancakes-step-2" data-recipe-step=""><span data-recipe-step-text="">Heat a buttered griddle over medium heat.</span></li>
  <li class="step card" id="buttermilk-pancakes-step-3" data-recipe-step=""><span data-recipe-step-text="">Cook ¼-cup portions, <span data-recipe-duration="">2–⁠3 minutes</span> per side.</span></li>
</ol>

With anything but one element child, <Recipe.Step> renders its own <li> with those children, or with its default children when they’re undefined, null, true, or false. In development, the first <Recipe.Step> to do this logs a development warning.

StepName

TSX
'use client'

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

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.StepList>
        {(step) => (
          <Recipe.Step item={step}>
            <Recipe.StepName className="step-name" />
            <p><Recipe.StepText /></p>
          </Recipe.Step>
        )}
      </Recipe.StepList>
    </Recipe.Root>
  )
}

For a recipe whose steps are { name: 'Autolyse', text: 'Mix the flour and water, then rest for 1 hour.' } and 'Shape the dough and proof overnight.', Method renders:

HTML
<ol start="1" data-recipe-step-list="">
  <li id="buttermilk-pancakes-autolyse" data-recipe-step=""><b class="step-name" data-recipe-step-name="">Autolyse</b><p><span data-recipe-step-text="">Mix the flour and water, then rest for <time data-recipe-duration="" dateTime="PT3600S">1 hour</time>.</span></p></li>
  <li id="buttermilk-pancakes-step-2" data-recipe-step=""><p><span data-recipe-step-text="">Shape the dough and proof overnight.</span></p></li>
</ol>

<Recipe.StepName> renders the name of the nearest <Recipe.Step> in a <b>, or nothing when the step has no name or its name is ''. It takes no children or dangerouslySetInnerHTML. Any other <b> prop, such as className, passes to the <b>, and a ref reaches it.

StepText

TSX
'use client'

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

function UnitsButton() {
  const { system, setSystem } = Recipe.useRecipe()
  return (
    <button onClick={() => setSystem(system === 'us' ? 'metric' : 'us')}>
      {system === 'us' ? 'Show metric' : 'Show US'}
    </button>
  )
}

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <UnitsButton />
      <Recipe.StepList>
        {(step) => (
          <Recipe.Step item={step}>
            <Recipe.StepName /> <Recipe.StepText />
          </Recipe.Step>
        )}
      </Recipe.StepList>
    </Recipe.Root>
  )
}

For a metric recipe whose steps are 'Preheat oven to 190°C (375°F) or 170°C fan (340°F).' and { name: 'Bake', text: 'Bake for 45 minutes, until a skewer comes out clean.' }, Method renders:

HTML
<button>Show US</button>
<ol start="1" data-recipe-step-list="">
  <li id="buttermilk-pancakes-step-1" data-recipe-step=""> <span data-recipe-step-text="">Preheat oven to <span data-recipe-temperature="">190 °C / 170 °C fan</span>.</span></li>
  <li id="buttermilk-pancakes-bake" data-recipe-step=""><b data-recipe-step-name="">Bake</b> <span data-recipe-step-text="">Bake for <time data-recipe-duration="" dateTime="PT2700S">45 minutes</time>, until a skewer comes out clean.</span></li>
</ol>

Show US changes the temperature to 375 °F / 340 °F fan, the Fahrenheit settings the author wrote. The space between <Recipe.StepName /> and <Recipe.StepText /> is in your JSX, so the unnamed first step starts with a space, while the default children add one only after a name.

<Recipe.StepText> renders the text of the nearest <Recipe.Step> in a <span>, as <Recipe.Step>’s default children do. Each temperature that segmentStepText finds is in a <span data-recipe-temperature>, in °C when Root’s system is 'metric' and in °F when it’s 'us', and it re-renders when the system changes. It shows each duration it finds as written, whatever the system and servings, in a <time data-recipe-duration> whose dateTime is in seconds to the millisecond, so 45 minutes gets dateTime="PT2700S" and 0.25 seconds gets dateTime="PT0.25S". A range, such as 25–30 minutes, is in a <span data-recipe-duration> instead, because an HTML duration can’t be a range. A word joiner (U+2060) follows a dash or tilde between a duration’s ends when a number comes right after it, as in 25–30 minutes, 10–10 minutes, or 25~30 minutes, so the line doesn’t break there, even in Safari 16.4. Copying the text keeps the word joiner. To keep a whole duration on one line, add [data-recipe-duration] { white-space: nowrap } to your CSS. The rest of the text shows as written.

  • A temperature already in the reader’s unit keeps its value, so Cook sous vide at 56.5°C. reads Cook sous vide at 56.5 °C. in metric. A converted temperature that’s an oven setting, one whose segment’s oven is true, rounds to the nearest 10 °C or 25 °F, so Bake at 180°C. reads Bake at 350 °F. in US. Any other converted temperature is in whole degrees, so Roast until it reads 74°C. reads Roast until it reads 165 °F. in US.
  • A setting that the author wrote in both units isn’t converted again. It shows the reading in the reader’s unit and keeps its value, so Bake at 400 degrees F (200 degrees C) reads Bake at 200 °C in metric, and Heat to 37.5 °C (99.5 °F). reads Heat to 99.5 °F. in US.
  • The fan label follows a fan-oven setting, so Heat oven to 190C/170C fan/gas 5. reads Heat oven to 190 °C / 170 °C fan. in metric. With an empty label, labels={labelPack({ fan: '' })}, it renders nothing, and StepText drops the space before it, so that step reads Heat oven to 190 °C / 170 °C.
  • When segmentStepText pairs a conventional setting with a fan setting, the conventional one shows first and the fan one after a slash, whatever order or words the author used, so Heat oven to 200°C (180°C fan). and Heat oven to 180°C fan or 200°C. both read Heat oven to 200 °C / 180 °C fan. in metric.
  • A gas mark that follows a temperature as another way to give the same setting, as in 190C/170C fan/gas 5 or 200°C (gas mark 6), is left out. Everything else, including a gas mark on its own or before a temperature, is shown as authored, so Bake at gas mark 6 (200°C). reads Bake at gas mark 6 (400 °F). in US.
  • A temperature written without a unit, such as Rest at 350°., isn’t found, so it shows as written, unless inferTemperatureUnit reads it.
  • The digits follow Root’s locale, so with locale="ar-EG", Bake at 180°C. reads Bake at ٣٥٠ °F. in US.

A <Recipe.StepText> that shows a temperature counts toward canConvert once it mounts. Recipes that can’t convert says what that means for <Recipe.SystemToggle> on the server and in a view that shows one step at a time.

Name Type Description
inferTemperatureUnit boolean | undefined Whether a temperature written with a degree sign or “degree” or “degrees” but no unit is °F when it’s 275 or more, as with segmentStepText’s option. See Temperatures without a scale.

It takes no children or dangerouslySetInnerHTML. Any other <span> prop, such as className, passes to the outer <span>, and a ref reaches it.

For a step’s text as a string in the reader’s units, such as for a button that copies the recipe, use core’s showStep example, with 'C' when Root’s system is 'metric' and 'F' when it’s 'us'.

Temperatures without a scale

Many US recipes leave out the scale, as in Preheat the oven to 425 degrees. <Recipe.StepText> shows such a temperature as written, since a number such as 180 could be either. To convert the ones of 275 or more as °F, since 275 °C is hotter than most home ovens go, set inferTemperatureUnit:

TSX
'use client'

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

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.StepList>
        {(step) => (
          <Recipe.Step item={step}>
            <Recipe.StepName /> <Recipe.StepText inferTemperatureUnit />
          </Recipe.Step>
        )}
      </Recipe.StepList>
    </Recipe.Root>
  )
}

In metric, Preheat the oven to 425 degrees. then reads Preheat the oven to 220 °C., while Warm the plates at 200°. stays as written. As with segmentStepText, the temperature needs a word such as “at” or “to” before it, “oven” after it, or a reading with a unit that it pairs with, as in Brown 350° (175°C)., which reads Brown 175 °C., so Turn the dial 300 degrees. stays as written too. <Recipe.Step>’s default children don’t set it, so render <Recipe.StepText> yourself to use it.

Keep a steps page small

<Recipe.Steps>, <Recipe.StepList>, and <Recipe.Step> bring in the code that <Recipe.StepText> uses to find durations and to find and convert temperatures, even when your own children leave <Recipe.StepText> out. Where that code matters, list the steps from useRecipe() in your own markup instead:

TSX
'use client'

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

function StepItems() {
  const { steps } = Recipe.useRecipe()
  return (
    <ol>
      {steps
        .flatMap((section) => section.items)
        .map((step) => (
          <li key={step.number}>
            {step.name !== undefined && <b>{step.name}</b>} {step.text}
          </li>
        ))}
    </ol>
  )
}

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Image />
      <StepItems />
    </Recipe.Root>
  )
}

On a page like this, Recipe Book adds about 4 kB of JavaScript, gzipped, under half what it adds to the same page with <Recipe.Steps>. It gives up what the step parts add: each step’s id, the data-recipe-* attributes, the section headings, each list’s start number, asChild, and <Recipe.StepName>. Its temperatures stay as written and don’t enable the system toggle, and its durations are plain text.

ConvertedStepText

TSX
'use client'

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

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe} defaultSystem="us">
      <Recipe.StepList>
        {(step) => (
          <Recipe.Step item={step}>
            <Recipe.StepName /> <Recipe.ConvertedStepText />
          </Recipe.Step>
        )}
      </Recipe.StepList>
    </Recipe.Root>
  )
}

For a metric recipe whose steps are 'Whisk 2 eggs into 250 ml of milk.' and { name: 'Bake', text: 'Bake at 160°C for 40 minutes.' }, Method renders:

HTML
<ol start="1" data-recipe-step-list="">
  <li id="buttermilk-pancakes-step-1" data-recipe-step=""> <span data-recipe-step-text="" data-recipe-converted-step-text="">Whisk 2 eggs into <span data-recipe-quantity="">1 cup</span> of milk.</span></li>
  <li id="buttermilk-pancakes-bake" data-recipe-step=""><b data-recipe-step-name="">Bake</b> <span data-recipe-step-text="" data-recipe-converted-step-text="">Bake at <span data-recipe-temperature="">325 °F</span> for <time data-recipe-duration="" dateTime="PT2400S">40 minutes</time>.</span></li>
</ol>

<Recipe.ConvertedStepText> renders the text of the nearest <Recipe.Step> as <Recipe.StepText> does, and also shows each mass and volume quantity that segmentStepQuantities finds in Root’s measurement system, converting them as the ingredient list does. Each quantity is in a <span data-recipe-quantity>, and it re-renders when the system changes.

  • A quantity already in the reader’s system keeps its text, so Add 200 g of flour. reads as written in metric. So does a quantity the author also wrote in the reader’s system, so Stir in 200 g (7 oz) of cream. reads as written in both systems. That holds for five quantities that restate one another, or six when the last two share a parenthesis, as segmentStepQuantities describes, and the next one can be converted again.
  • Any other quantity is converted with toSystem and written with formatQuantity in Root’s locale and labels, so Add 500 ml of stock. reads Add 2 ⅛ cups of stock. in US, and Add 2 cups of stock. reads Add 473 mL of stock. in metric.
  • Each quantity converts on its own, and quantities side by side aren’t added together, so Add 1 lb 2 oz of beef. reads Add 454 g 57 g of beef. in metric, with each quantity in its own <span data-recipe-quantity>.
  • With Root’s exact, a converted quantity is converted with toSystem’s exact, so it keeps the unit toSystem lands on but not its rounding, as the ingredient list does, so Add 150 ml of milk. reads Add 10 ⅛ tbsp of milk. in US rather than Add 10 tbsp of milk.
  • A quantity in a unit of both systems, such as 1 tbsp, shows as written in both.
  • Quantities follow the system, not the servings. Step text doesn’t say which quantities are the ingredients’, so Pour into a 2 L dish. keeps its 2 L at any servings.
  • Counts, such as 2 eggs, show as written. segmentStepQuantities lists the other text it leaves alone.

Once <Recipe.ConvertedStepText> mounts, a temperature it shows counts toward canConvert, as one in <Recipe.StepText> does, and so does a quantity that one of the systems would convert. So a recipe whose only quantities to convert are in its steps still enables the system toggle. A quantity in a unit of both systems, or one the author wrote in both, doesn’t count.

Its <span> has data-recipe-step-text as well as data-recipe-converted-step-text, so styles for <Recipe.StepText> apply to it. It takes inferTemperatureUnit as <Recipe.StepText> does, and no children or dangerouslySetInnerHTML. Any other <span> prop, such as className, passes to the outer <span>, and a ref reaches it.

The code that finds and converts quantities is only in pages that use <Recipe.ConvertedStepText>.

Errors

<Recipe.Steps>, <Recipe.StepList>, and <Recipe.Step> throw missing_parent with their own names when they aren’t inside <Recipe.Root>:

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

<Recipe.StepName>, <Recipe.StepText>, and <Recipe.ConvertedStepText> throw it when they aren’t inside a <Recipe.Step>:

Text
RecipeBookError: <Recipe.StepText> must be rendered inside <Recipe.Step>.
See https://recipe-book.siraj.page/errors/missing_parent/

<Recipe.StepText> throws invalid_argument for a step with a temperature when Root’s locale isn’t a language tag that Intl accepts, such as 'en_US'. So do <Recipe.Steps>, <Recipe.StepList>, and <Recipe.Step> when they render their default children, because those render <Recipe.StepText>. Custom children without <Recipe.StepText> don’t throw it. <Recipe.ConvertedStepText> throws it for a step with a temperature, or with a quantity it converts, when Root’s locale isn’t one Intl accepts. In a runtime without Intl, no step part throws it for any locale string, even 'en_US', and they write the numbers in English.

<Recipe.Steps> and <Recipe.StepList> call children for each section or step. When children are undefined, null, true, or false, both parts render their defaults instead. Other children that aren’t a function, such as an element, '', or [], throw a TypeError. So does a <Recipe.Step> without an item. JavaScript throws these, not Recipe Book, so the message depends on the build and the engine. In Node, which runs V8, with the package’s unminified build, <Recipe.StepList> with an element throws TypeError: render is not a function, and <Recipe.Step> without an item throws TypeError: Cannot read properties of undefined (reading 'name'). A minified build renames render, JavaScriptCore (Safari, Bun) adds the failing call after the first message, and other engines word the second differently. TypeScript rejects both:

Rejected by TypeScript
import type { ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.StepList>
        <li>Mix.</li>
      </Recipe.StepList>
      <Recipe.Step />
    </Recipe.Root>
  )
}
Text
error TS2322: Type 'Element' is not assignable to type '(step: RecipeStepItem) => ReactNode'.
error TS2741: Property 'item' is missing in type '{}' but required in type '{ item: RecipeStepItem; asChild?: boolean | undefined; }'.

Pass a function, as in Render your own steps, and give each <Recipe.Step> the step it renders.

Types

@recipe-book/react exports each part’s props type: RecipeStepsProps, RecipeStepListProps, RecipeStepProps, RecipeStepNameProps, RecipeStepTextProps, and RecipeConvertedStepTextProps. Use them to type a component that wraps a part:

TSX
import * as Recipe from '@recipe-book/react'

export function Method(props: Recipe.RecipeStepsProps) {
  return (
    <section aria-labelledby="method">
      <h2 id="method">Method</h2>
      <Recipe.Steps {...props} />
    </section>
  )
}

It also exports RecipeStepItem, the type of each step, and the generic RecipeSection: each section is a RecipeSection<RecipeStepItem>.

Named imports

To import these parts by name, import each one without the Recipe.: Steps, StepList, Step, StepName, StepText, and ConvertedStepText. If a name clashes with one of yours, alias it, as in import { Steps as RecipeSteps } from '@recipe-book/react'.

Contents