# Cook mode

> Reference for <Recipe.CookMode>, a switch that asks the browser to keep the screen on while someone cooks, in browsers with the Screen Wake Lock API.

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

[`<Recipe.CookMode>`](https://recipe-book.siraj.page/reference/react/cook-mode.md#cookmode) renders a switch that keeps the reader's screen on while they cook, so it doesn't dim or lock between steps. It asks the browser through the Screen Wake Lock API. It must be inside a [`<Recipe.Root>`](https://recipe-book.siraj.page/reference/react/root.md).

[Try the live demo of Recipe.CookMode](https://recipe-book.siraj.page/reference/react/cook-mode/)

## `CookMode`

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

export function KeepAwake({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.CookMode className="cook-mode" />
    </Recipe.Root>
  )
}
```

On the server, `KeepAwake` renders this HTML:

```html
<button autoComplete="off" class="cook-mode" type="button" role="switch" aria-checked="false" disabled="" data-recipe-cook-mode="" data-state="unchecked" data-disabled="">Keep screen on</button>
```

The server can't tell whether the reader's browser can keep the screen on, so the switch renders disabled until React hydrates the page. Then it's enabled, or gone in a browser without the API, as [Browsers without the API](https://recipe-book.siraj.page/reference/react/cook-mode.md#browsers-without-the-api) says. A switch that first renders in the browser, such as after a client-side navigation, is enabled or gone from the start. The file needs no `'use client'`, because the parts are already [Client Components](https://recipe-book.siraj.page/reference/react/root.md#root).

A click turns the switch on, with `aria-checked="true"`, and asks the browser to keep the screen on. Another click turns it off and lets the screen dim again. The browser lets the screen dim whenever the page is hidden, such as in another tab, and the switch asks again when the page is shown, so it stays on. When the browser refuses or lets the screen dim while the page is visible, as Firefox does when the battery is at 5% or less and not charging, the switch turns off. A refusal also logs a [development warning](https://recipe-book.siraj.page/errors.md#warning-wake-lock). In Firefox, the switch still turns on while the battery is that low, but the screen dims anyway. On iOS and iPadOS from version 16.4 but before version 18.4, in a page that opens from the Home Screen as its own app, the switch stays on, but the screen dims anyway. A switch that unmounts lets the screen dim. So does a switch that React 19.2's `<Activity mode="hidden">` hides, though it stays on and asks again when it's shown.

To style the switch, [pass a `className`](https://recipe-book.siraj.page/guides/style-a-recipe.md#pass-classname-and-style).

| Name              | Type                                           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------- | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `checked`         | `boolean \| undefined`                         | Whether the switch is on, for a [controlled](https://recipe-book.siraj.page/reference/react/cook-mode.md#controlled-and-uncontrolled) switch. In Safari, a switch that's on when it renders, or that you turn on, with no click shortly before calls `onCheckedChange(false)` right away, unless Safari has granted the page a wake lock since it loaded, as with `defaultChecked`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `defaultChecked`  | `boolean \| undefined`                         | Whether the switch starts on, for an uncontrolled switch. Defaults to `false`. Safari refuses a wake lock that the page requests with no click or other user gesture shortly before, unless it has granted the page one since the page loaded. So in Safari, a switch that starts on and renders with no click shortly before, such as one in the page's server HTML, turns off right away and logs the [development warning](https://recipe-book.siraj.page/errors.md#warning-wake-lock) `Recipe Book: <Recipe.CookMode> can't keep the screen on, so it turned off: NotAllowedError: Permission was denied. In a cross-origin iframe, the iframe needs allow="screen-wake-lock".` One that first renders shortly after a click, such as after a client-side navigation from a link, stays on. Chrome and Firefox keep it on either way, except on iOS and iPadOS, where they use WebKit as Safari does. |
| `onCheckedChange` | `((checked: boolean) => void) \| undefined`    | Called with the new value when a click turns the switch on or off, and with `false` when the switch turns off on its own.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `asChild`         | `boolean \| undefined`                         | Renders the switch as its one element child instead of a `<button>`. See [Render your own element](https://recipe-book.siraj.page/reference/react/cook-mode.md#render-your-own-element). Defaults to `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `autoComplete`    | `string \| undefined`                          | The button's `autocomplete` attribute. Defaults to `'off'`, so when going back reloads the page, Firefox doesn't re-enable a switch that the server rendered disabled and the page enabled later. `null` (from JavaScript, or without `strictNullChecks`) leaves the attribute out.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `children`        | `ReactNode \| undefined`                       | The switch's text, and its accessible name unless it has a non-empty `aria-label`, an `aria-labelledby` whose element has text, or a `<label>`. Defaults to [`labels.cookMode`](https://recipe-book.siraj.page/reference/react/cook-mode.md#labels).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `disabled`        | `boolean \| undefined`                         | Disables the switch, so a click doesn't turn it on or off. A switch that's on when it's disabled stays on. Defaults to `false`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `type`            | `'submit' \| 'reset' \| 'button' \| undefined` | The button's type. Defaults to `'button'`, so the switch doesn't submit a form.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |

Any other `<button>` prop passes to the `<button>`, except `role`, `aria-checked`, and the [data attributes](https://recipe-book.siraj.page/reference/react/cook-mode.md#style-with-data-attributes), which the switch sets itself. An [`asChild`](https://recipe-book.siraj.page/reference/react/cook-mode.md#render-your-own-element) child's own `role`, `aria-checked`, or data attribute wins over the switch's. The switch renders its own content, so it doesn't take `dangerouslySetInnerHTML`. A `ref` reaches the `<button>`. Your `onClick` runs before the switch's own. Call `event.preventDefault()` in it to stop a click from turning the switch on or off.

### Browsers without the API

In a browser without the Screen Wake Lock API, such as Chrome and Edge before version 84, Firefox before version 126, and Safari before version 16.4, `<Recipe.CookMode>` renders nothing once React hydrates the page: no element, so no gap or margin where the switch was. The API also needs a secure context, so on a page served over plain HTTP from anywhere but `localhost`, a `.localhost` name, or a loopback address such as `127.0.0.1` or `[::1]`, the switch renders nothing too, including at a local network address you open on a phone.

A wrapper of your own around the switch stays, with its padding, border, and anything else in it. To have it all go with the switch, put the wrapper's text inside the switch's `children`, and style the switch instead of the wrapper:

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

export function KeepAwake({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.CookMode className="cook-mode">
        Keep screen on <small>while you cook</small>
      </Recipe.CookMode>
    </Recipe.Root>
  )
}
```

On the server, `KeepAwake` renders:

```html
<button autoComplete="off" class="cook-mode" type="button" role="switch" aria-checked="false" disabled="" data-recipe-cook-mode="" data-state="unchecked" data-disabled="">Keep screen on <small>while you cook</small></button>
```

In an iframe from another origin, the browser refuses unless the iframe has `allow="screen-wake-lock"`, so the switch turns off as soon as it's clicked. An iframe from the page's own origin needs nothing.

## Controlled and uncontrolled

The switch is uncontrolled unless you pass `checked`, as the Root's [servings and system](https://recipe-book.siraj.page/reference/react/root.md#controlled-and-uncontrolled-state) are, with the same [development warnings](https://recipe-book.siraj.page/errors.md#warning-read-only). Control it to read it outside the switch, as this note does:

```tsx {1,8,12-13}
'use client'

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

export function Method({ recipe }: { recipe: ParsedRecipe }) {
  const [awake, setAwake] = useState(false)

  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.CookMode checked={awake} onCheckedChange={setAwake} />
      {awake && <p>Your screen stays on while this page is open.</p>}
      <Recipe.Steps />
    </Recipe.Root>
  )
}
```

`Method` passes a function to the switch, so it starts with `'use client'`.

On React 19, a switch can keep the server's `aria-checked="false"` and `data-state="unchecked"` while the screen stays on, or its `aria-checked="true"` and `data-state="checked"` while nothing keeps the screen on. That happens when it reads `checked` from your own context inside a Suspense boundary that hydrates late, such as one waiting for a lazy component's code, and the context changes it before the boundary hydrates, such as with a value restored from storage. Render the switch outside that boundary.

## Labels

Set the [`cookMode` label](https://recipe-book.siraj.page/reference/react/provider.md#recipelabels) with `labels` on the Root or a provider, in a pack from [`labelPack`](https://recipe-book.siraj.page/reference/react/labels.md#labelpack). Make the pack once, in a `'use client'` module:

```tsx {5,7,11}
'use client'

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

const labels = labelPack({ cookMode: 'Mantener la pantalla encendida' })

export function PantallaEncendida({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe} labels={labels}>
      <Recipe.CookMode />
    </Recipe.Root>
  )
}
```

On the server, `PantallaEncendida` renders:

```html
<button autoComplete="off" type="button" role="switch" aria-checked="false" disabled="" data-recipe-cook-mode="" data-state="unchecked" data-disabled="">Mantener la pantalla encendida</button>
```

## Render your own element

With `asChild`, the switch renders its one element child instead of its own `<button>`, and passes its props to it, including its role, ARIA attributes, `data-recipe-*` attributes, and `ref`. 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.

A `<button type={undefined}>` child renders without `type="button"`, so inside a `<form>`, a click on it submits the form. A component that passes its own optional props, such as `type`, `role`, `autoComplete`, or `aria-*` attributes, on to the child should leave out each one it has no value for, such as with `{...(type === undefined ? {} : { type })}`, rather than pass `undefined`.

Render a `<button>` or a component that renders one, so Space and Enter press it, and a disabled switch reads as disabled to screen readers and doesn't take focus on a click. A `disabled` set on the child disables the switch as the switch's own `disabled` does: a click doesn't turn it on or off, and it has `data-disabled`.

The child's own children take the place of the switch's, so an element child, other than a Fragment, whose children are `undefined`, `null`, `true`, or `false` gets the `cookMode` label, but `''`, `[]`, or an empty Fragment leave the button empty. Here, the `Pill` with no children shows it:

```tsx {12-14}
import type { ParsedRecipe } from '@recipe-book/react/core'
import * as Recipe from '@recipe-book/react'
import type { ComponentProps } from 'react'

function Pill(props: ComponentProps<'button'>) {
  return <button className="pill" {...props} />
}

export function KeepAwake({ recipe }: { recipe: ParsedRecipe }) {
  return (
    <Recipe.Root recipe={recipe}>
      <Recipe.CookMode asChild>
        <Pill />
      </Recipe.CookMode>
    </Recipe.Root>
  )
}
```

On the server, `KeepAwake` renders:

```html
<button class="pill" autoComplete="off" type="button" role="switch" aria-checked="false" disabled="" data-recipe-cook-mode="" data-state="unchecked" data-disabled="">Keep screen on</button>
```

The switch re-renders its child as soon as the page hydrates, to check whether the browser has the API. So a Suspense boundary that the child component renders itself, such as one around a lazy icon inside `Pill`, gives up its server HTML for its fallback when its code hasn't loaded yet. On React 18, React also reports a recoverable error for the boundary, to `hydrateRoot`'s `onRecoverableError` or else the browser's console. Render lazy content beside the switch, or pass it to the child as children, to keep it.

`asChild` needs one element child. With anything else, such as no children, text, several children, or a Fragment, the switch renders its own `<button>` instead, with those children, or with its label when they're `undefined`, `null`, `true`, or `false`. In development, the first `<Recipe.CookMode>` to do this logs a [development warning](https://recipe-book.siraj.page/errors.md#warning-as-child).

## Style with data attributes

The switch has `data-recipe-cook-mode`, `data-state`, which is `checked` while it's on and `unchecked` while it's off, and `data-disabled` while it's disabled. [Style a recipe](https://recipe-book.siraj.page/guides/style-a-recipe.md#data-attributes) lists every data attribute that the parts set. This CSS fills the switch while it's on and dims it while it's disabled:

```css
[data-recipe-cook-mode][data-state='checked'] {
  background: black;
  color: white;
}

[data-recipe-cook-mode][data-disabled] {
  opacity: 0.5;
}
```

## Errors

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

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

## Types

`@recipe-book/react` exports the props type as `RecipeCookModeProps`, to type a component that wraps the switch:

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

export function KeepAwake(props: Recipe.RecipeCookModeProps) {
  return <Recipe.CookMode className="cook-mode" {...props} />
}
```

## Named imports

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