Recipe Book0.6.0

4.10React reference

Equipment

Reference for <Recipe.Equipment>, which renders the tools a recipe needs as a list, linking each one that has a URL to its product page.

§ 4.105 min readView as Markdown

<Recipe.Equipment> renders the kitchen tools the recipe needs as a list, such as “2 loaf pans, greased”, with the name of each item that has a url linked to its product page. It must be inside <Recipe.Root>.

Equipment

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.'],
  equipment: [
    { name: 'loaf pan', plural: 'loaf pans', quantity: 2, note: 'greased' },
    { name: 'stand mixer', url: 'https://example.com/mixer' },
    'cooling rack',
  ],
})
if (!result.success) throw result.error
const recipe = result.data

export function BreadEquipment() {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Equipment className="tools" />
    </Recipe.Root>
  )
}

BreadEquipment renders this HTML, indented here for reading:

HTML
<ul class="tools" data-recipe-equipment="">
  <li data-recipe-equipment-item="">2 loaf pans, greased</li>
  <li data-recipe-equipment-item=""><a href="https://example.com/mixer">stand mixer</a></li>
  <li data-recipe-equipment-item="">cooling rack</li>
</ul>

Each item shows its quantity, if it has one, then its name, then a comma and its note, if it has one that isn’t empty. The name is the item’s plural, if it has one, when its quantity prints as more than 1, and its name otherwise, so a quantity of 1.4, which prints as 1, shows the name. Only a recipe you build can have a quantity that isn’t a whole number above 0, and a finite one is rounded to the nearest whole number, so 1.5 prints as 2 and -0.4 prints as 0, not -0. A no-break space joins the quantity to the name, so a line doesn’t break between them, and the quantity’s digits follow Root’s locale. <Recipe.Equipment> renders nothing when the recipe has no equipment, so put a heading above it behind a check of recipe.equipment.length. Equipment doesn’t scale with servings.

The name links to the item’s url when it isn’t empty and it’s an http, https, or relative URL that the URL parser reads. parseRecipe rejects other schemes, and Root doesn’t check a parsed recipe’s values, so a recipe built by hand can hold any string as a url. <Recipe.Equipment> shows the name of an item with any other url, such as '', 'http://' or a javascript: URL, as text. The link has no rel. To give it one, such as rel="sponsored", render your own items.

Name Type Description
asChild true Renders the list as its only child instead of a <ul>. 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 ((item: Equipment) => ReactNode) | ReactElement | undefined Renders each item instead of the default <li data-recipe-equipment-item>. The item is core’s Equipment. See Render your own items. With asChild, the one element to render.

Any other <ul> prop, such as className or aria-label, passes to the <ul>, 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-equipment attribute, or each item’s data-recipe-equipment-item.

Render your own items

Pass a function as children from a Client Component, as with <Recipe.Steps>. <Recipe.Equipment> keys each result by the item’s id, so an element or fragment you return needs no key. This example marks each link as sponsored:

TSX
'use client'

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

export function ShopTheRecipe({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Equipment>
        {(item) => (
          <li>
            {item.url ? (
              <a href={item.url} rel="sponsored">
                {item.name}
              </a>
            ) : (
              item.name
            )}
          </li>
        )}
      </Recipe.Equipment>
    </Recipe.Root>
  )
}

For the recipe in the first example, ShopTheRecipe renders:

HTML
<ul data-recipe-equipment="">
  <li>loaf pan</li>
  <li><a href="https://example.com/mixer" rel="sponsored">stand mixer</a></li>
  <li>cooling rack</li>
</ul>

A url you render yourself isn’t checked, so check its scheme unless the recipe comes from parseRecipe.

Render your own element

With asChild, <Recipe.Equipment> passes data-recipe-equipment, your other props, and its ref to its only child. Use it to number the items with an <ol>, or for a component that must be the list itself, such as an animated motion.ul. 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 items. A child whose children are undefined, null, true, or false gets the default items, but any other children replace them, even '', [], or an empty Fragment, which render nothing:

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

export function Tools({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.Equipment asChild>
        <ol className="tools" />
      </Recipe.Equipment>
    </Recipe.Root>
  )
}

For the recipe in the first example, Tools renders:

HTML
<ol class="tools" data-recipe-equipment="">
  <li data-recipe-equipment-item="">2 loaf pans, greased</li>
  <li data-recipe-equipment-item=""><a href="https://example.com/mixer">stand mixer</a></li>
  <li data-recipe-equipment-item="">cooling rack</li>
</ol>

The child should render a list, so the items stay list items. With anything but one element child, such as text, several children, a function, or a Fragment, <Recipe.Equipment> renders its own <ul> with those children, or with the default items when they’re undefined, null, true, or false. In development, the first <Recipe.Equipment> to do this logs a development warning.

Errors

Throws missing_parent when it isn’t inside <Recipe.Root>:

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

Throws invalid_argument for a recipe with an item that has a quantity when Root’s locale isn’t a language tag that Intl accepts, such as 'en_US', unless children is a function, which formats no quantities:

Text
RecipeBookError: <Recipe.Equipment>: locale must be a language tag that Intl accepts, such as "en-US", received "en_US".
See https://recipe-book.siraj.page/errors/invalid_argument/

The quantities are in English for en alone or with a region such as en-GB, and for a locale the runtime doesn’t support, as core’s formatters write them. In a runtime without Intl, <Recipe.Equipment> writes English for every string locale, even 'en_US', and doesn’t throw. A locale that isn’t a string, null or undefined, such as ['de-DE'], throws invalid_argument in the same cases as 'en_US', with or without Intl, as core’s formatters do.

Types

@recipe-book/react exports the props type as RecipeEquipmentProps, to type a component that wraps the part:

TypeScript
type RecipeEquipmentProps = Omit<
  ComponentPropsWithoutRef<'ul'>,
  'children' | 'dangerouslySetInnerHTML'
> &
  (
    | {
        asChild?: false | undefined
        children?: ((item: Equipment) => ReactNode) | undefined
      }
    | { asChild: true; children: ReactElement }
  )

Don’t remove props from RecipeEquipmentProps with Omit, which flattens the union, so <Recipe.Equipment {...props}> no longer type-checks.

Named imports

To import <Recipe.Equipment> by name, import Equipment. If the name clashes with one of yours, alias it, as in import { Equipment as RecipeEquipment } from '@recipe-book/react'.

Contents