Bien démarrer avec ThreeUI

ThreeUI est un catalogue de composants React créé par Meng To, publié sur threeui.com et sur npm sous le nom @designcodeio/threeui. Chaque composant embarque son propre moteur de rendu animé (Three.js, WebGL natif ou Canvas 2D, selon le composant). Pour ajouter un arrière-plan 3D animé à une section hero, il suffit donc d’importer un composant, sans avoir à construire une scène, une caméra et des matériaux.

Vous voulez une section hero qui capte l’attention dès le défilement, mais un tutoriel Three.js commence par les graphes de scène, les dispositifs d’éclairage et les boucles de rendu avant que quoi que ce soit n’apparaisse à l’écran. Ce guide explique comment installer ThreeUI, afficher un composant d’arrière-plan derrière une section hero, résoudre le problème des chemins d’assets et déterminer si le poids supplémentaire en vaut la peine sur votre page.

Qu’est-ce que ThreeUI et à qui s’adresse-t-il ?

ThreeUI fournit des sections animées prêtes à l’emploi (sections hero, arrière-plans, éléments interactifs) que vous intégrez dans une page React classique. Inutile de savoir comment fonctionne un graphe de scène : vous choisissez un composant, vous l’affichez et vous définissez ses props.

Plusieurs projets sans lien entre eux portent le nom three-ui, notamment poki-archive/three-ui et nirholas/three-ui. Ce guide porte sur le ThreeUI de Meng To, disponible sur threeui.com et dans le dépôt MengTo/threeui.

ThreeUI se décline en deux offres : Community et Pro. Les composants Community sont sous licence MIT et s’installent depuis npm. Les composants Pro ne sont pas publiés sur npm : vous téléchargez leur code source directement dans votre projet avec npx @designcodeio/threeui-cli, après vous être connecté avec un abonnement payant actif. Le projet est récent (la version Community est devenue open source en août 2026), attendez-vous donc à des évolutions de l’API.

Installer le package ThreeUI

Installez un seul package npm, puis importez sa feuille de style une fois. La page d’installation de ThreeUI détaille la configuration. Le package publié déclare comme dépendances peer react et react-dom à partir de la version 18 et jusqu’à la version 20 exclue, ainsi que three à partir de la version 0.149. À partir de npm 7, les dépendances peer manquantes sont installées automatiquement. La CLI Pro nécessite Node.js 20 ou une version ultérieure.

npm install @designcodeio/threeui

L’emplacement de l’import de la feuille de style dépend de votre framework :

// src/main.jsx (Vite)
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import "@designcodeio/threeui/style.css";
import App from "./App";

createRoot(document.getElementById("root")).render(
  <StrictMode>
    <App />
  </StrictMode>
);

Intégrer un composant

Pour afficher un composant ThreeUI, importez-le par son nom et placez-le dans votre JSX. L’exemple du README utilise AtTheHorizon, mais ce composant n’est pas exporté par la version actuelle 1.2.0 du package. Ce guide utilise donc EmeraldHorizonBackground, un arrière-plan Three.js animé qui se place derrière une section hero :

import { EmeraldHorizonBackground } from "@designcodeio/threeui";

export function Hero() {
  return <EmeraldHorizonBackground />;
}

L’import depuis la racine est l’option la plus simple. Le package propose également un sous-chemin par composant, qui charge moins de code pendant le développement :

import { EmeraldHorizonBackground } from "@designcodeio/threeui/components/EmeraldHorizonBackground";

Les props varient d’un composant à l’autre. Consultez-les sur la page de chaque composant sur threeui.com. Par exemple, Brand Orbs accepte variant, size, mode, speed et paused. Ne devinez pas les props. Pour ajouter une interaction sans dépendre d’aucune prop, utilisez l’état du composant parent :

import { useState } from "react";
import { EmeraldHorizonBackground } from "@designcodeio/threeui";

export function Hero() {
  const [show3D, setShow3D] = useState(true);

  return (
    <section>
      {show3D ? (
        <EmeraldHorizonBackground />
      ) : (
        <img src="/hero-fallback.jpg" alt="Product hero" />
      )}
      <button onClick={() => setShow3D((v) => !v)}>
        {show3D ? "Show static image" : "Show 3D"}
      </button>
    </section>
  );
}

Le piège des assets ThreeUI

Certains composants ThreeUI affichent un document HTML complet. Ils récupèrent leurs fichiers d’exécution depuis des chemins fixes à la racine de votre site, les mêmes que ceux utilisés par le site de démonstration de ThreeUI. Landscape, par exemple, demande /landscape.html par défaut. Si votre application ne sert aucun fichier à ce chemin, le composant ne fonctionne pas. Deux solutions s’offrent à vous. Copiez les fichiers nécessaires depuis node_modules/@designcodeio/threeui/lib-dist/assets/ vers votre dossier public. Ou, si le composant dispose d’une prop sourceUrl ou assetBaseUrl, faites-la pointer vers l’emplacement où vous hébergez les fichiers.

# Check the network tab for the exact paths the component requests,
# then mirror that layout under public/.
cp -R node_modules/@designcodeio/threeui/lib-dist/assets/. public/

// Only if the component's page lists this prop:
// <SomeComponent assetBaseUrl="/threeui/" />

ThreeUI face à Three.js natif

ThreeUI masque le moteur de rendu. Dans les composants basés sur Three.js, la scène, la caméra, le renderer, les matériaux et la boucle d’animation sont tous encapsulés dans le composant. D’autres composants utilisent WebGL natif ou Canvas 2D. Le prix de cette simplicité, c’est le contrôle : ThreeUI expose les variantes et les contrôles de chaque composant, et toute modification qui sort de ce cadre implique de modifier le code source du composant. Vous pouvez consulter le code source Community dans node_modules et sur GitHub. La CLI Pro copie le code source Pro dans votre projet.

Si vous prévoyez d’aller au-delà des contrôles exposés, apprenez la bibliothèque sous-jacente. L’article Building 3D animations using JavaScript and Three.js en couvre les fondamentaux.

Les performances de ThreeUI, sans détour

Chaque composant ThreeUI exécute un canvas animé en temps réel, ce qui a un coût en JavaScript, en téléchargement d’assets et en temps GPU. Ce sont les GPU mobiles qui en pâtissent le plus. Chargez les composants en différé, désactivez-les pour les visiteurs ayant activé prefers-reduced-motion et utilisez une image statique partout où l’effet 3D n’apporte rien à la page.

React.lazy attend un export par défaut : il faut donc mapper l’export nommé :

import { lazy, Suspense, useEffect, useState } from "react";

const EmeraldHorizonBackground = lazy(() =>
  import("@designcodeio/threeui").then((m) => ({ default: m.EmeraldHorizonBackground }))
);

function useReducedMotion() {
  const [reduced, setReduced] = useState(false);
  useEffect(() => {
    const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
    setReduced(mq.matches);
    const onChange = (e) => setReduced(e.matches);
    mq.addEventListener("change", onChange);
    return () => mq.removeEventListener("change", onChange);
  }, []);
  return reduced;
}

function hasWebGL() {
  const canvas = document.createElement("canvas");
  return Boolean(canvas.getContext("webgl2") || canvas.getContext("webgl"));
}

const fallback = <img src="/hero-fallback.jpg" alt="Product hero" />;

export function Hero() {
  const reduced = useReducedMotion();
  const [webgl, setWebgl] = useState(false);
  useEffect(() => setWebgl(hasWebGL()), []);

  if (reduced || !webgl) return fallback;
  return <Suspense fallback={fallback}><EmeraldHorizonBackground /></Suspense>;
}

Le composant Hero ci-dessus lit la caractéristique média prefers-reduced-motion via window.matchMedia et vérifie la disponibilité d’un contexte avec HTMLCanvasElement.getContext. Certains composants gèrent eux-mêmes la réduction des animations. Brand Orbs, par exemple, dispose des props speed et paused, et son code source vérifie prefers-reduced-motion et met l’animation en pause lorsque le composant sort du champ de vision. Consultez la page de chaque composant pour savoir ce qu’il prend en charge.

Avec Next.js, utilisez next/dynamic. L’option ssr: false ne fonctionne qu’à l’intérieur d’un Client Component, et Next.js lève une erreur si vous l’utilisez dans un Server Component. Désactiver le rendu côté serveur est un choix par défaut sûr pour du code canvas qui ne s’exécute que dans le navigateur :

"use client";
import dynamic from "next/dynamic";

const EmeraldHorizonBackground = dynamic(
  () => import("@designcodeio/threeui").then((m) => m.EmeraldHorizonBackground),
  { ssr: false, loading: () => <img src="/hero-fallback.jpg" alt="Product hero" /> }
);

export default function Hero() {
  return <EmeraldHorizonBackground />;
}

Consultez le guide de Next.js sur le lazy loading pour plus de détails. Lancez l’analyseur de bundle de votre outil de build pour mesurer ce que ThreeUI ajoute réellement à votre bundle. Les tests en laboratoire ne donnent toutefois qu’une vision partielle. Un outil de session replay comme OpenReplay vous permet d’observer de vraies visites, et donc de repérer une section hero qui reste vide ou saccade sur les téléphones les moins puissants. Si vous avez besoin de plus de contrôle que ce qu’offre un composant préconstruit, les options de plus bas niveau sont abordées dans WebGPU vs WebGL: Why the Industry Is Moving On.

Figez la version du package ThreeUI. Selon les règles de publication du README, une version Community est publiée lorsqu’un mainteneur fusionne la pull request de synchronisation relue, et la suppression d’un composant, d’une variante ou d’un contrôle public entraîne une version majeure. AtTheHorizon en est un exemple : il a été livré dans la version 0.3.0 et a disparu des versions 1.x. Lisez les notes de version avant toute mise à jour.

Conclusion

ThreeUI vous permet d’obtenir un arrière-plan 3D fonctionnel pour votre section hero avec une installation npm, un import de feuille de style et un composant. Prévoyez du temps pour servir les assets d’exécution, et gardez à l’esprit que ThreeUI sacrifie le contrôle au profit de la rapidité. Commencez par afficher un composant Community derrière une frontière de lazy loading, avec une solution de repli pour la réduction des animations. Mesurez ensuite le bundle et testez sur un téléphone milieu de gamme avant de décider de le conserver sur la page.

FAQ

Puis-je utiliser les composants ThreeUI Community dans un projet commercial ?

Oui. Le code applicatif, le code des composants et les visuels créés par ThreeUI dans l'offre Community sont sous licence MIT, qui autorise l'usage commercial à condition de conserver la mention de licence. Les polices open source incluses restent sous licence SIL Open Font License 1.1, et les fichiers d'exécution Three.js inclus restent sous licence MIT. Les composants Pro constituent un produit payant distinct : vérifiez les conditions Pro avant de les mettre en production.

Que se passe-t-il si je relance la CLI ThreeUI Pro après avoir modifié un composant téléchargé ?

La CLI ThreeUI Pro ne remplace pas les fichiers que vous avez modifiés, sauf si vous ajoutez l'option --force, par exemple npx @designcodeio/threeui-cli add cross-beam --dir ./src --force. L'option --force écrase vos modifications avec le code source téléchargé : commitez donc vos changements au préalable et réintégrez-les manuellement. Exécutez npx @designcodeio/threeui-cli --help pour afficher les autres commandes et options, notamment login et logout.

Pourquoi les composants ThreeUI Pro n'apparaissent-ils ni dans package.json ni dans npm update ?

Les composants Pro ne sont pas une dépendance npm. La CLI ThreeUI copie leur code source directement dans votre projet : ils ne figurent donc pas dans package.json, et ni npm update, ni npm outdated, ni les scanners de dépendances basés sur le lockfile ne les suivent. Traitez les fichiers Pro comme du code vendorisé : conservez-les dans votre gestionnaire de versions et téléchargez-les à nouveau avec la CLI lorsque vous souhaitez passer à une version plus récente.

Tous les composants ThreeUI nécessitent-ils WebGL ?

Non. Certains composants ThreeUI utilisent Canvas 2D au lieu de WebGL. Le preset DesignCode de Brand Orbs, par exemple, dessine son champ de points avec Canvas 2D. Une vérification WebGL appliquée systématiquement masque ces composants dans des navigateurs capables de les exécuter : n'appliquez donc une vérification getContext('webgl2') ou getContext('webgl') qu'aux composants dont la page sur threeui.com mentionne un moteur de rendu Three.js ou WebGL.