# Times

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

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

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

## `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](https://recipe-book.siraj.page/reference/core/types.md#customtime) 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](https://recipe-book.siraj.page/reference/react/provider.md#recipelabels) `prepTime`, `cookTime`, and `totalTime`, which stay in English under a [label pack](https://recipe-book.siraj.page/reference/react/labels.md) unless you set them, and a custom time shows its own label. The durations come from [`formatDuration`](https://recipe-book.siraj.page/reference/core/formatting.md#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](https://recipe-book.siraj.page/reference/react/times.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` | `((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](https://recipe-book.siraj.page/reference/react/times.md#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>`](https://recipe-book.siraj.page/reference/react/steps.md#render-your-own-sections). It receives a [`RecipeTimeItem`](https://recipe-book.siraj.page/reference/react/times.md#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 {1,10-17}
'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](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 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 {11-13}
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](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.Times> 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) 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`](https://recipe-book.siraj.page/reference/core/formatting.md#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`](https://recipe-book.siraj.page/errors/invalid_argument.md) 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`](https://recipe-book.siraj.page/reference/core/parsing.md#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:

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

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