Recipe Book0.6.0

4.9React reference

Times

Reference for <Recipe.Times>, which renders a recipe's prep, cook, custom, and total times as a description list.

§ 4.95 min readView as Markdown

<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

TSX
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:

HTML
<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:

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

HTML
<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:

TSX
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:

HTML
<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>:

Text
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:

TypeScript
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

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

Contents