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.
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.
- Whisk the dry ingredients in a large bowl.
- Whisk the buttermilk, eggs, and butter, then fold into the dry ingredients.
- Cook ¼-cup portions on a buttered griddle, 2–3 minutes per side.
Anatomy
'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
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:
<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':
'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:
<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
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:
<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:
'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:
<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
'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:
<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:
<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:
'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:
<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
'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:
<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
'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:
<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.readsCook sous vide at 56.5 °C.in metric. A converted temperature that’s an oven setting, one whose segment’sovenistrue, rounds to the nearest 10 °C or 25 °F, soBake at 180°C.readsBake at 350 °F.in US. Any other converted temperature is in whole degrees, soRoast until it reads 74°C.readsRoast 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)readsBake at 200 °Cin metric, andHeat to 37.5 °C (99.5 °F).readsHeat to 99.5 °F.in US. - The
fanlabel follows a fan-oven setting, soHeat oven to 190C/170C fan/gas 5.readsHeat 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 readsHeat oven to 190 °C / 170 °C. - When
segmentStepTextpairs 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, soHeat oven to 200°C (180°C fan).andHeat oven to 180°C fan or 200°C.both readHeat 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 5or200°C (gas mark 6), is left out. Everything else, including a gas mark on its own or before a temperature, is shown as authored, soBake at gas mark 6 (200°C).readsBake 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, unlessinferTemperatureUnitreads it. - The digits follow Root’s
locale, so withlocale="ar-EG",Bake at 180°C.readsBake 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:
'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:
'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
'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:
<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, soStir 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, assegmentStepQuantitiesdescribes, and the next one can be converted again. - Any other quantity is converted with
toSystemand written withformatQuantityin Root’slocaleandlabels, soAdd 500 ml of stock.readsAdd 2 ⅛ cups of stock.in US, andAdd 2 cups of stock.readsAdd 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.readsAdd 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 withtoSystem’sexact, so it keeps the unittoSystemlands on but not its rounding, as the ingredient list does, soAdd 150 ml of milk.readsAdd 10 ⅛ tbsp of milk.in US rather thanAdd 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.segmentStepQuantitieslists 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>:
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>:
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:
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>
)
}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:
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'.