Primeiros passos com o ThreeUI

O ThreeUI é um catálogo de componentes React criado por Meng To, publicado em threeui.com e no npm como @designcodeio/threeui. Cada componente traz seu próprio renderizador animado (Three.js, WebGL puro ou Canvas 2D, dependendo do componente). Assim, para adicionar um fundo 3D animado à seção hero, basta importar um componente, sem precisar montar cena, câmera e materiais.

Você quer uma seção hero que faça o visitante parar de rolar a página, mas um tutorial de Three.js começa com grafos de cena, esquemas de iluminação e loops de renderização antes de qualquer coisa aparecer na tela. Este guia mostra como instalar o ThreeUI, renderizar um componente de fundo atrás de uma seção hero, resolver o problema dos caminhos de assets e avaliar se o peso extra compensa na sua página.

O que é o ThreeUI e para quem ele serve?

O ThreeUI oferece seções animadas prontas (heroes, fundos, elementos interativos) que você insere em uma página React comum. Não é preciso saber como funciona um grafo de cena. Basta escolher um componente, renderizá-lo e definir suas props.

Vários projetos sem relação entre si se chamam three-ui, incluindo poki-archive/three-ui e nirholas/three-ui. Este guia trata do ThreeUI de Meng To, disponível em threeui.com e no repositório MengTo/threeui.

O ThreeUI é dividido em dois níveis: Community e Pro. Os componentes Community têm licença MIT e são instalados pelo npm. Os componentes Pro não estão no npm: você baixa o código-fonte deles para o seu projeto com npx @designcodeio/threeui-cli, depois de fazer login com um plano pago ativo. O projeto é recente (a versão Community teve o código aberto em agosto de 2026), então é provável que a API mude.

Instale o pacote do ThreeUI

Instale um único pacote npm e importe a folha de estilos dele uma vez. A página de instalação do ThreeUI detalha a configuração. O pacote publicado declara como peer dependencies react e react-dom a partir da versão 18 até a 20 (sem incluí-la), além de three a partir da 0.149. O npm 7 e versões posteriores instalam automaticamente as peer dependencies ausentes. A CLI Pro exige Node.js 20 ou superior.

npm install @designcodeio/threeui

O local da importação da folha de estilos depende do 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>
);

Adicione um componente

Para renderizar um componente do ThreeUI, importe-o pelo nome e coloque-o no seu JSX. O exemplo do README usa AtTheHorizon, mas esse componente não é exportado pelo pacote atual (1.2.0). Por isso, este guia usa EmeraldHorizonBackground, um fundo animado em Three.js que fica atrás de uma seção hero:

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

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

A importação pela raiz é a opção mais simples. O pacote também oferece um subcaminho por componente, que carrega menos código durante o desenvolvimento:

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

As props variam de um componente para outro. Consulte-as na página de cada componente em threeui.com. Por exemplo, o Brand Orbs aceita variant, size, mode, speed e paused. Não tente adivinhar props. Para adicionar uma interação sem depender de nenhuma prop, use estado no componente que envolve o ThreeUI:

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

A pegadinha dos assets do ThreeUI

Alguns componentes do ThreeUI renderizam um documento HTML completo. Eles buscam seus arquivos de runtime em caminhos fixos na raiz do seu site, os mesmos usados pelo site de preview do ThreeUI. O Landscape, por exemplo, solicita /landscape.html por padrão. Se a sua aplicação não servir um arquivo nesse caminho, o componente quebra. Há duas formas de resolver isso. Copie os arquivos necessários de node_modules/@designcodeio/threeui/lib-dist/assets/ para a sua pasta pública. Ou, se o componente tiver a prop sourceUrl ou assetBaseUrl, aponte-a para o local onde você hospeda os arquivos.

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

Como o ThreeUI se compara ao Three.js puro

O ThreeUI esconde o renderizador. Nos componentes baseados em Three.js, cena, câmera, renderizador, materiais e loop de animação ficam todos dentro do componente. Outros componentes usam WebGL puro ou Canvas 2D. O preço dessa conveniência é o controle: o ThreeUI expõe as variantes e os controles de cada componente, e alterar qualquer coisa que não esteja coberta por eles significa editar o código-fonte do componente. Você pode ler o código-fonte Community em node_modules e no GitHub. A CLI Pro copia o código-fonte Pro para o seu projeto.

Se você pretende ir além dos controles expostos, aprenda a biblioteca subjacente. O artigo Building 3D animations using JavaScript and Three.js aborda os fundamentos.

Desempenho do ThreeUI, sem rodeios

Todo componente do ThreeUI executa um canvas animado em tempo real, o que custa JavaScript, download de assets e tempo de GPU. As GPUs de dispositivos móveis são as que mais sentem esse custo. Carregue os componentes de forma lazy, não os exiba para visitantes que ativaram prefers-reduced-motion e use uma imagem estática sempre que o efeito 3D não agregar nada à página.

O React.lazy espera um export default, então mapeie o export nomeado:

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

O componente Hero acima lê a media feature prefers-reduced-motion por meio de window.matchMedia e verifica a disponibilidade de um contexto com HTMLCanvasElement.getContext. Alguns componentes tratam a redução de movimento por conta própria. O Brand Orbs, por exemplo, tem as props speed e paused, e seu código-fonte verifica prefers-reduced-motion e pausa a animação quando o componente sai da área visível. Consulte a página de cada componente para saber o que ele cobre.

No Next.js, use next/dynamic. A opção ssr: false só funciona dentro de um Client Component, e o Next.js lança um erro se você a usar em um Server Component. Desativar a renderização no servidor é um padrão seguro para código de canvas que só roda no navegador:

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

Consulte o guia de lazy loading do Next.js para mais detalhes. Rode o bundle analyzer da sua ferramenta de build para ver o quanto o ThreeUI realmente acrescenta ao seu bundle. Testes de laboratório, porém, mostram apenas parte do cenário. Uma ferramenta de session replay como o OpenReplay permite assistir a visitas reais, para que você identifique uma seção hero que fica em branco ou trava em celulares mais lentos. Se você precisar de mais controle do que um componente pronto oferece, as opções de nível mais baixo são abordadas em WebGPU vs WebGL: Why the Industry Is Moving On.

Fixe a versão do pacote do ThreeUI. Segundo as regras de release do README, uma versão Community é publicada quando um mantenedor faz o merge do pull request de sincronização revisado, e a remoção de um componente, variante ou controle público gera uma nova versão major. O AtTheHorizon é um exemplo: ele foi lançado na 0.3.0 e não existe mais nas versões 1.x. Leia as release notes antes de atualizar.

Conclusão

O ThreeUI entrega um fundo 3D funcional para a seção hero com uma instalação via npm, uma importação de folha de estilos e um componente. Reserve tempo para servir os assets de runtime e lembre-se de que ele troca controle por velocidade. Comece renderizando um componente Community dentro de um limite de lazy loading, com fallback para redução de movimento. Depois, meça o bundle e teste em um celular intermediário antes de decidir se ele permanece na página.

Perguntas frequentes

Posso usar os componentes Community do ThreeUI em um projeto comercial?

Sim. O código da aplicação, o código dos componentes e as imagens criadas pelo ThreeUI na versão Community têm licença MIT, que permite uso comercial desde que você mantenha o aviso de licença. As fontes abertas incluídas continuam sob a SIL Open Font License 1.1, e os arquivos de runtime do Three.js incluídos continuam sob licença MIT. Os componentes Pro são um produto pago separado, então consulte os termos do Pro antes de colocá-los em produção.

O que acontece se eu executar a CLI do ThreeUI Pro novamente depois de editar um componente baixado?

A CLI do ThreeUI Pro não substitui arquivos que você editou, a menos que você adicione a flag --force, por exemplo: npx @designcodeio/threeui-cli add cross-beam --dir ./src --force. Usar --force substitui suas edições pelo código-fonte baixado, então faça commit das suas alterações antes e reaplique-as manualmente. Execute npx @designcodeio/threeui-cli --help para ver os outros comandos e flags, incluindo login e logout.

Por que os componentes Pro do ThreeUI não aparecem no package.json nem no npm update?

Os componentes Pro não são uma dependência npm. A CLI do ThreeUI copia o código-fonte deles diretamente para o seu projeto, então eles não aparecem no package.json, e o npm update, o npm outdated e os scanners de dependências baseados em lockfile não os rastreiam. Trate os arquivos Pro como código vendorizado: mantenha-os no controle de versão e baixe-os novamente com a CLI quando quiser uma versão mais recente.

Todo componente do ThreeUI precisa de WebGL?

Não. Alguns componentes do ThreeUI desenham com Canvas 2D em vez de WebGL. O preset DesignCode do Brand Orbs, por exemplo, desenha seu campo de pontos com Canvas 2D. Uma verificação genérica de WebGL esconde esses componentes de navegadores que conseguiriam executá-los, então aplique a verificação getContext('webgl2') ou getContext('webgl') apenas aos componentes cuja página em threeui.com descreve um renderizador Three.js ou WebGL.