React

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 />

Contraintes

Les composants React dans Mintlify s’exécutent dans un environnement MDX isolé, avec les contraintes suivantes :

Les hooks React sont pré-injectés : useState, useEffect, useRef, useCallback, useMemo, useContext et useReducer sont disponibles sans les importer.
Les packages npm nécessitent une configuration : pour importer des packages tiers, configurez les bibliothèques tierces. Sinon, utilisez les fonctionnalités natives du navigateur ou écrivez la logique directement dans le composant.
Pas d’exports par défaut : utilisez des exports nommés (export const MyComponent = ...). Les exports par défaut (export default) ne sont pas pris en charge.
Pas d’imports entre snippets : les fichiers de snippets ne peuvent pas importer d’autres fichiers de snippets. Importez toutes les dépendances directement dans le fichier MDX parent.
Pas d’imports JSON : l’import de fichiers .json n’est pas pris en charge.
Pas de fractionnement du code : React.lazy et import() dynamique ne sont pas pris en charge. Tout le code des composants d’une page, y compris les snippets importés, est compilé dans la page et chargé avec elle.

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

Rendu côté client : La plupart des composants personnalisés s’affichent dans le navigateur après le chargement de la page, ils ne figurent donc pas dans le HTML rendu côté serveur. Cela s’applique aux composants que vous importez par leur nom depuis un snippet, comme import { ColorGenerator } from "/snippets/color-generator.jsx", et à la plupart des composants que vous définissez avec export dans un fichier MDX. Les snippets MDX que vous importez en tant que contenu, comme import MySnippet from "/snippets/my-snippet.mdx", sont rendus côté serveur. Un composant que vous définissez avec export est également rendu côté serveur lorsqu’il s’agit d’un simple modèle. Il doit uniquement placer ses props dans des éléments HTML et des composants intégrés, sans état, hooks, appels de fonction, conditions, gestionnaires d’événements ni attributs style. Chaque endroit où vous l’utilisez doit transmettre uniquement des attributs de type chaîne simples, comme <HeroCard title="Quickstart" href="/quickstart" />.
SEO : Comme les composants personnalisés ne figurent pas dans le HTML initial, les moteurs de recherche peuvent ne pas indexer complètement leur contenu.
Chargement initial : Les visiteurs peuvent voir un flash ou un décalage de mise en page pendant le rendu des composants personnalisés. Pour le contenu qui doit apparaître dans le HTML initial ou ne doit pas se décaler au chargement, utilisez plutôt des composants intégrés comme les cartes et les colonnes. La plupart des composants intégrés sont rendus côté serveur.
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 : Le code des composants ne peut pas être chargé de façon différée. Tous les composants sont chargés avec la page. Si un composant effectue des opérations gourmandes en ressources lorsqu’il est monté, comme la récupération de données ou des calculs lourds, utilisez le rendu conditionnel pour différer son montage jusqu’à une interaction de l’utilisateur.

Prise en main

Créer du contenu

Gérer votre site

Agent

Assistant

Contenu adapté aux agents

Recherche et SEO

Documenter des API

Intégrations

Référence

Composants en ligne

Contraintes

Importer des composants

Considérations

​Composants en ligne

​Contraintes

​Importer des composants

​Considérations

Composants en ligne

Contraintes

Importer des composants

Considérations