# 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.

Source: https://recipe-book.siraj.page/reference/react/equipment/

`<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>`](https://recipe-book.siraj.page/reference/react/root.md).

## `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`](https://recipe-book.siraj.page/reference/core/parsing.md#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](https://recipe-book.siraj.page/reference/react/equipment.md#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](https://recipe-book.siraj.page/reference/react/equipment.md#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`](https://recipe-book.siraj.page/reference/core/types.md#equipment). See [Render your own items](https://recipe-book.siraj.page/reference/react/equipment.md#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>`](https://recipe-book.siraj.page/reference/react/steps.md#render-your-own-sections). `<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 {1,10-20}
'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](https://recipe-book.siraj.page/reference/react/system-toggle.md#render-your-own-elements) 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 {7-9}
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](https://recipe-book.siraj.page/errors.md#warning-as-child).

## Errors

Throws [`missing_parent`](https://recipe-book.siraj.page/errors/missing_parent.md) when it isn't inside `<Recipe.Root>`:

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

Throws [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) 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:

```txt
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](https://recipe-book.siraj.page/reference/core/formatting.md#formatoptions) 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:

```ts
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'`.
