4.16React reference
Provider
Reference for <Recipe.Provider>, which sets the default locale, labels, and starting measurement system for every Root inside it.
<Recipe.Provider> sets defaults for every <Recipe.Root> inside it, so you don’t repeat them on each recipe. It renders no element of its own, so wrapping a layout in it doesn’t change the layout’s HTML. It’s optional, and you can nest one provider inside another. A provider from another copy of @recipe-book/react is ignored without a warning, so load one copy.
Provider
import * as Recipe from '@recipe-book/react'
import type { ReactNode } from 'react'
export default function RecipesLayout({ children }: { children: ReactNode }) {
return (
<Recipe.Provider defaultSystem="metric">
{children}
</Recipe.Provider>
)
}Every Root under app/recipes/ starts in metric, including Roots for recipes written in US units, unless a Root sets its own defaultSystem or passes system, which makes the system controlled. The provider takes only data, so it can wrap a layout that’s a Server Component, like this one. Put it in the layout of the routes that render recipes rather than in app/layout.tsx: @recipe-book/react is one client module, so a layout that renders the provider ships every part the app uses, up to 21.18 kB minified and gzipped without the parser, even to pages that render no parts.
| Name | Type | Description |
|---|---|---|
locale |
string | undefined |
A language tag that Intl accepts, such as 'de-DE', for formatting numbers. Defaults to the outer provider’s locale, then 'en-US'. The provider doesn’t check it: with a tag Intl rejects, such as 'en_US', the parts that write numbers throw invalid_argument when they have one to write, and <Recipe.Ingredient> throws even for a line with no number, such as “salt, to taste”. In a runtime without Intl, none of them throws for any locale string, even 'en_US', and they write the numbers in English, as the ingredients page says for its parts. Render the server and the browser with the same locale and the same Intl locale support, or React reports a hydration mismatch in the parts that write numbers; see the caution under FormatOptions. The caution under Root names those parts. |
labels |
RecipeLabelPack | undefined |
A label pack: a language’s from @recipe-book/react/labels, or one made with its labelPack. The controls’ text merges key by key: a key the pack doesn’t set keeps the outer provider’s value, then the default. The words for units and sizes come from the nearest pack alone, so a pack of the controls’ text alone writes units in English. Under every pack, <Recipe.Times> writes its durations in English, <Recipe.Nutrition> writes kcal, g, and mg, and temperatures show as °C and °F, so no part writes a pack’s durations or temperature words. Make the pack once, such as at module scope: a new one each render re-renders most parts. A copy from a loader or JSON isn’t a pack. In every build, a value that isn’t a pack, such as 'de' or a plain object, throws invalid_argument, and so does a pack a Server Component passes that it didn’t import by name from a client module, such as @recipe-book/react/labels or a 'use client' module of yours: one it made, say, or core’s de from @recipe-book/react/core/labels. In client code, one of core’s packs, from @recipe-book/core/labels or @recipe-book/react/core/labels, passes with no error or warning, but the controls get no text from it: with locale="de-DE" and no outer provider that sets them, <Recipe.ServingsSelect> and <Recipe.SystemToggle> read “2 servings … Metric US” under core’s de, where the de from @recipe-book/react/labels gives “2 Portionen … Metrisch USA”. For translated controls, use the pack from @recipe-book/react/labels. |
defaultSystem |
System | undefined |
The default measurement system for each Root and useRecipeState() call below the provider, unless it or a nearer provider sets its own. Defaults to the outer provider’s defaultSystem, then the system the recipe was written in, then 'metric'. A value other than 'metric' or 'us' counts as missing, with a development warning. |
children |
ReactNode | undefined |
The part of the app that uses these defaults. |
@recipe-book/react exports the props type as RecipeBookProviderProps. Use it to type a component that wraps the provider.
useRecipeState() reads only defaultSystem.
Labels
labels replaces the built-in text that parts render or announce, and the words they write for units. For one language, import its pack from @recipe-book/react/labels, which covers units and the controls’ text, as in Translate the built-in text. The packs leave out the US units oz, lb, fl-oz, cup, pint, quart, and gallon and the 250 mL cup-metric, which keep their English labels. They don’t label handful, jar, stalk, and bag yet either, so those stay in English too. The terms of <Recipe.Times> and <Recipe.Nutrition> and the text of <Recipe.CookMode> stay in English unless you set them.
RecipeLabels
type RecipeLabels = {
readonly language?: LabelWords['language']
readonly units?: LabelWords['units']
readonly durations?: LabelWords['durations']
readonly temperature?: LabelWords['temperature']
readonly size?: LabelWords['size']
readonly servings: string
readonly servingUnit: { readonly one: string; readonly other: string }
readonly system: string
readonly metric: string
readonly us: string
readonly fan: string
readonly optional: string
readonly to: string
readonly prepTime: string
readonly cookTime: string
readonly totalTime: string
readonly servingSize: string
readonly calories: string
readonly fat: string
readonly saturatedFat: string
readonly transFat: string
readonly unsaturatedFat: string
readonly carbohydrates: string
readonly sugar: string
readonly fiber: string
readonly protein: string
readonly sodium: string
readonly cholesterol: string
readonly cookMode: string
}All the built-in text but three kinds, which no key sets: the durations <Recipe.Times> writes, which stay in English, as in “1 hr 15 min”; the units <Recipe.Nutrition> writes, kcal, g, and mg; and the °C and °F of temperatures. The first five keys are core’s LabelWords.
| Name | Type | Description |
|---|---|---|
language |
string | undefined |
The language of the words, such as 'de', as in LabelWords. Picks the plural forms of the units’ words, of servingUnit, and of a yield’s words or an ingredient’s name after a bare count, so with fr, 1.5 eggs read “1 ½ egg”. Defaults to English. |
units |
LabelWords['units'] | undefined |
The words for units by unit id, for ingredient quantities, the yield <Recipe.YieldText> writes in a mass or volume unit for a recipe whose servings have a valid amount, and the quantities <Recipe.ConvertedStepText> converts, as in LabelWords. A unit you leave out is written in English, because a pack’s words replace the outer pack’s whole. |
durations |
LabelWords['durations'] | undefined |
The words for durations, as in LabelWords, which keep a pack whole when you pass it to core’s formatDuration. <Recipe.Times> doesn’t read them: it writes its durations in English under every pack. Defaults to English. |
temperature |
LabelWords['temperature'] | undefined |
The long form of temperatures, as in LabelWords. No part writes it, because <Recipe.StepText> and <Recipe.ConvertedStepText> write the short form, as in “180 °C”. Defaults to English. |
size |
LabelWords['size'] | undefined |
The words after a count unit’s size, each and total, as in LabelWords: <Recipe.IngredientQuantity> writes 2 Dosen (425 g pro Stück) under de. Defaults to English, “each” and “total”. |
servings |
string |
The accessible name of <Recipe.ServingsSelect> and <Recipe.ServingsInput>, unless they get an aria-label or an aria-labelledby whose element has text. Defaults to 'Servings'. |
servingUnit |
{ readonly one: string; readonly other: string } |
The unit after a number of servings, as in “1 serving” and “4 servings”, for a recipe with servings. one and other follow the plural rule of language, as LabelWords describes, and English without one: one follows 1 and a fraction below 1, such as “½ serving”, and other follows a number that prints as a decimal and every other number, such as “0.3 servings” and “1 ½ servings”. Defaults to { one: 'serving', other: 'servings' }. |
system |
string |
The accessible name of <Recipe.SystemToggle>, unless it gets an aria-label or an aria-labelledby whose element has text. Defaults to 'Measurement system'. |
metric |
string |
The text of a <Recipe.SystemOption> for 'metric', and its accessible name unless it has a non-empty aria-label, an aria-labelledby whose element has text, or a <label>, in place of its children when they’re undefined, null, true, or false, or with asChild in its element child, other than a Fragment, when its own children are too. Any other children replace it, so give an icon-only option an aria-label. Defaults to 'Metric'. |
us |
string |
The text of a <Recipe.SystemOption> for 'us', and its accessible name unless it has a non-empty aria-label, an aria-labelledby whose element has text, or a <label>, in the same cases as metric. Defaults to 'US'. |
fan |
string |
The marker after a fan-oven temperature in step text, as in “170 °C fan”. Defaults to 'fan'. |
optional |
string |
The marker after an optional ingredient, shown as is, punctuation included, as in “1 tbsp honey (optional)”. Defaults to '(optional)'. |
to |
string |
Spoken between the ends of an ingredient’s quantity range, as in “2 to 3 tbsp”, for screen readers only, but not a size’s range, as in “2 cans (425–454 g each)”, or a range in other text, such as <Recipe.StepText> or <Recipe.ServingsText>. The visible text keeps its dash, as in “2–3 tbsp”. Defaults to 'to'. |
prepTime |
string |
The term for the prep time in <Recipe.Times>. Defaults to 'Prep time'. |
cookTime |
string |
The term for the cook time in <Recipe.Times>. Defaults to 'Cook time'. |
totalTime |
string |
The term for the total time in <Recipe.Times>. Defaults to 'Total time'. |
servingSize |
string |
The term for the serving size in <Recipe.Nutrition>. Defaults to 'Serving size'. |
calories |
string |
The term for calories in <Recipe.Nutrition>. Defaults to 'Calories'. |
fat |
string |
The term for fat in <Recipe.Nutrition>. Defaults to 'Fat'. |
saturatedFat |
string |
The term for saturated fat in <Recipe.Nutrition>. Defaults to 'Saturated fat'. |
transFat |
string |
The term for trans fat in <Recipe.Nutrition>. Defaults to 'Trans fat'. |
unsaturatedFat |
string |
The term for unsaturated fat in <Recipe.Nutrition>. Defaults to 'Unsaturated fat'. |
carbohydrates |
string |
The term for carbohydrates in <Recipe.Nutrition>. Defaults to 'Carbohydrates'. |
sugar |
string |
The term for sugar in <Recipe.Nutrition>. Defaults to 'Sugar'. |
fiber |
string |
The term for fiber in <Recipe.Nutrition>. Defaults to 'Fiber'. |
protein |
string |
The term for protein in <Recipe.Nutrition>. Defaults to 'Protein'. |
sodium |
string |
The term for sodium in <Recipe.Nutrition>. Defaults to 'Sodium'. |
cholesterol |
string |
The term for cholesterol in <Recipe.Nutrition>. Defaults to 'Cholesterol'. |
cookMode |
string |
The text of <Recipe.CookMode>. It shows in place of the switch’s children when they’re undefined, null, true, or false. With asChild, it shows in the element child, other than a Fragment, when that child’s children are any of those. It’s also the switch’s accessible name unless the switch has a non-empty aria-label, an aria-labelledby whose element has text, or a <label>. Children of your own replace it, so give an icon-only switch an aria-label. Children of '', [], or an empty Fragment leave the button empty. Defaults to 'Keep screen on'. |
RecipeLabelOverrides
type RecipeLabelOverrides = {
[Key in keyof RecipeLabels]?: RecipeLabels[Key] | undefined
}Any of the keys of RecipeLabels, which labelPack makes into a pack for labels. Each key replaces the outer value whole, so servingUnit needs both one and other. In the controls’ text, an undefined or null value keeps the outer value. language, units, durations, temperature, and size come from the nearest pack alone, so a pack’s words replace the outer pack’s whole. Change one word shows a changed pack on a Root.
RecipeLabelPack
type RecipeLabelPack = RecipeLabelOverrides & LabelPackA pack from @recipe-book/react/labels: a language’s, such as de, or one from its labelPack. Type a value that holds one with it, such as a map of packs by language. It has the keys of RecipeLabelOverrides rather than of RecipeLabels, because the packs leave some of them out. LabelPack marks it as a pack, which a plain object of the same keys isn’t.
'use client'
import type { RecipeLabelPack } from '@recipe-book/react'
import { de, fr } from '@recipe-book/react/labels'
const packs: Record<string, RecipeLabelPack | undefined> = { de, fr }Named imports
To import <Recipe.Provider> by name, import Provider. If the name clashes with one of yours, alias it, as in import { Provider as RecipeBookProvider } from '@recipe-book/react'.