diff --git a/.github/ISSUE_TEMPLATE/0-bug.yml b/.github/ISSUE_TEMPLATE/0-bug.yml new file mode 100644 index 000000000..4bb06d0f0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/0-bug.yml @@ -0,0 +1,34 @@ +name: "🐛 Signaler un bug" +description: "Signale un bug sur le site web." +title: "[Bug]: " +labels: ["bug: unconfirmed"] +body: + - type: textarea + attributes: + label: RĂ©sumĂ© + description: | + Un rĂ©sumĂ© clair et concis du bug. + placeholder: | + Exemple de rapport de bug : + Lorsque je clique sur le bouton « Envoyer » des retours, rien ne se passe. + validations: + required: true + - type: input + attributes: + label: Page + description: | + Sur quelle page avez-vous constatĂ© le bug ? + placeholder: | + https://fr.react.dev/ + validations: + required: true + - type: textarea + attributes: + label: DĂ©tails + description: | + Veuillez fournir tout dĂ©tail complĂ©mentaire utile sur ce bug. + placeholder: | + Exemples de dĂ©tails : + Le bouton « Envoyer » ne rĂ©agit pas. J'ai tentĂ© de rafraĂźchir la page et d'utiliser un autre navigateur, mais le problĂšme persiste. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/1-typo.yml b/.github/ISSUE_TEMPLATE/1-typo.yml new file mode 100644 index 000000000..c376a78f5 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/1-typo.yml @@ -0,0 +1,34 @@ +name: "đŸ€Š Typo ou erreur" +description: "Signale une typo ou une erreur dans les docs." +title: "[Typo]: " +labels: ["type: typos"] +body: + - type: textarea + attributes: + label: RĂ©sumĂ© + description: | + Un rĂ©sumĂ© clair et concis du bug. + placeholder: | + Exemple : + L'exemple de code sur la page "useReducer" comporte une variable `nextId` inutilisĂ©e. + validations: + required: true + - type: input + attributes: + label: Page + description: | + Sur quelle page avez-vous constatĂ© la typo ? + placeholder: | + https://fr.react.dev/ + validations: + required: true + - type: textarea + attributes: + label: DĂ©tails + description: | + Veuillez fournir tout dĂ©tail complĂ©mentaire utile pour comprendre la nature de l'erreur. + placeholder: | + Exemple d'erreur : + Dans la section « useReducer » de la page « RĂ©fĂ©rence de l'API », l'exemple de code pour la partie « Écrire la fonction de rĂ©duction » comporte une variable `nextId` qui devrait ĂȘtre retirĂ©e. + validations: + required: false diff --git a/.github/ISSUE_TEMPLATE/2-suggestion.yml b/.github/ISSUE_TEMPLATE/2-suggestion.yml new file mode 100644 index 000000000..80e141ad6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/2-suggestion.yml @@ -0,0 +1,34 @@ +name: "💡 Suggestions" +description: "SuggĂšre une nouvelle page, section ou mise Ă  jour d'une page existante." +title: "[Suggestion]: " +labels: ["type: documentation"] +body: + - type: textarea + attributes: + label: RĂ©sumĂ© + description: | + Un rĂ©sumĂ© clair et concis de ce que nous devrions ajouter. + placeholder: | + Exemple : + Ajouter une page dĂ©crivant l'utilisation de React avec TypeScript. + validations: + required: true + - type: input + attributes: + label: Page + description: | + De quelle page s'agit-il ? + placeholder: | + https://fr.react.dev/ + validations: + required: false + - type: textarea + attributes: + label: DĂ©tails + description: | + Veuillez nous expliquer ce que vous suggĂ©rez. + placeholder: | + Exemple : + Je pense qu'il serait utile d'avoir une page expliquant comment utiliser React avec TypeScript. Elle pourrait inclure un exemple simple de composant Ă©crit en TypeScript, et faire les liens adĂ©quats vers la documentation de TypeScript. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/3-framework.yml b/.github/ISSUE_TEMPLATE/3-framework.yml new file mode 100644 index 000000000..b16a38fbc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/3-framework.yml @@ -0,0 +1,116 @@ +name: "📄 SuggĂ©rer un nouveau framework" +description: "Je suis l'auteur·e d'unframework et j'aimerais qu'il fasse partie des frameworks recommandĂ©s." +title: "[Framework]: " +labels: ["type: framework"] +body: + - type: markdown + attributes: + value: | + ## Candidature pour l'inclusion d'un framework React recommandĂ© + + _Ce formulaire s'adresse aux auteur·es de framework qui souhaitent candidater pour qu'il fasse partie de la liste des [frameworks React](https://react.dev/learn/start-a-new-react-project) recommandĂ©s. Si vous n'ĂȘtes pas l'auteur·e du framework, contactez ses auteur·es pour leur suggĂ©rer de candidater._ + + Lorsque nous recommandons un framework, nous le faisons afin que les dĂ©veloppeur·ses puissent dĂ©marrer avec un projet React qui s'occupe d'entrĂ©e de jeu de sujets rĂ©currents tels que la dĂ©coupe de code, le chargement de donnĂ©es, le routage et la gĂ©nĂ©ration du HTML, sans avoir Ă  fournir un travail complĂ©mentaire. Nous estimons que ça permettra aux gens de dĂ©marrer plus vite avec React, et de faire monter leur application Ă  l'Ă©chelle en production. + + MĂȘme si nous comprenons bien que de nombreux frameworks aimeraient ĂȘtre inclus dans la liste, cette page n'est pas lĂ  pour faire la publicitĂ© de tous les frameworks React potentiels, ou de tous les frameworks auxquels React peut ĂȘtre intĂ©grĂ©. Il existe de nombreux superbes frameworks capables d'intĂ©grer React mais que nous ne listons pas dans nos guides. Les frameworks que nous recommandons ont investi de façon significative dans l'Ă©cosystĂšme React, et collaborĂ© avec l'Ă©quipe React pour ĂȘtre compatible avec notre [vision d'une architecture React full-stack](https://fr.react.dev/learn/start-a-new-react-project#which-features-make-up-the-react-teams-full-stack-architecture-vision). + + Pour ĂȘtre inclus dans la liste, un framework doit satisfaire les critĂšres suivants : + + - **Open-source et gratuit** : il doit ĂȘtre en logiciel libre et son utilisation gratuite. + - **Bonne maintenance** : il doit ĂȘtre activement maintenu, avec correctifs et amĂ©liorations. + - **CommunautĂ© active** : il doit disposer d'une communautĂ© suffisamment large et vivante pour aider ses utilisateurs. + - **Adoption facile** : il doit disposer d'Ă©tapes claires pour l'installation de la version React du framework. + - **Compatible avec l'Ă©cosystĂšme** : il doit prendre en charge l'ensemble des bibliothĂšques et outils de l'Ă©cosystĂšme React. + - **Auto-hĂ©bergement possible** : il doit permettre l'auto-hĂ©bergement d'applications sans que cela en limite les fonctionnalitĂ©s. + - **ExpĂ©rience de dĂ©veloppement (DX)** : il doit permettre aux dĂ©veloppeur·ses d'ĂȘtre productif·ves grĂące Ă  des fonctionnalitĂ©s telles que _Fast Refresh_. + - **ExpĂ©rience utilisateur (UX)** : il doit fournir des solutions intĂ©grĂ©es aux problĂ©matiques usuelles telles que le routage et le chargement de donnĂ©es. + - **Compatible avec notre vision de l'avenir de React**. React Ă©volue avec le temps, et les frameworks qui ne s'alignent pas avec la direction que prend React risquent au fil du temps d'isoler leurs utilisateurs de l'Ă©cosystĂšme React principal. Pour vous inclure sur cette page, nous devons ĂȘtre confiants dans la capacitĂ© du framework Ă  placer ses utilisateurs durablement sur le chemin du succĂšs avec React. + + Notez bien que nous avons dĂ©jĂ  passĂ© en revue la plupart des frameworks populaires disponibles pour le moment, il est donc peu probable que nous n'ayons pas encore examinĂ© votre framework. Mais si vous pensez que nous avons loupĂ© quelque chose, veuillez remplir le formulaire ci-dessous. + - type: input + attributes: + label: Nom + description: | + Quel est le nom de votre framework ? + validations: + required: true + - type: input + attributes: + label: Page d'accueil + description: | + Quelle est l'URL de votre page d'accueil ? + validations: + required: true + - type: input + attributes: + label: Instructions d'installation + description: | + Quelle est l'URL de votre guide de dĂ©marrage ? + validations: + required: true + - type: dropdown + attributes: + label: Votre framework est-il open source ? + description: | + Nous ne recommandons que les frameworks open source et gratuits. + options: + - 'Non' + - 'Oui' + validations: + required: true + - type: textarea + attributes: + label: Maintenance active + description: | + Veuillez dĂ©crire (en anglais) en quoi votre framework est activement maintenu. Fournissez des exemples rĂ©cents de versions publiĂ©es, correctifs et amĂ©liorations. + validations: + required: true + - type: textarea + attributes: + label: CommunautĂ© active + description: | + Veuillez dĂ©crire (en anglais) votre communautĂ©. Indiquez-en la taille et fournissez des liens sur les ressoures communautaires. + validations: + required: true + - type: textarea + attributes: + label: Adoption facile + description: | + Veuillez dĂ©crire (en anglais) comment une personne peut installer votre framework avec React. Fournissez les liens adĂ©quats vers votre documentation. + validations: + required: true + - type: textarea + attributes: + label: CompatibilitĂ© avec l'Ă©cosystĂšme + description: | + Veuillez dĂ©crire (en anglais) toute limite connue que votre framework aurait vis-Ă -vis de l'Ă©cosystĂšme React. Indiquez toute bibliothĂšque ou tout outil dont vous savez qu'il n'est pas compatible avec votre framework. + validations: + required: true + - type: textarea + attributes: + label: Auto-hĂ©bergement + description: | + Veuillez dĂ©crire (en anglais) en quoi votre framework permet l'auto-hĂ©bergement. Indiquez toute limitation connue de fonctionnalitĂ©s dans le cadre de l'auto-hĂ©bergement. Indiquez aussi s'il faut un serveur pour dĂ©ployer votre framework. + validations: + required: true + - type: textarea + attributes: + label: ExpĂ©rience de dĂ©veloppement (DX) + description: | + Veuillez dĂ©crire (en anglais) en quoi votre framework permet une super expĂ©rience de dĂ©veloppeemnt. Indiquez toute limite connue aux fonctionnalitĂ©s telles que les outils de dĂ©veloppement React, ceux de Chrome ou encore le Fast Refresh. + validations: + required: true + - type: textarea + attributes: + label: ExpĂ©rience utilisateur (UX) + description: | + Veuillez dĂ©crire (en anglais) en quoi votre framework aide les gens Ă  crĂ©er une expĂ©rience utilisateur de grande qualitĂ©, en s'occupant directement des problĂ©matiques courantes. Indiquez par exemple en quoi vous gĂ©rez nativement la dĂ©coupe de code, le routage, la gĂ©nĂ©ration de HTML ou le chargement de donnĂ©es d'une façon qui Ă©vite par dĂ©faut les cascades de requĂȘtes client/serveur. DĂ©taillez la façon dont vous permettez des approches telles que SSG ou SSR. + validations: + required: true + - type: textarea + attributes: + label: Compatible avec notre vision de l'avenir de React + description: | + Veuillez dĂ©crire (en anglais) en quoi votre framework est alignĂ© avec notre vision de l'avenir de React. Indiquez comment votre framework Ă©voluera avec React, et quels sont vos plans pour prendre en charge les fonctionnalitĂ©s Ă  venir de React telles que les React Server Components. + validations: + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 000000000..b8d428c56 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,7 @@ +contact_links: + - name: 📃 Bugs dans React + url: https://github.com/facebook/react/issues/new/choose + about: Ce suivi de tickets ne sert pas aux bugs dans React. DĂ©posez vos tickets React plutĂŽt lĂ -bas. + - name: đŸ€” Questions et Aide + url: https://react.dev/community + about: Ce suivi de tickets ne sert pas au support technique. Consultez plutĂŽt l'aide communautaire de React et les forums de discussion. diff --git a/src/components/MDX/InlineCode.tsx b/src/components/MDX/InlineCode.tsx index d206e9888..0e8db0165 100644 --- a/src/components/MDX/InlineCode.tsx +++ b/src/components/MDX/InlineCode.tsx @@ -5,7 +5,8 @@ import cn from 'classnames'; interface InlineCodeProps { - isLink: boolean; + isLink?: boolean; + meta?: string; } function InlineCode({ isLink, diff --git a/src/components/MDX/MDXComponents.tsx b/src/components/MDX/MDXComponents.tsx index 2d5778205..fe3b9ac8c 100644 --- a/src/components/MDX/MDXComponents.tsx +++ b/src/components/MDX/MDXComponents.tsx @@ -19,6 +19,7 @@ import Link from './Link'; import {PackageImport} from './PackageImport'; import Recap from './Recap'; import Sandpack from './Sandpack'; +import SandpackWithHTMLOutput from './SandpackWithHTMLOutput'; import Diagram from './Diagram'; import DiagramGroup from './DiagramGroup'; import SimpleCallout from './SimpleCallout'; @@ -434,6 +435,7 @@ export const MDXComponents = { Recap, Recipes, Sandpack, + SandpackWithHTMLOutput, TeamMember, TerminalBlock, YouWillLearn, diff --git a/src/components/MDX/Sandpack/Preview.tsx b/src/components/MDX/Sandpack/Preview.tsx index 9669e5f4f..94fb50e90 100644 --- a/src/components/MDX/Sandpack/Preview.tsx +++ b/src/components/MDX/Sandpack/Preview.tsx @@ -188,7 +188,7 @@ export function Preview({ ? 'absolute opacity-0 pointer-events-none duration-75' : 'opacity-100 duration-150' )} - title="Sandbox Preview" + title="PrĂ©visualisation de la sandbox" style={{ height: iframeComputedHeight || '15px', zIndex: isExpanded ? 'initial' : -1, diff --git a/src/components/MDX/Sandpack/createFileMap.ts b/src/components/MDX/Sandpack/createFileMap.ts index 85c7f09bf..615d34c9a 100644 --- a/src/components/MDX/Sandpack/createFileMap.ts +++ b/src/components/MDX/Sandpack/createFileMap.ts @@ -11,7 +11,10 @@ export const SUPPORTED_FILES = [AppJSPath, StylesCSSPath]; export const createFileMap = (codeSnippets: any) => { return codeSnippets.reduce( (result: Record, codeSnippet: React.ReactElement) => { - if ((codeSnippet.type as any).mdxName !== 'pre') { + if ( + (codeSnippet.type as any).mdxName !== 'pre' && + codeSnippet.type !== 'pre' + ) { return result; } const {props} = codeSnippet.props.children; diff --git a/src/components/MDX/SandpackWithHTMLOutput.tsx b/src/components/MDX/SandpackWithHTMLOutput.tsx new file mode 100644 index 000000000..971610a9c --- /dev/null +++ b/src/components/MDX/SandpackWithHTMLOutput.tsx @@ -0,0 +1,85 @@ +import {Children, memo} from 'react'; +import InlineCode from './InlineCode'; +import Sandpack from './Sandpack'; + +const ShowRenderedHTML = ` +import { renderToStaticMarkup } from 'react-dom/server'; +import formatHTML from './formatHTML.js'; + +export default function ShowRenderedHTML({children}) { + const markup = renderToStaticMarkup( + + + {children} + + ); + return ( + <> +

HTML produit :

+
+        {formatHTML(markup)}
+      
+ + ); +}`; + +const formatHTML = ` +import format from 'html-format'; + +export default function formatHTML(markup) { + // Bidouilles pour formatter lisiblement le HTML -- je n'ai pas + // rĂ©ussi Ă  trouver un module tournant cĂŽtĂ© navigateur qui nettoie + // le HTML s'il n'a pas de retours-chariot. + return format(markup + .replace('', '\\n') + .replace('', '\\n') + .replaceAll(/<\\/script>/g, '<\\/script>\\n') + .replaceAll(/]*)\\/>/g, ' +``` + + + + + +--- + +## Reference {/*reference*/} + +### ` +``` + +[See more examples below.](#usage) + +#### Props {/*props*/} + +` + + 
 + + + ); +} + +export default function App() { + return ( + + + + ); +} +``` + + diff --git a/src/content/reference/react-dom/components/title.md b/src/content/reference/react-dom/components/title.md new file mode 100644 index 000000000..9d6ed18cc --- /dev/null +++ b/src/content/reference/react-dom/components/title.md @@ -0,0 +1,98 @@ +--- +title: "" +canary: true +--- + +<Canary> + +React's extensions to `<title>` are currently only available in React's canary and experimental channels. In stable releases of React `<title>` works only as a [built-in browser HTML component](https://react.dev/reference/react-dom/components#all-html-components). Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + +</Canary> + + +<Intro> + +The [built-in browser `<title>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) lets you specify the title of the document. + +```js +<title>My Blog +``` + + + + + +--- + +## Reference {/*reference*/} + +### `` {/*title*/} + +To specify the title of the document, render the [built-in browser `<title>` component](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title). You can render `<title>` from any component and React will always place the corresponding DOM element in the document head. + +```js +<title>My Blog +``` + +[See more examples below.](#usage) + +#### Props {/*props*/} + +`` supports all [common element props.](/reference/react-dom/components/common#props) + +* `children`: `<title>` accepts only text as a child. This text will become the title of the document. You can also pass your own components as long as they only render text. + +#### Special rendering behavior {/*special-rendering-behavior*/} + +React will always place the DOM element corresponding to the `<title>` component within the document’s `<head>`, regardless of where in the React tree it is rendered. The `<head>` is the only valid place for `<title>` to exist within the DOM, yet it’s convenient and keeps things composable if a component representing a specific page can render its `<title>` itself. + +There are two exception to this: +* If `<title>` is within an `<svg>` component, then there is no special behavior, because in this context it doesn’t represent the document’s title but rather is an [accessibility annotation for that SVG graphic](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/title). +* If the `<title>` has an [`itemProp`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/itemprop) prop, there is no special behavior, because in this case it doesn’t represent the document’s title but rather metadata about a specific part of the page. + +<Pitfall> + +Only render a single `<title>` at a time. If more than one component renders a `<title>` tag at the same time, React will place all of those titles in the document head. When this happens, the behavior of browsers and search engines is undefined. + +</Pitfall> + +--- + +## Usage {/*usage*/} + +### Set the document title {/*set-the-document-title*/} + +Render the `<title>` component from any component with text as its children. React will put a `<title>` DOM node in the document `<head>`. + +<SandpackWithHTMLOutput> + +```js App.js active +import ShowRenderedHTML from './ShowRenderedHTML.js'; + +export default function ContactUsPage() { + return ( + <ShowRenderedHTML> + <title>My Site: Contact Us +

Contact Us

+

Email us at support@example.com

+ + ); +} +``` + + + +### Use variables in the title {/*use-variables-in-the-title*/} + +The children of the `` component must be a single string of text. (Or a single number or a single object with a `toString` method.) It might not be obvious, but using JSX curly braces like this: + +```js +<title>Results page {pageNumber} // 🔮 Problem: This is not a single string +``` + +... actually causes the `` component to get a two-element array as its children (the string `"Results page"` and the value of `pageNumber`). This will cause an error. Instead, use string interpolation to pass `<title>` a single string: + +```js +<title>{`Results page ${pageNumber}`} +``` + diff --git a/src/content/reference/react-dom/index.md b/src/content/reference/react-dom/index.md index f39cc24af..85b91339c 100644 --- a/src/content/reference/react-dom/index.md +++ b/src/content/reference/react-dom/index.md @@ -17,6 +17,19 @@ Ces API peuvent ĂȘtre importĂ©es depuis vos composants. On les utilise rarement * [`createPortal`](/reference/react-dom/createPortal) vous permet d'afficher des composants enfants dans une autre partie de l'arbre du DOM. * [`flushSync`](/reference/react-dom/flushSync) vous permet de forcer React Ă  traiter les mises Ă  jour d'Ă©tat en attente, puis Ă  mettre Ă  jour le DOM de façon synchrone. +## API de prĂ©chargement de ressources {/*resource-preloading-apis*/} + +Ces API peuvent ĂȘtre utilisĂ©es pour accĂ©lĂ©rer vos applis en prĂ©chargeant des ressources telles que les scripts, feuilles de style et fontes dĂšs que vous savez que vous en aurez besoin, par exemple avant de naviguer sur une autre page qui utilisera ces ressources. + +[Les frameworks basĂ©s sur React](/learn/start-a-new-react-project) s'occupent frĂ©quemment pour vous du chargement des ressources, de sorte que vous n'aurez peut-ĂȘtre pas besoin d'appeler ces API vous-mĂȘme. Consultez la documentation de votre framework pour en savoir plus Ă  ce sujet. + +* [`prefetchDNS`](/reference/react-dom/prefetchDNS) vous permet de prĂ©charger l'adresse IP d'un nom de domaine DNS auquel vous anticipez une connexion. +* [`preconnect`](/reference/react-dom/preconnect) vous permet de vous connecter Ă  un serveur en vue d'y charger des ressources par la suite, mĂȘme si vous ne savez pas encore exactement lesquelles. +* [`preload`](/reference/react-dom/preload) vous permet de charger une feuille de styles, une fonte, une image ou un script externe dont vous anticipez l'utilisation. +* [`preloadModule`](/reference/react-dom/preloadModule) vous permet de charger un module ESM en vue de son utilisation imminente. +* [`preinit`](/reference/react-dom/preinit) vous permet de charger et d'Ă©valuer un script tiers ou de charger et insĂ©rer une feuille de style. +* [`preinitModule`](/reference/react-dom/preinitModule) vous permet de charget et Ă©valuer un module ESM. + --- ## Points d'entrĂ©e {/*entry-points*/} diff --git a/src/content/reference/react-dom/preconnect.md b/src/content/reference/react-dom/preconnect.md new file mode 100644 index 000000000..cb14a5e89 --- /dev/null +++ b/src/content/reference/react-dom/preconnect.md @@ -0,0 +1,96 @@ +--- +title: preconnect +canary: true +--- + + + +The `preconnect` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + + + +`preconnect` lets you eagerly connect to a server that you expect to load resources from. + +```js +preconnect("https://example.com"); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `preconnect(href)` {/*preconnect*/} + +To preconnect to a host, call the `preconnect` function from `react-dom`. + +```js +import { preconnect } from 'react-dom'; + +function AppRoot() { + preconnect("https://example.com"); + // ... +} + +``` + +[See more examples below.](#usage) + +The `preconnect` function provides the browser with a hint that it should open a connection to the given server. If the browser chooses to do so, this can speed up the loading of resources from that server. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the server you want to connect to. + + +#### Returns {/*returns*/} + +`preconnect` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple calls to `preconnect` with the same server have the same effect as a single call. +* In the browser, you can call `preconnect` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `preconnect` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. +* If you know the specific resources you'll need, you can call [other functions](/reference/react-dom/#resource-preloading-apis) instead that will start loading the resources right away. +* There is no benefit to preconnecting to the same server the webpage itself is hosted from because it's already been connected to by the time the hint would be given. + +--- + +## Usage {/*usage*/} + +### Preconnecting when rendering {/*preconnecting-when-rendering*/} + +Call `preconnect` when rendering a component if you know that its children will load external resources from that host. + +```js +import { preconnect } from 'react-dom'; + +function AppRoot() { + preconnect("https://example.com"); + return ...; +} +``` + +### Preconnecting in an event handler {/*preconnecting-in-an-event-handler*/} + +Call `preconnect` in an event handler before transitioning to a page or state where external resources will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { preconnect } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + preconnect('http://example.com'); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/content/reference/react-dom/prefetchDNS.md b/src/content/reference/react-dom/prefetchDNS.md new file mode 100644 index 000000000..f9889836e --- /dev/null +++ b/src/content/reference/react-dom/prefetchDNS.md @@ -0,0 +1,96 @@ +--- +title: prefetchDNS +canary: true +--- + + + +The `prefetchDNS` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + + + +`prefetchDNS` lets you eagerly look up the IP of a server that you expect to load resources from. + +```js +prefetchDNS("https://example.com"); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `prefetchDNS(href)` {/*prefetchdns*/} + +To look up a host, call the `prefetchDNS` function from `react-dom`. + +```js +import { prefetchDNS } from 'react-dom'; + +function AppRoot() { + prefetchDNS("https://example.com"); + // ... +} + +``` + +[See more examples below.](#usage) + +The prefetchDNS function provides the browser with a hint that it should look up the IP address of a given server. If the browser chooses to do so, this can speed up the loading of resources from that server. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the server you want to connect to. + +#### Returns {/*returns*/} + +`prefetchDNS` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple calls to `prefetchDNS` with the same server have the same effect as a single call. +* In the browser, you can call `prefetchDNS` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `prefetchDNS` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. +* If you know the specific resources you'll need, you can call [other functions](/reference/react-dom/#resource-preloading-apis) instead that will start loading the resources right away. +* There is no benefit to prefetching the same server the webpage itself is hosted from because it's already been looked up by the time the hint would be given. +* Compared with [`preconnect`](/reference/react-dom/preconnect), `prefetchDNS` may be better if you are speculatively connecting to a large number of domains, in which case the overhead of preconnections might outweigh the benefit. + +--- + +## Usage {/*usage*/} + +### Prefetching DNS when rendering {/*prefetching-dns-when-rendering*/} + +Call `prefetchDNS` when rendering a component if you know that its children will load external resources from that host. + +```js +import { prefetchDNS } from 'react-dom'; + +function AppRoot() { + prefetchDNS("https://example.com"); + return ...; +} +``` + +### Prefetching DNS in an event handler {/*prefetching-dns-in-an-event-handler*/} + +Call `prefetchDNS` in an event handler before transitioning to a page or state where external resources will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { prefetchDNS } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + prefetchDNS('http://example.com'); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/content/reference/react-dom/preinit.md b/src/content/reference/react-dom/preinit.md new file mode 100644 index 000000000..5a04528bd --- /dev/null +++ b/src/content/reference/react-dom/preinit.md @@ -0,0 +1,133 @@ +--- +title: preinit +canary: true +--- + + + +The `preinit` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + + + +[React-based frameworks](/learn/start-a-new-react-project) frequently handle resource loading for you, so you might not have to call this API yourself. Consult your framework's documentation for details. + + + + + +`preinit` lets you eagerly fetch and evaluate a stylesheet or external script. + +```js +preinit("https://example.com/script.js", {as: "style"}); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `preinit(href, options)` {/*preinit*/} + +To preinit a script or stylesheet, call the `preinit` function from `react-dom`. + +```js +import { preinit } from 'react-dom'; + +function AppRoot() { + preinit("https://example.com/script.js", {as: "script"}); + // ... +} + +``` + +[See more examples below.](#usage) + +The `preinit` function provides the browser with a hint that it should start downloading and executing the given resource, which can save time. Scripts that you `preinit` are executed when they finish downloading. Stylesheets that you preinit are inserted into the document, which causes them to go into effect right away. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the resource you want to download and execute. +* `options`: an object. It contains the following properties: + * `as`: a required string. The type of resource. Its possible values are `script` and `style`. + * `precedence`: a string. Required with stylesheets. Says where to insert the stylesheet relative to others. Stylesheets with higher precedence can override those with lower precedence. The possible values are `reset`, `low`, `medium`, `high`. + * `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`. It is required when `as` is set to `"fetch"`. + * `integrity`: a string. A cryptographic hash of the resource, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). + * `nonce`: a string. A cryptographic [nonce to allow the resource](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) when using a strict Content Security Policy. + * `fetchPriority`: a string. Suggests a relative priority for fetching the resource. The possible values are `auto` (the default), `high`, and `low`. + +#### Returns {/*returns*/} + +`preinit` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple calls to `preinit` with the same `href` have the same effect as a single call. +* In the browser, you can call `preinit` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `preinit` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. + +--- + +## Usage {/*usage*/} + +### Preiniting when rendering {/*preiniting-when-rendering*/} + +Call `preinit` when rendering a component if you know that it or its children will use a specific resource, and you're OK with the resource being evaluated and thereby taking effect immediately upon being downloaded. + + + +#### Preiniting an external script {/*preiniting-an-external-script*/} + +```js +import { preinit } from 'react-dom'; + +function AppRoot() { + preinit("https://example.com/script.js", {as: "script"}); + return ...; +} +``` + +If you want the browser to download the script but not to execute it right away, use [`preload`](/reference/react-dom/preload) instead. If you want to load an ESM module, use [`preinitModule`](/reference/react-dom/preinitModule). + + + +#### Preiniting a stylesheet {/*preiniting-a-stylesheet*/} + +```js +import { preinit } from 'react-dom'; + +function AppRoot() { + preinit("https://example.com/style.css", {as: "style", precedence: "medium"}); + return ...; +} +``` + +The `precedence` option, which is required, lets you control the order of stylesheets within the document. Stylesheets with higher precedence can overrule those with lower precedence. + +If you want to download the stylesheet but not to insert it into the document right away, use [`preload`](/reference/react-dom/preload) instead. + + + + + +### Preiniting in an event handler {/*preiniting-in-an-event-handler*/} + +Call `preinit` in an event handler before transitioning to a page or state where external resources will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { preinit } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + preinit("https://example.com/wizardStyles.css", {as: "style"}); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/content/reference/react-dom/preinitModule.md b/src/content/reference/react-dom/preinitModule.md new file mode 100644 index 000000000..ba6316a7a --- /dev/null +++ b/src/content/reference/react-dom/preinitModule.md @@ -0,0 +1,106 @@ +--- +title: preinitModule +canary: true +--- + + + +The `preinitModule` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + + + +[React-based frameworks](/learn/start-a-new-react-project) frequently handle resource loading for you, so you might not have to call this API yourself. Consult your framework's documentation for details. + + + + + +`preinitModule` lets you eagerly fetch and evaluate an ESM module. + +```js +preinitModule("https://example.com/module.js", {as: "script"}); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `preinitModule(href, options)` {/*preinitmodule*/} + +To preinit an ESM module, call the `preinitModule` function from `react-dom`. + +```js +import { preinitModule } from 'react-dom'; + +function AppRoot() { + preinitModule("https://example.com/module.js", {as: "script"}); + // ... +} + +``` + +[See more examples below.](#usage) + +The `preinitModule` function provides the browser with a hint that it should start downloading and executing the given module, which can save time. Modules that you `preinit` are executed when they finish downloading. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the module you want to download and exeucute. +* `options`: an object. It contains the following properties: + * `as`: a required string. It must be `'script'`. + * `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`. + * `integrity`: a string. A cryptographic hash of the module, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). + * `nonce`: a string. A cryptographic [nonce to allow the module](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) when using a strict Content Security Policy. + +#### Returns {/*returns*/} + +`preinitModule` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple calls to `preinitModule` with the same `href` have the same effect as a single call. +* In the browser, you can call `preinitModule` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `preinitModule` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. + +--- + +## Usage {/*usage*/} + +### Preloading when rendering {/*preloading-when-rendering*/} + +Call `preinitModule` when rendering a component if you know that it or its children will use a specific module and you're OK with the module being evaluated and thereby taking effect immediately upon being downloaded. + +```js +import { preinitModule } from 'react-dom'; + +function AppRoot() { + preinitModule("https://example.com/module.js", {as: "script"}); + return ...; +} +``` + +If you want the browser to download the module but not to execute it right away, use [`preloadModule`](/reference/react-dom/preloadModule) instead. If you want to preinit a script that isn't an ESM module, use [`preinit`](/reference/react-dom/preinit). + +### Preloading in an event handler {/*preloading-in-an-event-handler*/} + +Call `preinitModule` in an event handler before transitioning to a page or state where the module will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { preinitModule } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + preinitModule("https://example.com/module.js", {as: "script"}); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/content/reference/react-dom/preload.md b/src/content/reference/react-dom/preload.md new file mode 100644 index 000000000..ffec1177c --- /dev/null +++ b/src/content/reference/react-dom/preload.md @@ -0,0 +1,171 @@ +--- +title: preload +canary: true +--- + + + +The `preload` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + + + +[React-based frameworks](/learn/start-a-new-react-project) frequently handle resource loading for you, so you might not have to call this API yourself. Consult your framework's documentation for details. + + + + + +`preload` lets you eagerly fetch a resource such as a stylesheet, font, or external script that you expect to use. + +```js +preload("https://example.com/font.woff2", {as: "font"}); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `preload(href, options)` {/*preload*/} + +To preload a resource, call the `preload` function from `react-dom`. + +```js +import { preload } from 'react-dom'; + +function AppRoot() { + preload("https://example.com/font.woff2", {as: "font"}); + // ... +} + +``` + +[See more examples below.](#usage) + +The `preload` function provides the browser with a hint that it should start downloading the given resource, which can save time. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the resource you want to download. +* `options`: an object. It contains the following properties: + * `as`: a required string. The type of resource. Its [possible values](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#as) are `audio`, `document`, `embed`, `fetch`, `font`, `image`, `object`, `script`, `style`, `track`, `video`, `worker`. + * `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`. It is required when `as` is set to `"fetch"`. + * `referrerPolicy`: a string. The [Referrer header](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link#referrerpolicy) to send when fetching. Its possible values are `no-referrer-when-downgrade` (the default), `no-referrer`, `origin`, `origin-when-cross-origin`, and `unsafe-url`. + * `integrity`: a string. A cryptographic hash of the resource, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). + * `type`: a string. The MIME type of the resource. + * `nonce`: a string. A cryptographic [nonce to allow the resource](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) when using a strict Content Security Policy. + * `fetchPriority`: a string. Suggests a relative priority for fetching the resource. The possible values are `auto` (the default), `high`, and `low`. + * `imageSrcSet`: a string. For use only with `as: "image"`. Specifies the [source set of the image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). + * `imageSizes`: a string. For use only with `as: "image"`. Specifies the [sizes of the image](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). + +#### Returns {/*returns*/} + +`preload` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple equivalent calls to `preload` have the same effect as a single call. Calls to `preload` are considered equivalent according to the following rules: + * Two calls are equivalent if they have the same `href`, except: + * If `as` is set to `image`, two calls are equivalent if they have the same `href`, `imageSrcSet`, and `imageSizes`. +* In the browser, you can call `preload` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `preload` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. + +--- + +## Usage {/*usage*/} + +### Preloading when rendering {/*preloading-when-rendering*/} + +Call `preload` when rendering a component if you know that it or its children will use a specific resource. + + + +#### Preloading an external script {/*preloading-an-external-script*/} + +```js +import { preload } from 'react-dom'; + +function AppRoot() { + preload("https://example.com/script.js", {as: "script"}); + return ...; +} +``` + +If you want the browser to start executing the script immediately (rather than just downloading it), use [`preinit`](/reference/react-dom/preinit) instead. If you want to load an ESM module, use [`preloadModule`](/reference/react-dom/preloadModule). + + + +#### Preloading a stylesheet {/*preloading-a-stylesheet*/} + +```js +import { preload } from 'react-dom'; + +function AppRoot() { + preload("https://example.com/style.css", {as: "style"}); + return ...; +} +``` + +If you want the stylesheet to be inserted into the document immediately (which means the browser will start parsing it immediately rather than just downloading it), use [`preinit`](/reference/react-dom/preinit) instead. + + + +#### Preloading a font {/*preloading-a-font*/} + +```js +import { preload } from 'react-dom'; + +function AppRoot() { + preload("https://example.com/style.css", {as: "style"}); + preload("https://example.com/font.woff2", {as: "font"}); + return ...; +} +``` + +If you preload a stylesheet, it's smart to also preload any fonts that the stylesheet refers to. That way, the browser can start downloading the font before it's downloaded and parsed the stylesheet. + + + +#### Preloading an image {/*preloading-an-image*/} + +```js +import { preload } from 'react-dom'; + +function AppRoot() { + preload("/banner.png", { + as: "image", + imageSrcSet: "/banner512.png 512w, /banner1024.png 1024w", + imageSizes: "(max-width: 512px) 512px, 1024px", + }); + return ...; +} +``` + +When preloading an image, the `imageSrcSet` and `imageSizes` options help the browser [fetch the correctly sized image for the size of the screen]((https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images)). + + + + + +### Preloading in an event handler {/*preloading-in-an-event-handler*/} + +Call `preload` in an event handler before transitioning to a page or state where external resources will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { preload } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + preload("https://example.com/wizardStyles.css", {as: "style"}); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/content/reference/react-dom/preloadModule.md b/src/content/reference/react-dom/preloadModule.md new file mode 100644 index 000000000..05333f1cb --- /dev/null +++ b/src/content/reference/react-dom/preloadModule.md @@ -0,0 +1,107 @@ +--- +title: preloadModule +canary: true +--- + + + +The `preloadModule` function is currently only available in React's Canary and experimental channels. Learn more about [React's release channels here](/community/versioning-policy#all-release-channels). + + + + + +[React-based frameworks](/learn/start-a-new-react-project) frequently handle resource loading for you, so you might not have to call this API yourself. Consult your framework's documentation for details. + + + + + +`preloadModule` lets you eagerly fetch an ESM module that you expect to use. + +```js +preloadModule("https://example.com/module.js", {as: "script"}); +``` + + + + + +--- + +## Reference {/*reference*/} + +### `preloadModule(href, options)` {/*preloadmodule*/} + +To preload an ESM module, call the `preloadModule` function from `react-dom`. + +```js +import { preloadModule } from 'react-dom'; + +function AppRoot() { + preloadModule("https://example.com/module.js", {as: "script"}); + // ... +} + +``` + +[See more examples below.](#usage) + +The `preloadModule` function provides the browser with a hint that it should start downloading the given module, which can save time. + +#### Parameters {/*parameters*/} + +* `href`: a string. The URL of the module you want to download. +* `options`: an object. It contains the following properties: + * `as`: a required string. It must be `'script'`. + * `crossOrigin`: a string. The [CORS policy](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/crossorigin) to use. Its possible values are `anonymous` and `use-credentials`. + * `integrity`: a string. A cryptographic hash of the module, to [verify its authenticity](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity). + * `nonce`: a string. A cryptographic [nonce to allow the module](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/nonce) when using a strict Content Security Policy. + + +#### Returns {/*returns*/} + +`preloadModule` returns nothing. + +#### Caveats {/*caveats*/} + +* Multiple calls to `preloadModule` with the same `href` have the same effect as a single call. +* In the browser, you can call `preloadModule` in any situation: while rendering a component, in an effect, in an event handler, and so on. +* In server-side rendering or when rendering Server Components, `preloadModule` only has an effect if you call it while rendering a component or in an async context originating from rendering a component. Any other calls will be ignored. + +--- + +## Usage {/*usage*/} + +### Preloading when rendering {/*preloading-when-rendering*/} + +Call `preloadModule` when rendering a component if you know that it or its children will use a specific module. + +```js +import { preloadModule } from 'react-dom'; + +function AppRoot() { + preloadModule("https://example.com/module.js", {as: "script"}); + return ...; +} +``` + +If you want the browser to start executing the module immediately (rather than just downloading it), use [`preinitModule`](/reference/react-dom/preinitModule) instead. If you want to load a script that isn't an ESM module, use [`preload`](/reference/react-dom/preload). + +### Preloading in an event handler {/*preloading-in-an-event-handler*/} + +Call `preloadModule` in an event handler before transitioning to a page or state where the module will be needed. This gets the process started earlier than if you call it during the rendering of the new page or state. + +```js +import { preloadModule } from 'react-dom'; + +function CallToAction() { + const onClick = () => { + preloadModule("https://example.com/module.js", {as: "script"}); + startWizard(); + } + return ( + + ); +} +``` diff --git a/src/sidebarReference.json b/src/sidebarReference.json index 890e7990b..ac6713800 100644 --- a/src/sidebarReference.json +++ b/src/sidebarReference.json @@ -203,6 +203,16 @@ "title": "", "path": "/reference/react-dom/components/input" }, + { + "title": "", + "path": "/reference/react-dom/components/link", + "canary": true + }, + { + "title": "", + "path": "/reference/react-dom/components/meta", + "canary": true + }, { "title": "