# Hooks

> Reference for useRecipe, useRecipeState, and useFormatIngredient, which give your own components the state and formatting that parts use.

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

Three hooks give your own components the state and formatting that parts use. [`useRecipe()`](https://recipe-book.siraj.page/reference/react/hooks.md#userecipe) reads the state of the nearest [`<Recipe.Root>`](https://recipe-book.siraj.page/reference/react/root.md), and [`useFormatIngredient()`](https://recipe-book.siraj.page/reference/react/hooks.md#useformatingredient) formats its ingredients as text. [`useRecipeState()`](https://recipe-book.siraj.page/reference/react/hooks.md#userecipestate) holds the state itself, without a Root. The [Checklist](https://recipe-book.siraj.page/reference/react/checklist.md) page has two more, for a checklist's ticks: [`useChecklist()`](https://recipe-book.siraj.page/reference/react/checklist.md#usechecklist) reads those of the nearest [`<Recipe.Checklist>`](https://recipe-book.siraj.page/reference/react/checklist.md#checklist), and [`useChecklistState()`](https://recipe-book.siraj.page/reference/react/checklist.md#usecheckliststate) holds them without one. A component that calls any of them needs `'use client'`.

[Try the live demo of useRecipe and useFormatIngredient](https://recipe-book.siraj.page/reference/react/hooks/)

## `useRecipe`

```ts
function useRecipe(): RecipeState
```

Returns the state of the nearest `<Recipe.Root>`: the recipe, its servings and measurement system, and the functions that change them.

```tsx
'use client'

import * as Recipe from '@recipe-book/react'

export function SystemSwitch() {
  const { system, setSystem, canConvert } = Recipe.useRecipe()
  if (!canConvert) return null

  return (
    <button onClick={() => setSystem(system === 'us' ? 'metric' : 'us')}>
      {system === 'us' ? 'Show metric' : 'Show US'}
    </button>
  )
}
```

Inside a Root for the [sample recipe](https://recipe-book.siraj.page/guides/render-a-recipe-in-react.md#parse-on-the-server), which is written in US units, `SystemSwitch` renders:

```html
<button>Show metric</button>
```

A click changes it to `<button>Show US</button>`. For a recipe whose only quantity is a count, such as 2 slices of bread, it renders nothing.

### Returns

[`RecipeState`](https://recipe-book.siraj.page/reference/react/hooks.md#recipestate).

### Errors

Throws [`missing_parent`](https://recipe-book.siraj.page/errors/missing_parent.md) when a component outside `<Recipe.Root>` calls it:

```txt
RecipeBookError: useRecipe() must be called inside <Recipe.Root>. To use recipe state without a Root, call useRecipeState().
See https://recipe-book.siraj.page/errors/missing_parent/
```

## `useFormatIngredient`

```ts
function useFormatIngredient(): (
  item: RecipeIngredientItem,
) => RecipeFormattedIngredient
```

Returns a function that formats an ingredient as [`<Recipe.Ingredient>`](https://recipe-book.siraj.page/reference/react/ingredients.md#ingredient) does, with the `locale` and `labels` of the nearest `<Recipe.Root>`.

```tsx {12-14}
'use client'

import * as Recipe from '@recipe-book/react'

export function CopyIngredients() {
  const { ingredients } = Recipe.useRecipe()
  const format = Recipe.useFormatIngredient()
  const lines = ingredients
    .flatMap((section) => section.items)
    .map((item) => {
      const formatted = format(item)
      return formatted.optionalLabel
        ? `${formatted.text} ${formatted.optionalLabel}`
        : formatted.text
    })

  return (
    <button onClick={() => navigator.clipboard.writeText(lines.join('\n'))}>
      Copy ingredients
    </button>
  )
}
```

Inside a Root for the [sample recipe](https://recipe-book.siraj.page/guides/render-a-recipe-in-react.md#parse-on-the-server), a click on **Copy ingredients** copies:

```txt
1 ½ cups all-purpose flour
2 tbsp sugar
2 tsp baking powder
1 ¼ cups buttermilk
2 eggs
3 tbsp butter, melted
maple syrup, to serve
```

Call it when you need text instead of elements: to copy the ingredients, as here, to put one in an attribute, or to render somewhere other than the DOM. To show ingredients on the page, use the [ingredient parts](https://recipe-book.siraj.page/reference/react/ingredients.md), which add the `data-recipe-*` attributes and follow the dash of a quantity range, as in "2–3 tbsp", with the [`to` label](https://recipe-book.siraj.page/reference/react/ingredients.md#labels) in text that's hidden on screen, so in Chrome and Firefox the label takes the dash's place. The function's `text` never includes the optional label: add `optionalLabel` yourself, as `CopyIngredients` does.

### Returns

A function that takes a [`RecipeIngredientItem`](https://recipe-book.siraj.page/reference/react/ingredients.md#recipeingredientitem) and returns a [`RecipeFormattedIngredient`](https://recipe-book.siraj.page/reference/react/hooks.md#recipeformattedingredient). `useFormatIngredient()` returns the same function until Root's `locale`, `labels.optional`, or measurement system changes, so you can list it in a hook's dependencies. Once a Root or provider sets a pack, it also returns a new function whenever the nearest Root or provider that sets one gets a new `labels` object, so define `labels` at module scope.

### Errors

Throws [`missing_parent`](https://recipe-book.siraj.page/errors/missing_parent.md) when a component outside `<Recipe.Root>` calls it, even one inside a [`<Recipe.Provider>`](https://recipe-book.siraj.page/reference/react/provider.md):

```txt
RecipeBookError: useFormatIngredient() must be called inside <Recipe.Root>. To format ingredients without a Root, call formatIngredient() from @recipe-book/react/core.
See https://recipe-book.siraj.page/errors/missing_parent/
```

The function it returns throws [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) when the item isn't `{ ingredient, quantity? }`, such as `null`, when Root's `locale` isn't a language tag that `Intl` accepts, such as `'en_US'`, or when the item's quantity, or the size it shows after a count unit, has an amount that [`formatQuantity`](https://recipe-book.siraj.page/reference/core/formatting.md#formatquantity) rejects, such as 0 or a range whose `min` is above its `max`, and [`unknown_unit`](https://recipe-book.siraj.page/errors/unknown_unit.md) when its unit isn't a unit ID, unless it throws `invalid_argument` first, as it does for an amount of 0, or for an item from Root, 1e308 scaled past the largest number. A reversed size range doesn't throw, though, where the count is a range and [the size shows one figure for each item](https://recipe-book.siraj.page/guides/display-quantities.md#show-the-size-of-a-can), as 200–201 cans whose only size is `{ min: 101, max: 100 }` oz show "½ oz each" in `'us'`. In `'metric'`, 14 g is more than 2% off 101 oz split 200 ways, so it switches to the total and throws because the total's range is still reversed. It also throws `invalid_argument`, with a message that starts `formatIngredient:`, when the item's ingredient has a `name`, `plural`, or `note` that isn't a string, such as `null`.

In a runtime without `Intl`, the function that `useFormatIngredient()` returns doesn't throw for any `locale` string, even `'en_US'`, and writes the numbers in English.

## `useRecipeState`

```ts
function useRecipeState(options: RecipeStateOptions): RecipeState
```

Holds a recipe's state without a `<Recipe.Root>`. `<Recipe.Root>` is built on it, so the state works the same way: [controlled or uncontrolled](https://recipe-book.siraj.page/reference/react/root.md#controlled-and-uncontrolled-state), within the same [servings window](https://recipe-book.siraj.page/reference/react/root.md#servings-window), with the same [development warnings](https://recipe-book.siraj.page/errors.md#react-development-warnings).

```tsx
'use client'

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

export function ServingsSummary({ recipe }: { recipe: ParsedRecipe }) {
  const { scaledServings, scale } = Recipe.useRecipeState({
    recipe,
    defaultServings: 8,
  })

  return (
    scaledServings && (
      <p>{`Serves ${formatServings(scaledServings)}, scaled ×${scale}`}</p>
    )
  )
}
```

For the sample recipe, which has 4 servings, `ServingsSummary` renders:

```html
<p>Serves 8, scaled ×2</p>
```

For a recipe with a yield but no servings, `scaledServings` is `undefined`, so `ServingsSummary` renders nothing. `defaultServings` then counts in the yield's unit, and `scaledYield` holds the yield, which [`formatYield`](https://recipe-book.siraj.page/reference/core/formatting.md#formatyield) writes as "8 cookies".

Parts and `useRecipe()` can't read this state, because it isn't in a Root. To share it with other components, pass it to them as props.

| Name      | Type                                                                                               | Default  | Description               |
| --------- | -------------------------------------------------------------------------------------------------- | -------- | ------------------------- |
| `options` | [`RecipeStateOptions`](https://recipe-book.siraj.page/reference/react/hooks.md#recipestateoptions) | Required | The recipe and its state. |

### Returns

[`RecipeState`](https://recipe-book.siraj.page/reference/react/hooks.md#recipestate).

### Errors

In development, throws [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) when `recipe` doesn't have a parsed recipe's shape, which it checks as [`<Recipe.Root>`](https://recipe-book.siraj.page/reference/react/root.md#parse-on-the-server) does:

```txt
RecipeBookError: useRecipeState(): recipe must be a parsed recipe, received an object that parseRecipe hasn't normalized. Call parseRecipe() from @recipe-book/react/core and pass result.data.
See https://recipe-book.siraj.page/errors/invalid_argument/
```

In development, it throws the same error when `options` has no `recipe`, such as for `useRecipeState()` or `useRecipeState(recipe)`. For `useRecipeState()`, the message says to call [`useRecipe()`](https://recipe-book.siraj.page/reference/react/hooks.md#userecipe) to read the state of the nearest Root; otherwise it says to pass `{ recipe }`.

## Types

`@recipe-book/react` exports each of these types. Name them through the namespace, such as `Recipe.RecipeState`:

```ts
import type * as Recipe from '@recipe-book/react'

export function isScaled(state: Recipe.RecipeState): boolean {
  return state.scale !== 1
}
```

### `RecipeState`

```ts
type RecipeState = {
  recipe: Recipe
  servings: number
  setServings: (servings: number) => void
  scale: number
  scaledServings?: Servings | undefined
  scaledYield?: Yield | undefined
  system: System
  setSystem: (system: System) => void
  canConvert: boolean
  ingredients: readonly RecipeSection<RecipeIngredientItem>[]
  steps: readonly RecipeSection<RecipeStepItem>[]
  idPrefix: string
}
```

What `useRecipe()` and `useRecipeState()` return.

| Name             | Type                                                                                                                                                                                                               | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `recipe`         | [`Recipe`](https://recipe-book.siraj.page/reference/core/types.md#recipe)                                                                                                                                          | The parsed recipe.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `servings`       | `number`                                                                                                                                                                                                           | The number of servings shown, counted from the recipe's [scaling base](https://recipe-book.siraj.page/reference/react/root.md#scaling-base). For a recipe with a yield but no servings, it counts in the yield's unit.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `setServings`    | `(servings: number) => void`                                                                                                                                                                                       | Calls `onServingsChange`, and changes the number of servings unless servings are controlled. Ignores any number outside the [servings window](https://recipe-book.siraj.page/reference/react/root.md#servings-window), and the current number unless a controlled `servings` is outside the window, or another number passed to it inside a transition is pending and, if servings are controlled, `<Recipe.Root>`, or the component that calls `useRecipeState`, has rendered since. A number pending only in the parent's own transition doesn't count.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `scale`          | `number`                                                                                                                                                                                                           | `servings` divided by the recipe's [scaling base](https://recipe-book.siraj.page/reference/react/root.md#scaling-base).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `scaledServings` | [`Servings`](https://recipe-book.siraj.page/reference/core/types.md#servings) \| `undefined`                                                                                                                       | The recipe's servings at `scale`, or `undefined` for a recipe without servings. At a `scale` within 1e-9 of 1, the servings as written, so a range such as 6–8 stays one. At any other `scale`, `{ amount: servings }` when the servings are the [scaling base](https://recipe-book.siraj.page/reference/react/root.md#scaling-base), plus a `max` that isn't greater than the amount, scaled, which only a recipe you build can have. [`<Recipe.ServingsText>`](https://recipe-book.siraj.page/reference/react/servings.md#servingstext) shows them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `scaledYield`    | [`Yield`](https://recipe-book.siraj.page/reference/core/types.md#yield) \| `undefined`                                                                                                                             | The recipe's yield at `scale`, or `undefined` for a recipe without one. At a `scale` within 1e-9 of 1, the yield as written. When the servings are the [scaling base](https://recipe-book.siraj.page/reference/react/root.md#scaling-base), both ends of a range scale, so 12–16 rolls for 4 servings are 24–32 rolls at 8. Otherwise, as for a recipe with only a yield, any other `scale` gives `{ amount: servings, unit, plural }`. Either way, when the yield's own amount is a finite number greater than 0, a `max` that isn't greater than it, which only a recipe you build can have, is kept and scaled. When it isn't, a `max` that isn't greater than it is dropped at a scale more than 1e-9 from 1, which is every `max` when `amount` is NaN or Infinity. [`<Recipe.YieldText>`](https://recipe-book.siraj.page/reference/react/servings.md#yieldtext) shows it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `system`         | [`System`](https://recipe-book.siraj.page/reference/core/units.md#system)                                                                                                                                          | The measurement system shown.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `setSystem`      | `(system: System) => void`                                                                                                                                                                                         | Calls `onSystemChange`, and changes the measurement system unless it's controlled. Ignores anything but `'metric'` and `'us'`, and the current system unless a controlled `system` is neither, or another system passed to it inside a transition is pending and, if the system is controlled, `<Recipe.Root>`, or the component that calls `useRecipeState`, has rendered since. A system pending only in the parent's own transition doesn't count.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `canConvert`     | `boolean`                                                                                                                                                                                                          | `true` when an ingredient's quantity, or any equivalent of a quantity in a count unit, such as the size of a can, has a unit that belongs to only one measurement system or, in a Root, a mounted [`<Recipe.StepText>`](https://recipe-book.siraj.page/reference/react/steps.md#steptext) or [`<Recipe.ConvertedStepText>`](https://recipe-book.siraj.page/reference/react/steps.md#convertedsteptext) shows a temperature, or a mounted `<Recipe.ConvertedStepText>` shows a quantity that one of the systems would convert. From `useRecipeState()`, it counts ingredients only. See [Recipes that can't convert](https://recipe-book.siraj.page/reference/react/system-toggle.md#recipes-that-cant-convert).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `ingredients`    | readonly [`RecipeSection`](https://recipe-book.siraj.page/reference/react/hooks.md#recipesection)\<[`RecipeIngredientItem`](https://recipe-book.siraj.page/reference/react/ingredients.md#recipeingredientitem)>[] | Each section's ingredients at `servings`, in `system`, scaled but not formatted. US volume converted from metric, or scaled in cups or spoons, can land on a [cup or spoon measure](https://recipe-book.siraj.page/reference/core/units.md#tosystem) unless [`exact`](https://recipe-book.siraj.page/reference/react/hooks.md#recipestateoptions) is set. In `'us'`, quarts, pints, gallons, and fluid ounces only scale, so 2 quarts for 4 servings is 2.74 quarts for 5.48, and at a scale within 1e-9 of 1, an amount in its own system and unit stays as written, so 1.3 cups stays 1.3 cups, but a range whose `min` equals its `max` gives its `min`. A range whose `min` is greater than its `max`, or whose `max` is missing, `null`, or `NaN`, which only a recipe you build can have, is kept and scaled. [`<Recipe.Ingredient>`](https://recipe-book.siraj.page/reference/react/ingredients.md#ingredient) and the function that [`useFormatIngredient()`](https://recipe-book.siraj.page/reference/react/hooks.md#useformatingredient) returns throw [`invalid_argument`](https://recipe-book.siraj.page/errors/invalid_argument.md) for it at every scale. Where scaling or converting makes the range's ends equal, it gives one amount instead. At twice the servings in metric, 1 cup of milk has the quantity `{ amount: 473.176473, unit: 'ml' }`. |
| `steps`          | readonly [`RecipeSection`](https://recipe-book.siraj.page/reference/react/hooks.md#recipesection)\<[`RecipeStepItem`](https://recipe-book.siraj.page/reference/react/hooks.md#recipestepitem)>[]                   | The recipe's steps in their sections.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `idPrefix`       | `string`                                                                                                                                                                                                           | Comes before each step's `id` in the `id` that [`<Recipe.Step>`](https://recipe-book.siraj.page/reference/react/steps.md#step) renders, so `` `#${idPrefix}${step.id}` `` links to a step. The Root's [`idPrefix`](https://recipe-book.siraj.page/reference/react/root.md#step-ids), or the recipe's `id` and a hyphen, which is what `useRecipeState()` gives.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |

`setSystem` stays the same function while the component holding the state is mounted, and `setServings` does too until the recipe's [scaling base](https://recipe-book.siraj.page/reference/react/root.md#scaling-base) changes, so passing one to a [`memo`](https://react.dev/reference/react/memo) component doesn't make it render again when the servings or system change. Don't change the state or anything in it, such as `recipe`, which is the object you passed.

### `RecipeStateOptions`

```ts
type RecipeStateOptions = {
  recipe: Recipe
  servings?: number | undefined
  defaultServings?: number | undefined
  onServingsChange?: ((servings: number) => void) | undefined
  system?: System | undefined
  defaultSystem?: System | undefined
  onSystemChange?: ((system: System) => void) | undefined
  exact?: boolean | undefined
}
```

What `useRecipeState()` takes. The state props of `<Recipe.Root>` are the same.

| Name               | Type                                                                                     | Description                                                                                                                                                                                                                                                                                                                                |
| ------------------ | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `recipe`           | [`Recipe`](https://recipe-book.siraj.page/reference/core/types.md#recipe)                | A parsed recipe: `result.data` from [`parseRecipe`](https://recipe-book.siraj.page/reference/core/parsing.md#parserecipe).                                                                                                                                                                                                                 |
| `servings`         | `number \| undefined`                                                                    | The number of servings to show. Passing it makes servings controlled.                                                                                                                                                                                                                                                                      |
| `defaultServings`  | `number \| undefined`                                                                    | The number of servings to start with when servings are uncontrolled. Defaults to the recipe's [scaling base](https://recipe-book.siraj.page/reference/react/root.md#scaling-base).                                                                                                                                                         |
| `onServingsChange` | `((servings: number) => void) \| undefined`                                              | Called with the new number of servings each time [`setServings`](https://recipe-book.siraj.page/reference/react/hooks.md#recipestate) accepts one, whether or not servings are controlled.                                                                                                                                                 |
| `system`           | [`System`](https://recipe-book.siraj.page/reference/core/units.md#system) \| `undefined` | The measurement system to show. Passing it makes the system controlled.                                                                                                                                                                                                                                                                    |
| `defaultSystem`    | [`System`](https://recipe-book.siraj.page/reference/core/units.md#system) \| `undefined` | The measurement system to start with when the system is uncontrolled. Defaults to the nearest provider's, then the recipe's, then `'metric'`.                                                                                                                                                                                              |
| `onSystemChange`   | `((system: System) => void) \| undefined`                                                | Called with the new system each time [`setSystem`](https://recipe-book.siraj.page/reference/react/hooks.md#recipestate) accepts one, whether or not the system is controlled.                                                                                                                                                              |
| `exact`            | `boolean \| undefined`                                                                   | Pass `true` to keep amounts exact when they're shown in another system or rebalanced, so 150 mL in `'us'` is 10.1442… tbsp, which [`formatIngredient`](https://recipe-book.siraj.page/reference/core/formatting.md#formatingredient) and the parts show as 10 ⅛ tbsp, rather than 10 tbsp. The unit is still the one a cook measures with. |

### `RecipeFormattedIngredient`

```ts
type RecipeFormattedIngredient = FormattedIngredient & {
  quantityParts: readonly QuantityPart[]
  optionalLabel?: string | undefined
}
```

What the function from `useFormatIngredient()` returns: an ingredient in the pieces that `<Recipe.Ingredient>` renders. The first five fields are core's [`FormattedIngredient`](https://recipe-book.siraj.page/reference/core/formatting.md#formattedingredient).

| Name            | Type                                                                                                             | Description                                                                                                                                                                                                                                                                                                                              |
| --------------- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `quantity`      | `string \| undefined`                                                                                            | The quantity, as [`formatQuantity`](https://recipe-book.siraj.page/reference/core/formatting.md#formatquantity) formats it with Root's `locale` and [`labels`](https://recipe-book.siraj.page/reference/react/provider.md#recipelabels). Absent when the ingredient has none.                                                            |
| `size`          | `string \| undefined`                                                                                            | For a can, a package, or another count unit with a mass or volume equivalent, its size as `text` shows it in parentheses, such as 15 oz each for 2 cans, as [`formatIngredient`](https://recipe-book.siraj.page/reference/core/formatting.md#formatingredient) describes. Absent otherwise. `quantity` and `quantityParts` leave it out. |
| `name`          | `string`                                                                                                         | The name, or the `plural` after a bare count that takes it, as in 2 eggs. A `plural` that's empty or only whitespace reads as none.                                                                                                                                                                                                      |
| `note`          | `string \| undefined`                                                                                            | The note. Absent when the ingredient has none.                                                                                                                                                                                                                                                                                           |
| `text`          | `string`                                                                                                         | The quantity, any size in parentheses, the name, and the note after a comma, joined as `formatIngredient` joins them. It never includes `optionalLabel`.                                                                                                                                                                                 |
| `quantityParts` | <code>readonly [QuantityPart](https://recipe-book.siraj.page/reference/core/formatting.md#quantitypart)[]</code> | The quantity in pieces, from [`formatQuantityToParts`](https://recipe-book.siraj.page/reference/core/formatting.md#formatquantitytoparts). Empty when the ingredient has no quantity.                                                                                                                                                    |
| `optionalLabel` | `string \| undefined`                                                                                            | The [`optional` label](https://recipe-book.siraj.page/reference/react/ingredients.md#labels). Absent when the ingredient isn't optional.                                                                                                                                                                                                 |

For an ingredient written as `{ name: 'lemon', plural: 'lemons', quantity: '1–2', note: 'zested', optional: true }`, the function returns:

```ts
import type * as Recipe from '@recipe-book/react'

export const lemon: Recipe.RecipeFormattedIngredient = {
  quantity: '1–2',
  name: 'lemons',
  note: 'zested',
  text: '1–2\u00a0lemons, zested',
  quantityParts: [
    { type: 'amount', value: '1' },
    { type: 'rangeSeparator', value: '–' },
    { type: 'amount', value: '2' },
  ],
  optionalLabel: '(optional)',
}
```

### `RecipeStepItem`

```ts
type RecipeStepItem = Step & { number: number }
```

A [`Step`](https://recipe-book.siraj.page/reference/core/types.md#step) with its `number`. [`<Recipe.Step>`](https://recipe-book.siraj.page/reference/react/steps.md#step) takes one as `item`.

| Name     | Type     | Description                                                                                                                                                          |
| -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `number` | `number` | The step's position, counted from 1 across sections. For a recipe with one untitled step and a "Cook" section of two steps, the steps in "Cook" are numbers 2 and 3. |

### `RecipeSection`

```ts
type RecipeSection<T> = {
  id: string
  title?: string | undefined
  items: readonly T[]
}
```

A section of a recipe's ingredients or steps.

| Name    | Type                  | Description                                   |
| ------- | --------------------- | --------------------------------------------- |
| `id`    | `string`              | The section's ID from the recipe.             |
| `title` | `string \| undefined` | The section's title. Absent when it has none. |
| `items` | `readonly T[]`        | The items in the section.                     |
