Passer au contenu principal
Créez des éléments interactifs dans votre documentation à l’aide de composants React et de hooks directement dans vos fichiers MDX.

​
Composants en ligne

Déclarez des composants directement dans votre fichier MDX : 
export const Counter = () => {
  const [count, setCount] = useState(0)
  const increment = () => setCount(count + 1)
  const decrement = () => setCount(count - 1)

  return (
    <div>
      <button onClick={decrement}>-</button>
      <span>{count}</span>
      <button onClick={increment}>+</button>
    </div>
  )
}

<Counter />

​
Importer des composants

Les fichiers de composants doivent se trouver dans le dossier /snippets/. En savoir plus sur les snippets réutilisables.
Les imports imbriqués ne sont pas pris en charge. Importez tous les composants référencés directement dans le fichier MDX parent.
Créez un fichier de composant dans snippets/ :
/snippets/color-generator.jsx
export const ColorGenerator = () => {
  const [hue, setHue] = useState(180)
  const [saturation, setSaturation] = useState(50)
  const [lightness, setLightness] = useState(50)
  const [colors, setColors] = useState([])

  useEffect(() => {
    const newColors = []
    for (let i = 0; i < 5; i++) {
      const l = Math.max(10, Math.min(90, lightness - 20 + i * 10))
      newColors.push(`hsl(${hue}, ${saturation}%, ${l}%)`)
    }
    setColors(newColors)
  }, [hue, saturation, lightness])

  const copyToClipboard = (color) => {
    navigator.clipboard
      .writeText(color)
      .then(() => {
        console.log(`Copied ${color} to clipboard!`)
      })
      .catch((err) => {
        console.error("Failed to copy: ", err)
      })
  }

  return (
    <div className="p-4 border dark:border-zinc-950/80 rounded-xl not-prose">
      <div className="space-y-4">
        <div className="space-y-2">
          <label className="block text-sm text-zinc-950/70 dark:text-white/70">
            Hue: {hue}°
            <input
              type="range"
              min="0"
              max="360"
              value={hue}
              onChange={(e) => setHue(Number.parseInt(e.target.value))}
              className="w-full h-2 bg-zinc-950/20 rounded-lg appearance-none cursor-pointer dark:bg-white/20 mt-1"
              style={{
                background: `linear-gradient(to right, 
                  hsl(0, ${saturation}%, ${lightness}%), 
                  hsl(60, ${saturation}%, ${lightness}%), 
                  hsl(120, ${saturation}%, ${lightness}%), 
                  hsl(180, ${saturation}%, ${lightness}%), 
                  hsl(240, ${saturation}%, ${lightness}%), 
                  hsl(300, ${saturation}%, ${lightness}%), 
                  hsl(360, ${saturation}%, ${lightness}%))`,
              }}
            />
          </label>

          <label className="block text-sm text-zinc-950/70 dark:text-white/70">
            Saturation: {saturation}%
            <input
              type="range"
              min="0"
              max="100"
              value={saturation}
              onChange={(e) => setSaturation(Number.parseInt(e.target.value))}
              className="w-full h-2 bg-zinc-950/20 rounded-lg appearance-none cursor-pointer dark:bg-white/20 mt-1"
              style={{
                background: `linear-gradient(to right, 
                  hsl(${hue}, 0%, ${lightness}%), 
                  hsl(${hue}, 50%, ${lightness}%), 
                  hsl(${hue}, 100%, ${lightness}%))`,
              }}
            />
          </label>

          <label className="block text-sm text-zinc-950/70 dark:text-white/70">
            Lightness: {lightness}%
            <input
              type="range"
              min="0"
              max="100"
              value={lightness}
              onChange={(e) => setLightness(Number.parseInt(e.target.value))}
              className="w-full h-2 bg-zinc-950/20 rounded-lg appearance-none cursor-pointer dark:bg-white/20 mt-1"
              style={{
                background: `linear-gradient(to right, 
                  hsl(${hue}, ${saturation}%, 0%), 
                  hsl(${hue}, ${saturation}%, 50%), 
                  hsl(${hue}, ${saturation}%, 100%))`,
              }}
            />
          </label>
        </div>

        <div className="flex space-x-1">
          {colors.map((color, idx) => (
            <div
              key={idx}
              className="h-16 rounded flex-1 cursor-pointer transition-transform hover:scale-105"
              style={{ backgroundColor: color }}
              title={`Click to copy: ${color}`}
              onClick={() => copyToClipboard(color)}
            />
          ))}
        </div>

        <div className="text-sm font-mono text-zinc-950/70 dark:text-white/70">
          <p>
            Base color: hsl({hue}, {saturation}%, {lightness}%)
          </p>
        </div>
      </div>
    </div>
  )
}
Puis importez-le et utilisez-le : 
import { ColorGenerator } from "/snippets/color-generator.jsx"

<ColorGenerator />

​
Considérations

  • SEO : Les moteurs de recherche peuvent ne pas indexer complètement le contenu dynamique rendu côté client.
  • Chargement initial : Les visiteurs peuvent voir un flash avant que les composants ne s’affichent.
  • Accessibilité : Assurez-vous que les lecteurs d’écran annoncent les changements de contenu dynamique.
  • Optimisez les tableaux de dépendances : N’incluez que les dépendances nécessaires dans useEffect.
  • Mémoïsez les opérations coûteuses : Utilisez useMemo ou useCallback lorsque cela est pertinent.
  • Réduisez les re-rendus : Décomposez les grands composants en composants plus petits.
  • Lazy loading : Différez le rendu des composants complexes jusqu’à ce qu’ils soient nécessaires afin d’améliorer le temps de chargement initial de la page. Comme le bac à sable MDX ne prend en charge ni React.lazy ni import() dynamique, conditionnez plutôt les composants lourds à une interaction de l’utilisateur ou à leur visibilité. Voir Différer le rendu des composants lourds.

​
Différer le rendu des composants lourds

React.lazy, Suspense et import() dynamique ne sont pas disponibles dans le bac à sable MDX. Pour obtenir le même bénéfice, affichez d’abord un espace réservé léger et ne montez le composant coûteux qu’après l’action explicite du lecteur. Cela garde le chargement initial de la page rapide tout en permettant aux lecteurs d’interagir avec le composant complet. L’exemple ci-dessous garde le ColorGenerator de la section précédente non monté jusqu’à ce que le lecteur clique sur Load color generator : 
import { ColorGenerator } from "/snippets/color-generator.jsx"

export const LazyColorGenerator = () => {
  const [show, setShow] = useState(false)

  if (!show) {
    return (
      <button onClick={() => setShow(true)}>
        Load color generator
      </button>
    )
  }

  return <ColorGenerator />
}

<LazyColorGenerator />
Pour différer le rendu jusqu’à ce que le composant apparaisse dans la zone visible, remplacez le bouton par un IntersectionObserver configuré dans un useEffect. Le schéma est identique : maintenez show à false jusqu’au déclenchement, puis renvoyez le composant lourd.

Sujets connexes

Extraits réutilisablesCréer des mises en page personnaliséesMise en forme du code