Erste Schritte mit ThreeUI

ThreeUI ist ein Katalog von React-Komponenten von Meng To, veröffentlicht unter threeui.com und auf npm als @designcodeio/threeui. Jede Komponente bringt ihren eigenen animierten Renderer mit (je nach Komponente Three.js, reines WebGL oder Canvas 2D). Einen animierten 3D-Hero-Hintergrund binden Sie daher per Import einer Komponente ein, statt selbst Szene, Kamera und Materialien aufzubauen.

Sie wünschen sich einen Hero-Bereich, der Besucher beim Scrollen innehalten lässt. Ein Three.js-Tutorial beginnt jedoch mit Szenengraphen, Beleuchtungs-Setups und Render-Loops, bevor überhaupt etwas auf dem Bildschirm erscheint. Dieser Leitfaden zeigt, wie Sie ThreeUI installieren, eine Hintergrundkomponente hinter einem Hero-Bereich rendern und das Problem mit den Asset-Pfaden lösen. Außerdem hilft er Ihnen bei der Entscheidung, ob sich das zusätzliche Gewicht auf Ihrer Seite lohnt.

Was ist ThreeUI und für wen eignet es sich?

ThreeUI liefert fertige animierte Abschnitte (Heroes, Hintergründe, interaktive Elemente), die Sie in eine gewöhnliche React-Seite einfügen. Sie müssen nicht wissen, wie ein Szenengraph funktioniert. Sie wählen eine Komponente aus, rendern sie und setzen ihre Props.

Es gibt mehrere voneinander unabhängige Projekte namens three-ui, darunter poki-archive/three-ui und nirholas/three-ui. Dieser Leitfaden bezieht sich auf Meng Tos ThreeUI von threeui.com und das Repository MengTo/threeui.

ThreeUI gibt es in zwei Stufen: Community und Pro. Community-Komponenten stehen unter der MIT-Lizenz und werden über npm installiert. Pro-Komponenten sind nicht auf npm verfügbar: Sie laden sie nach der Anmeldung mit einem aktiven kostenpflichtigen Plan per npx @designcodeio/threeui-cli als Quellcode in Ihr Projekt. Das Projekt ist noch jung (die Community-Variante wurde im August 2026 als Open Source veröffentlicht), daher ist mit Änderungen an der API zu rechnen.

Das ThreeUI-Paket installieren

Installieren Sie ein einzelnes npm-Paket und importieren Sie anschließend einmalig dessen Stylesheet. Die ThreeUI-Installationsseite führt Schritt für Schritt durch die Einrichtung. Das veröffentlichte Paket führt react und react-dom ab Version 18 bis ausschließlich 20 sowie three ab 0.149 als Peer Dependencies. Ab npm 7 werden fehlende Peers automatisch installiert. Die Pro-CLI benötigt Node.js 20 oder neuer.

npm install @designcodeio/threeui

Wo der Stylesheet-Import platziert wird, hängt von Ihrem Framework ab:

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

Eine Komponente einbinden

Um eine ThreeUI-Komponente zu rendern, importieren Sie sie über ihren Namen und platzieren sie in Ihrem JSX. Das Beispiel in der README verwendet AtTheHorizon. Diese Komponente wird vom aktuellen Paket in Version 1.2.0 jedoch nicht exportiert, daher nutzt dieser Leitfaden EmeraldHorizonBackground, einen animierten Three.js-Hintergrund, der hinter einem Hero-Bereich liegt:

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

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

Der Import aus dem Paket-Root ist die einfachste Variante. Das Paket bietet zusätzlich einen Subpath pro Komponente, der während der Entwicklung weniger Code einbindet:

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

Die Props unterscheiden sich von Komponente zu Komponente. Schlagen Sie sie auf der jeweiligen Seite der Komponente auf threeui.com nach. Brand Orbs akzeptiert beispielsweise variant, size, mode, speed und paused. Raten Sie Props nicht. Wenn Sie eine Interaktion ergänzen möchten, ohne auf bestimmte Props angewiesen zu sein, verwenden Sie State in der umgebenden Komponente:

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>
  );
}

Der Asset-Stolperstein bei ThreeUI

Einige ThreeUI-Komponenten rendern ein vollständiges HTML-Dokument. Sie laden ihre Laufzeitdateien von festen Pfaden im Root Ihrer Website, also von denselben Pfaden, die auch die ThreeUI-Vorschauseite verwendet. Landscape fordert beispielsweise standardmäßig /landscape.html an. Liefert Ihre App unter diesem Pfad keine Datei aus, funktioniert die Komponente nicht. Dafür gibt es zwei Lösungen: Kopieren Sie die benötigten Dateien aus node_modules/@designcodeio/threeui/lib-dist/assets/ in Ihren Public-Ordner. Oder, falls die Komponente eine sourceUrl- oder assetBaseUrl-Prop besitzt, verweisen Sie damit auf den Ort, an dem Sie die Dateien hosten.

# 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 im Vergleich zu reinem Three.js

ThreeUI kapselt den Renderer. Bei den auf Three.js basierenden Komponenten befinden sich Szene, Kamera, Renderer, Materialien und Animations-Loop vollständig innerhalb der Komponente. Andere Komponenten verwenden reines WebGL oder Canvas 2D. Der Preis für diesen Komfort ist Kontrolle: ThreeUI stellt für jede Komponente bestimmte Varianten und Steuerelemente bereit, und alles, was darüber hinausgeht, erfordert Änderungen am Quellcode der Komponente. Den Community-Quellcode können Sie in node_modules und auf GitHub einsehen. Die Pro-CLI kopiert den Pro-Quellcode direkt in Ihr Projekt.

Wenn Sie absehen können, dass Sie über die bereitgestellten Steuerelemente hinausgehen werden, sollten Sie sich mit der zugrunde liegenden Bibliothek vertraut machen. Building 3D animations using JavaScript and Three.js behandelt die Grundlagen.

ThreeUI und Performance: eine ehrliche Einschätzung

Jede ThreeUI-Komponente betreibt ein animiertes Live-Canvas. Das kostet JavaScript, Asset-Downloads und GPU-Zeit. Am stärksten spüren das mobile GPUs. Laden Sie Komponenten per Lazy Loading, lassen Sie sie für Besucher mit gesetztem prefers-reduced-motion weg und verwenden Sie überall dort ein statisches Bild, wo der 3D-Effekt der Seite keinen Mehrwert bringt.

React.lazy erwartet einen Default-Export, daher müssen Sie den benannten Export entsprechend abbilden:

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>;
}

Die obige Hero-Komponente liest das Media-Feature prefers-reduced-motion über window.matchMedia aus und prüft mit HTMLCanvasElement.getContext, ob ein Kontext verfügbar ist. Einige Komponenten berücksichtigen reduzierte Bewegung bereits selbst. Brand Orbs besitzt beispielsweise die Props speed und paused, und ihr Quellcode prüft prefers-reduced-motion und pausiert die Animation, sobald die Komponente nicht mehr im sichtbaren Bereich liegt. Prüfen Sie auf der Seite der jeweiligen Komponente, was sie abdeckt.

In Next.js verwenden Sie next/dynamic. Die Option ssr: false funktioniert nur innerhalb einer Client Component; in einer Server Component wirft Next.js einen Fehler. Serverseitiges Rendering zu deaktivieren ist ein sicherer Standard für Canvas-Code, der ausschließlich im Browser läuft:

"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 />;
}

Details finden Sie im Lazy-Loading-Leitfaden von Next.js. Führen Sie den Bundle Analyzer Ihres Build-Tools aus, um zu sehen, was ThreeUI tatsächlich zu Ihrem Bundle beiträgt. Labortests zeigen allerdings nur einen Teil des Gesamtbilds. Mit einem Session-Replay-Tool wie OpenReplay können Sie echte Besuche nachverfolgen und so einen Hero-Bereich erkennen, der auf langsameren Smartphones leer bleibt oder ruckelt. Wenn Sie mehr Kontrolle benötigen, als eine vorgefertigte Komponente bietet, finden Sie die Low-Level-Optionen in WebGPU vs WebGL: Why the Industry Is Moving On.

Pinnen Sie die Version des ThreeUI-Pakets. Gemäß den Release-Regeln in der README wird ein Community-Release veröffentlicht, sobald ein Maintainer den geprüften Sync-Pull-Request mergt. Das Entfernen einer öffentlichen Komponente, Variante oder eines Steuerelements führt zu einer neuen Major-Version. AtTheHorizon ist ein Beispiel dafür: Die Komponente wurde mit 0.3.0 ausgeliefert und ist in den 1.x-Releases nicht mehr enthalten. Lesen Sie die Release Notes, bevor Sie ein Upgrade durchführen.

Fazit

Mit ThreeUI erhalten Sie einen funktionierenden 3D-Hero-Hintergrund mit einer npm-Installation, einem Stylesheet-Import und einer Komponente. Planen Sie Zeit für die Bereitstellung der Laufzeit-Assets ein und behalten Sie im Hinterkopf, dass ThreeUI Kontrolle gegen Geschwindigkeit eintauscht. Rendern Sie zunächst eine Community-Komponente hinter einer Lazy-Loading-Grenze mit einem Fallback für reduzierte Bewegung. Messen Sie anschließend das Bundle und testen Sie auf einem Mittelklasse-Smartphone, bevor Sie entscheiden, ob die Komponente auf der Seite bleibt.

FAQs

Darf ich ThreeUI-Community-Komponenten in einem kommerziellen Projekt verwenden?

Ja. Anwendungscode, Komponentencode und von ThreeUI erstellte Grafiken der Community-Variante stehen unter der MIT-Lizenz, die eine kommerzielle Nutzung erlaubt, sofern Sie den Lizenzhinweis beibehalten. Mitgelieferte freie Schriftarten unterliegen weiterhin der SIL Open Font License 1.1, und mitgelieferte Three.js-Laufzeitdateien stehen weiterhin unter der MIT-Lizenz. Pro-Komponenten sind ein separates kostenpflichtiges Produkt. Prüfen Sie daher die Pro-Bedingungen, bevor Sie sie ausliefern.

Was passiert, wenn ich die ThreeUI-Pro-CLI erneut ausführe, nachdem ich eine heruntergeladene Komponente bearbeitet habe?

Die ThreeUI-Pro-CLI überschreibt keine Dateien, die Sie bearbeitet haben, es sei denn, Sie setzen das Flag --force, zum Beispiel npx @designcodeio/threeui-cli add cross-beam --dir ./src --force. Mit --force werden Ihre Änderungen durch den heruntergeladenen Quellcode ersetzt. Committen Sie Ihre Änderungen daher vorher und führen Sie sie anschließend manuell wieder zusammen. Mit npx @designcodeio/threeui-cli --help sehen Sie die weiteren Befehle und Flags, darunter login und logout.

Warum erscheinen ThreeUI-Pro-Komponenten nicht in package.json oder bei npm update?

Pro-Komponenten sind keine npm-Abhängigkeit. Die ThreeUI-CLI kopiert ihren Quellcode direkt in Ihr Projekt. Daher sind sie nicht in package.json aufgeführt, und npm update, npm outdated sowie lockfile-basierte Dependency-Scanner erfassen sie nicht. Behandeln Sie Pro-Dateien als Vendored Code: Verwalten Sie sie in der Versionskontrolle und laden Sie sie mit der CLI erneut herunter, wenn Sie eine neuere Version benötigen.

Benötigt jede ThreeUI-Komponente WebGL?

Nein. Einige ThreeUI-Komponenten zeichnen mit Canvas 2D statt mit WebGL. Das DesignCode-Preset von Brand Orbs zeichnet sein Punktfeld beispielsweise mit Canvas 2D. Eine pauschale WebGL-Prüfung blendet diese Komponenten in Browsern aus, die sie eigentlich ausführen könnten. Wenden Sie eine Prüfung mit getContext('webgl2') oder getContext('webgl') daher nur auf Komponenten an, deren Seite auf threeui.com einen Three.js- oder WebGL-Renderer beschreibt.