4.9React reference
Times
Reference for <Recipe.Times>, which renders a recipe's prep, cook, custom, and total times as a description list.
<Recipe.Times> renders the recipe’s prep time, cook time, custom times, and total time as a description list, with each time’s label as the term and its duration as the description. It must be inside <Recipe.Root>.
Times
import { parseRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
const result = parseRecipe({
name: 'Sandwich bread',
ingredients: [{ name: 'bread flour', quantity: '500 g' }],
steps: ['Knead the dough until smooth.'],
times: {
prep: 20,
cook: 35,
total: 175,
custom: [{ label: 'Rise', minutes: 120 }],
},
})
if (!result.success) throw result.error
const recipe = result.data
export function BreadTimes() {
return (
<Recipe.Root recipe={recipe}>
<Recipe.Times className="facts" />
</Recipe.Root>
)
}BreadTimes renders this HTML, indented here for reading:
<dl class="facts" data-recipe-times="">
<div data-recipe-time="prep"><dt>Prep time</dt><dd><time dateTime="PT1200S">20 min</time></dd></div>
<div data-recipe-time="cook"><dt>Cook time</dt><dd><time dateTime="PT2100S">35 min</time></dd></div>
<div data-recipe-time="custom"><dt>Rise</dt><dd><time dateTime="PT7200S">2 hr</time></dd></div>
<div data-recipe-time="total"><dt>Total time</dt><dd><time dateTime="PT10500S">2 hr 55 min</time></dd></div>
</dl>The rows are always in this order: prep, cook, each of the recipe’s custom times as written, then total. A time the recipe doesn’t give has no row, and a time of 0 shows as “0 min”. <Recipe.Times> renders nothing when the recipe has no times, so hide a heading above it unless recipe.times has a prep, cook, or total, or a custom time. A check of recipe.times alone always passes, since a recipe with no times still has { custom: [] }. Times don’t scale with servings.
The prep, cook, and total rows take their terms from Root’s labels prepTime, cookTime, and totalTime, which stay in English under a label pack unless you set them, and a custom time shows its own label. The durations come from formatDuration with Root’s locale, which sets only how their numbers are written. Their unit words are English with or without a label pack: “day” or “days”, “hr”, “min”, and “sec”. A time of a day or more shows days, so 1,500 minutes shows as “1 day 1 hr”, and part of a minute shows seconds, rounded to the second, so 1.5 minutes shows as “1 min 30 sec” and 0.001 minutes as “0 min”.
| Name | Type | Description |
|---|---|---|
asChild |
true |
Renders the list as its only child instead of a <dl>. See Render your own element. Defaults to false. It needs exactly one element child. A value typed boolean, such as asChild={isLinked}, doesn’t type-check, so render the list with and without asChild in separate branches. |
children |
((time: RecipeTimeItem) => ReactNode) | ReactElement | undefined |
Renders each time instead of the default row: a <div data-recipe-time> around a <dt> and a <dd>. See Render your own rows. With asChild, the one element to render. |
Any other <dl> prop, such as className or aria-label, passes to the <dl>, and a ref reaches it. It renders its own content, so it doesn’t take dangerouslySetInnerHTML. Style it with className, or select its data-recipe-times attribute, or each row’s data-recipe-time, which is set to the time’s kind: prep, cook, custom, or total.
Render your own rows
Pass a function as children from a Client Component, as with <Recipe.Steps>. It receives a RecipeTimeItem for each time, and <Recipe.Times> keys each result, so an element or fragment you return needs no key. Return null to leave a time out, such as the total when your page shows it elsewhere:
'use client'
import type { ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
export function Timeline({ recipe }: { recipe: ParsedRecipe }) {
return (
<Recipe.Root recipe={recipe}>
<Recipe.Times>
{(time) =>
time.kind === 'total' ? null : (
<div>
<dt>{time.label}</dt>
<dd>{time.text}</dd>
</div>
)
}
</Recipe.Times>
</Recipe.Root>
)
}For the recipe in the first example, Timeline renders:
<dl data-recipe-times="">
<div><dt>Prep time</dt><dd>20 min</dd></div>
<div><dt>Cook time</dt><dd>35 min</dd></div>
<div><dt>Rise</dt><dd>2 hr</dd></div>
</dl>Render your own element
With asChild, <Recipe.Times> renders its only child in place of the <dl>, and passes data-recipe-times, your other props, and its ref to it. Use it for a component that must be the list itself, such as an animated motion.dl. 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 replace the rows. A child whose children are undefined, null, true, or false gets the default rows, but any other children replace them, even '', [], or an empty Fragment, which render nothing. Here, Facts stands in for a component like that:
import type { ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
import type { ComponentProps } from 'react'
function Facts(props: ComponentProps<'dl'>) {
return <dl {...props} />
}
export function RecipeFacts({ recipe }: { recipe: ParsedRecipe }) {
return (
<Recipe.Root recipe={recipe}>
<Recipe.Times asChild className="times">
<Facts className="facts" />
</Recipe.Times>
</Recipe.Root>
)
}For the recipe in the first example, RecipeFacts renders:
<dl class="times facts" data-recipe-times="">
<div data-recipe-time="prep"><dt>Prep time</dt><dd><time dateTime="PT1200S">20 min</time></dd></div>
<div data-recipe-time="cook"><dt>Cook time</dt><dd><time dateTime="PT2100S">35 min</time></dd></div>
<div data-recipe-time="custom"><dt>Rise</dt><dd><time dateTime="PT7200S">2 hr</time></dd></div>
<div data-recipe-time="total"><dt>Total time</dt><dd><time dateTime="PT10500S">2 hr 55 min</time></dd></div>
</dl>The child should render a <dl>, so the rows stay in a description list. With anything but one element child, such as text, several children, a function, or a Fragment, <Recipe.Times> renders its own <dl> with those children, or with the default rows when they’re undefined, null, true, or false. In development, the first <Recipe.Times> to do this logs a development warning.
Errors
Throws missing_parent when it isn’t inside <Recipe.Root>:
RecipeBookError: <Recipe.Times> must be rendered inside <Recipe.Root>.
See https://recipe-book.siraj.page/errors/missing_parent/Throws invalid_argument when Root’s locale isn’t a language tag that Intl accepts, such as 'en_US', and the recipe has a time to format, even 0 or with a function as children. The message starts with formatDuration. In a runtime without Intl, <Recipe.Times> doesn’t throw for any locale string, even 'en_US', and writes the numbers in English.
It also throws invalid_argument when a recipe you build has a prep, cook, or total, or a custom time’s minutes, that isn’t a finite number 0 or more, such as -5, NaN, or Infinity, even with a function as children. <Recipe.Root> doesn’t check them, and parseRecipe never returns such a recipe. This message also starts with formatDuration.
Types
@recipe-book/react exports the props type as RecipeTimesProps, to type a component that wraps the part:
type RecipeTimesProps = Omit<
ComponentPropsWithoutRef<'dl'>,
'children' | 'dangerouslySetInnerHTML'
> &
(
| {
asChild?: false | undefined
children?: ((time: RecipeTimeItem) => ReactNode) | undefined
}
| { asChild: true; children: ReactElement }
)Don’t remove props from RecipeTimesProps with Omit, which flattens the union, so <Recipe.Times {...props}> no longer type-checks.
RecipeTimeItem
type RecipeTimeItem = {
kind: 'prep' | 'cook' | 'custom' | 'total'
id: string
label: string
minutes: number
text: string
}One time, as <Recipe.Times> passes it to children.
| Name | Type | Description |
|---|---|---|
kind |
'prep' | 'cook' | 'custom' | 'total' |
Which time it is. 'custom' is one of the recipe’s custom times. |
id |
string |
The kind, or a custom time’s own id. A custom time labeled “Prep” has the id 'prep', so tell times apart by kind and id together. |
label |
string |
The prepTime, cookTime, or totalTime label, or a custom time’s own label. |
minutes |
number |
The duration in minutes, as the recipe gives it. |
text |
string |
The duration formatted with Root’s locale, such as “1 hr 15 min”. |
Named imports
To import <Recipe.Times> by name, import Times. If the name clashes with one of yours, alias it, as in import { Times as RecipeTimes } from '@recipe-book/react'.