La prop children en React : composants enveloppes et slots

Dans React, children est la prop qui contient tout ce que vous écrivez entre les balises ouvrante et fermante d'un composant. Un composant qui affiche {children} quelque part dans son résultat devient une enveloppe : il fournit le cadre, et l'appelant fournit le contenu.

function Card({ title, children }) {
    return (
        <section style={{ border: '1px solid #ddd', borderRadius: 8, padding: 16, marginBottom: 12 }}>
            <h3 style={{ marginTop: 0 }}>{title}</h3>
            {children}
        </section>
    );
}

export default function App() {
    return (
        <div>
            <Card title="Profile">
                <p>Ada Lovelace</p>
                <p>Mathematician</p>
            </Card>
            <Card title="Settings">
                <label>
                    <input type="checkbox" /> Email me updates
                </label>
            </Card>
        </div>
    );
}

Les deux cartes partagent la même bordure, le même padding et le même style de titre, mais chacune contient un contenu totalement différent. Ajoutez une troisième <Card title="Help"> avec un lien à l'intérieur et elle reçoit le même cadre gratuitement.

Comment children arrive au composant

Le JSX transforme le contenu imbriqué en prop. Ces deux lignes produisent le même élément :

<Card title="Profile"><p>Ada</p></Card>

<Card title="Profile" children={<p>Ada</p>} />

children est donc une prop ordinaire, transmise d'une façon particulière. Vous la déstructurez comme n'importe quelle autre (function Card({ children })) ou la lisez via props.children. La page sur les props traite des props en général.

Ce qui arrive dans children dépend de ce que vous avez écrit entre les balises. Un seul enfant arrive tel quel. Plusieurs enfants arrivent sous forme de tableau. Du texte arrive sous forme de chaîne, et l'absence de contenu arrive comme undefined.

function Inspect({ label, children }) {
    const kind = Array.isArray(children) ? 'array of ' + children.length : typeof children;
    console.log(label + ':', kind);
    return <div>{children}</div>;
}

export default function App() {
    return (
        <div>
            <Inspect label="one element">
                <b>Bold</b>
            </Inspect>
            <Inspect label="two elements">
                <b>Bold</b>
                <i>Italic</i>
            </Inspect>
            <Inspect label="text">Just text</Inspect>
            <Inspect label="empty" />
        </div>
    );
}

La console affiche object, array of 2, string et undefined. Vous avez rarement à vous en soucier : afficher {children} gère tous ces cas, et null, undefined, true et false n'affichent rien. La forme ne compte que si vous essayez d'inspecter ou de modifier children, ce contre quoi la dernière section met en garde.

Composants de mise en page

L'usage le plus courant de children est un composant de mise en page : une structure de page, une mise en page avec barre latérale, une colonne centrée. Le composant gère la structure et les espacements, et chaque page qui l'utilise passe son propre contenu.

function PageLayout({ children }) {
    return (
        <div className="page">
            <Header />
            <main className="page-content">{children}</main>
            <Footer />
        </div>
    );
}

function AboutPage() {
    return (
        <PageLayout>
            <h1>About us</h1>
            <p>We teach people to code.</p>
        </PageLayout>
    );
}

PageLayout ne sait pas et n'a pas besoin de savoir ce que contient une page « à propos ». C'est tout l'intérêt de cette séparation : modifiez l'en-tête une fois et chaque page enveloppée dans la mise en page en profite.

Plusieurs emplacements avec des props nommées

children est un seul emplacement. Quand un composant a besoin de contenu à plusieurs endroits, passez les morceaux supplémentaires sous forme de props nommées. N'importe quelle prop peut contenir du JSX, donc une modale peut prendre un title, un footer et son corps dans children.

import { useState } from 'react';

function Modal({ title, footer, children }) {
    return (
        <div style={{ border: '1px solid #ccc', borderRadius: 8, maxWidth: 360 }}>
            <header style={{ padding: 12, borderBottom: '1px solid #eee', fontWeight: 600 }}>
                {title}
            </header>
            <div style={{ padding: 12 }}>{children}</div>
            <footer style={{ padding: 12, borderTop: '1px solid #eee', display: 'flex', gap: 8 }}>
                {footer}
            </footer>
        </div>
    );
}

export default function App() {
    const [open, setOpen] = useState(true);

    if (!open) {
        return <button onClick={() => setOpen(true)}>Open the dialog again</button>;
    }

    return (
        <Modal
            title="Delete this file?"
            footer={
                <>
                    <button onClick={() => setOpen(false)}>Cancel</button>
                    <button onClick={() => console.log('Deleted')}>Delete</button>
                </>
            }
        >
            <p>notes.txt will be removed. This cannot be undone.</p>
        </Modal>
    );
}

La structure de la modale contrôle les bordures, le padding et l'ordre des trois zones, et l'appelant remplit chacune d'elles. D'autres frameworks appellent cela des slots ; dans React, ce sont simplement des props. Le <>...</> autour des deux boutons est un fragment, qui les regroupe sans ajouter d'élément. Une vraie boîte de dialogue serait aussi rendue dans document.body avec un portail pour s'afficher au-dessus de la page.

Déplacez le <p> dans la prop title et le texte du corps apparaît dans l'en-tête : le composant décide où va chaque prop, l'appelant décide seulement de ce qu'elle contient.

children comme fonction

Parfois, l'enveloppe possède un état et c'est l'appelant qui doit décider comment le dessiner. Au lieu d'un élément, l'appelant passe une fonction dans children, et l'enveloppe l'appelle avec les valeurs. Ce pattern s'appelle une render prop.

import { useState } from 'react';

function Toggle({ children }) {
    const [on, setOn] = useState(false);
    return children(on, () => setOn(!on));
}

export default function App() {
    return (
        <div>
            <Toggle>
                {(on, toggle) => (
                    <button onClick={toggle}>{on ? 'Light is on' : 'Light is off'}</button>
                )}
            </Toggle>
            <Toggle>
                {(on, toggle) => (
                    <label style={{ display: 'block', marginTop: 8 }}>
                        <input type="checkbox" checked={on} onChange={toggle} />
                        {on ? ' Subscribed' : ' Not subscribed'}
                    </label>
                )}
            </Toggle>
        </div>
    );
}

Un Toggle dessine un bouton et l'autre une case à cocher, à partir de la même logique. Les render props étaient le principal moyen de partager une logique avec état avant les hooks. Aujourd'hui, un hook personnalisé comme useToggle() se lit généralement mieux, mais vous verrez encore des render props dans des bibliothèques de listes, de formulaires et d'animation.

L'API Children et cloneElement

React exporte un objet Children avec des utilitaires pour parcourir children : Children.map, Children.forEach, Children.count, Children.toArray et Children.only. Avec cloneElement, qui copie un élément avec de nouvelles props, ils permettent à un parent d'inspecter et de modifier ce qu'il a reçu. L'équipe React les classe parmi les API legacy : ils fonctionnent encore, mais le nouveau code devrait les éviter.

La raison est qu'ils ne voient que les éléments écrits directement entre les balises. Ils ne voient pas ce que ces éléments affichent.

import { Children, cloneElement } from 'react';

function NumberedList({ children }) {
    console.log('Children.count =', Children.count(children));
    return (
        <ol>
            {Children.map(children, (child, i) =>
                cloneElement(child, { style: { color: i % 2 ? 'gray' : 'black' } })
            )}
        </ol>
    );
}

function TwoMore() {
    return (
        <>
            <li>Third</li>
            <li>Fourth</li>
        </>
    );
}

export default function App() {
    return (
        <NumberedList>
            <li>First</li>
            <li>Second</li>
            <TwoMore />
        </NumberedList>
    );
}

La liste affiche quatre éléments, mais la console indique Children.count = 3, car TwoMore est un seul enfant, peu importe combien d'éléments il affiche. cloneElement transmet aussi la prop style à TwoMore, qui l'ignore, donc les troisième et quatrième éléments ne sont pas rayés. Quiconque refactorise quelques éléments <li> en un composant casse le parent sans y toucher.

La solution est d'arrêter de fouiller dans children et de passer des données à la place :

function NumberedList({ items }) {
    return (
        <ol>
            {items.map((item, i) => (
                <li key={item.id} style={{ color: i % 2 ? 'gray' : 'black' }}>
                    {item.label}
                </li>
            ))}
        </ol>
    );
}

Maintenant, la liste gère l'affichage de chaque ligne, et rien ne dépend de la façon dont l'appelant a écrit son JSX. Quand un parent doit partager des valeurs avec des enfants profondément imbriqués (un onglet sélectionné, un thème), utilisez le contexte plutôt que de cloner des props sur eux.

Typer children en TypeScript

En TypeScript, typez children comme React.ReactNode. Il couvre tout ce que React peut afficher : éléments, chaînes, nombres, tableaux de ces valeurs, null, undefined et booléens.

import type { ReactNode } from 'react';

type CardProps = {
    title: string;
    children: ReactNode;
};

function Card({ title, children }: CardProps) {
    return (
        <section>
            <h3>{title}</h3>
            {children}
        </section>
    );
}

Pour une render prop, typez-la comme la fonction qu'elle est : children: (on: boolean, toggle: () => void) => ReactNode. Rendez children facultative (children?: ReactNode) quand le composant a aussi un sens vide.

Erreurs courantes

Oublier d'afficher children. Si un composant accepte des children mais ne place jamais {children} dans son résultat, le contenu disparaît sans bruit. Rien ne vous avertit.

Appeler children comme une fonction alors qu'elle n'en est pas une. children() ne fonctionne que si l'appelant a passé une fonction. Si un composant attend une render prop, indiquez-le dans son nom ou sa documentation, ou acceptez une prop nommée comme render pour que l'intention soit claire.

Modifier children. Les éléments sont en lecture seule. React les gèle en développement, donc affecter une valeur à children.props lève une erreur. Construisez plutôt un nouveau résultat.