Blog

O que é HeroUI? Tutorial HeroUI para Iniciantes

Mark Ponomarev

Mark Ponomarev

12 junho 2025

O que é HeroUI? Tutorial HeroUI para Iniciantes
💡
Quer uma ótima ferramenta de Teste de API que gera documentação de API linda?

Quer uma plataforma integrada, Tudo-em-Um, para sua Equipe de Desenvolvimento trabalhar junta com máxima produtividade?

Apidog entrega todas as suas demandas e substitui o Postman por um preço muito mais acessível!
button

Para desenvolvedores frontend, a demanda por interfaces de usuário esteticamente agradáveis, de alto desempenho e altamente personalizáveis nunca foi tão grande. Desenvolvedores estão constantemente procurando ferramentas que possam acelerar seu fluxo de trabalho sem sacrificar qualidade ou controle criativo. Embora bibliotecas de componentes de UI monolíticas tenham servido bem à comunidade por anos, um novo paradigma está emergindo — um que prioriza a posse do código pelo desenvolvedor, modularidade e integração perfeita com frameworks modernos. É dentro deste novo paradigma que o HeroUI encontra seu nicho.

HeroUI não é apenas mais uma biblioteca de componentes; é uma coleção meticulosamente elaborada de componentes de UI reutilizáveis projetados para serem integrados diretamente em seus projetos. Ele defende uma filosofia que dá aos desenvolvedores o controle final sobre sua base de código. Em vez de importar componentes opacos de um módulo node, você usa a Interface de Linha de Comando (CLI) do HeroUI para adicionar o código-fonte real dos componentes que você precisa em seu projeto. Esta evolução de "copiar e colar" significa que cada botão, card e caixa de diálogo se torna parte de sua própria aplicação, pronto para ser ajustado, reestilizado e adaptado às suas necessidades específicas.

Construído sobre os ombros de gigantes como React, Tailwind CSS e Next.js, o HeroUI fornece os blocos de construção para criar interfaces de usuário bonitas, acessíveis e responsivas. Ele é projetado para o desenvolvedor moderno que valoriza tanto a velocidade quanto a especificidade, oferecendo um ponto de partida robusto que não o prende a um sistema de design rígido. Este artigo servirá como um guia abrangente para entender os princípios centrais do HeroUI, instalá-lo em seu projeto, personalizar sua aparência e aproveitar sua poderosa CLI para construir a próxima geração de aplicações web.

Parte 1: Desconstruindo o HeroUI - Filosofia e Recursos Centrais

Antes de mergulhar nos detalhes técnicos de instalação e uso, é crucial entender o "porquê" por trás do HeroUI. Quais problemas ele resolve e o que o torna uma escolha atraente em um campo lotado de ferramentas de UI?

A Filosofia: Propriedade e Personalização Sem Compromisso

A diferença fundamental entre o HeroUI e as bibliotecas de UI tradicionais como Material-UI ou Ant Design reside no conceito de propriedade. Ao instalar uma biblioteca tradicional, você está adicionando uma dependência ao seu package.json. Sua aplicação então importa componentes pré-compilados deste pacote. Embora isso seja conveniente, vem com várias desvantagens:

  1. Personalização Limitada: Substituir estilos pode ser complexo, muitas vezes exigindo que você lute contra os estilos padrão da biblioteca com tags !important ou configurações complicadas de provedores de tema.
  2. Componentes Caixa Preta: A lógica interna dos componentes está oculta na pasta node_modules. Depurar comportamento inesperado ou entender o funcionamento interno se torna significativamente mais difícil.
  3. Inchaço no Tamanho do Bundle: Você frequentemente importa a biblioteca inteira, ou pelo menos uma parte significativa dela, mesmo que use apenas um punhado de componentes, potencialmente aumentando o tamanho final do bundle da sua aplicação.
  4. Inferno de Dependências: Você está sujeito ao ciclo de atualização da biblioteca e suas dependências. Uma mudança disruptiva na biblioteca pode forçar uma grande refatoração em sua aplicação.

O HeroUI contorna esses problemas completamente. Ao fazer com que a CLI coloque o código-fonte do componente diretamente no diretório do seu projeto (por exemplo, /components/ui), ele o capacita de várias maneiras:

Essa filosofia é direcionada a desenvolvedores e equipes que desejam construir um sistema de design único para seu produto sem começar do zero. Ele fornece os primitivos fundamentais, sem estilo (ou levemente estilizados), e você fornece a identidade da marca.

Recursos Chave em Destaque

HeroUI é mais do que apenas seu método de instalação. Ele vem repleto de recursos projetados para um fluxo de trabalho de desenvolvimento moderno.

Para Quem é o HeroUI?

HeroUI é uma escolha ideal para um tipo específico de desenvolvedor e projeto:

Pode ser menos adequado para iniciantes absolutos que preferem uma solução mais "pronta para uso", com tudo incluído, onde a configuração mínima é necessária. O poder do HeroUI reside em sua configurabilidade, que exige uma compreensão fundamental do Tailwind CSS e do ambiente de desenvolvimento frontend moderno.

Parte 2: Começando - Um Guia Detalhado de Instalação e Configuração

Agora que entendemos a filosofia, vamos colocar a mão na massa. Esta seção fornece um guia meticuloso, passo a passo, para integrar o HeroUI em um projeto novo ou existente. O método recomendado e mais eficiente é usar a CLI oficial do HeroUI.

Pré-requisitos

Antes de começar, certifique-se de que seu ambiente de desenvolvimento atende aos seguintes requisitos:

npx create-next-app@latest my-heroui-app

Durante a configuração do Next.js, é recomendado escolher TypeScript e Tailwind CSS, pois estes são fundamentais para o ecossistema HeroUI.

O Comando init da CLI do HeroUI: Seu Ponto de Partida

O comando init é o ponto de entrada mágico no mundo do HeroUI. Ele inspeciona inteligentemente seu projeto, faz uma série de perguntas e então configura automaticamente tudo o que você precisa.

Navegue até o diretório do seu projeto:Bash

cd my-heroui-app

Agora, execute o comando de inicialização:Bash

npx heroui-cli@latest init

A CLI agora o guiará pelo processo de configuração. Vamos detalhar cada pergunta que ela faz e o que suas escolhas significam.

1. "Qual estilo você gostaria de usar?"

2. "Qual cor você gostaria de usar como cor base?"

3. "Onde está seu arquivo CSS global?"

4. "Você quer usar variáveis CSS para cores?"

5. "Onde está seu arquivo tailwind.config.js?"

6. "Configurar alias de importação para componentes:"

7. "Configurar alias de importação para utils:"

8. "Você está usando React Server Components?"

Depois de responder a todas as perguntas, a CLI realizará sua mágica. Ela irá:

Seu projeto agora está totalmente configurado e pronto para o HeroUI.

Anatomia das Mudanças

Vamos examinar mais de perto os principais arquivos que a CLI modificou ou criou.

components.json

Este arquivo é o manifesto para o HeroUI dentro do seu projeto. Ele armazena as escolhas que você fez durante o processo init e informa à CLI como seu projeto está configurado.JSON

{
  "style": "default",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "tailwind.config.js",
    "css": "app/globals.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "utils": "@/lib/utils",
    "components": "@/components"
  }
}

Você raramente precisará editar este arquivo manualmente, mas é útil entender seu propósito. É o cérebro por trás das operações da CLI.

tailwind.config.js

Sua configuração do Tailwind será estendida para se parecer com algo assim. As adições principais são as extensões theme e o plugin tailwindcss-animate.JavaScript

/** @type {import('tailwindcss').Config} */
module.exports = {
  darkMode: ["class"],
  content: [
    './pages/**/*.{ts,tsx}',
    './components/**/*.{ts,tsx}',
    './app/**/*.{ts,tsx}',
    './src/**/*.{ts,tsx}',
  ],
  theme: {
    container: {
      center: true,
      padding: "2rem",
      screens: {
        "2xl": "1400px",
      },
    },
    extend: {
      colors: {
        border: "hsl(var(--border))",
        input: "hsl(var(--input))",
        // ... e muitas outras definições de cor ligadas a variáveis CSS
        primary: {
          DEFAULT: "hsl(var(--primary))",
          foreground: "hsl(var(--primary-foreground))",
        },
        // ...
      },
      borderRadius: {
        lg: "var(--radius)",
        md: "calc(var(--radius) - 2px)",
        sm: "calc(var(--radius) - 4px)",
      },
      keyframes: {
        // ... keyframes para animações
      },
      animation: {
        // ... utilitários de animação
      },
    },
  },
  plugins: [require("tailwindcss-animate")],
}

Observe como cores como primary não são definidas com um código hexadecimal, mas com hsl(var(--primary)). Isso diz ao Tailwind para usar a variável CSS chamada --primary, que é definida no seu CSS global.

app/globals.css

Este arquivo agora é o coração do tema do seu sistema de design. Ele conterá as diretivas base do Tailwind e um grande bloco de variáveis CSS.CSS

@tailwind base;
@tailwind components;
@tailwind utilities;

@layer base {
  :root {
    --background: 0 0% 100%;
    --foreground: 222.2 84% 4.9%;
    --card: 0 0% 100%;
    /* ... muitas outras variáveis para o tema claro */
    --radius: 0.5rem;
  }

  .dark {
    --background: 222.2 84% 4.9%;
    --foreground: 210 40% 98%;
    --card: 222.2 84% 4.9%;
    /* ... muitas outras variáveis para o tema escuro */
  }
}

Aqui você pode ver o poder dessa configuração. Todas as cores do seu tema claro são definidas no escopo :root, e todas as cores do seu tema escuro são definidas dentro do escopo da classe .dark. Quando a classe .dark é adicionada ao elemento <html>, o navegador usará automaticamente as variáveis do tema escuro.

Parte 3: Dominando a Personalização - Tematização, Layout e Modo Escuro

Com o HeroUI inicializado, a verdadeira diversão começa: torná-lo seu. A arquitetura é explicitamente projetada para personalização profunda e intuitiva.

A Arte da Tematização com Variáveis CSS

A tematização no HeroUI é uma mudança em relação aos objetos de tema complexos baseados em JavaScript que você pode encontrar em outras bibliotecas. É mais simples, mais poderoso e aproveita recursos CSS modernos. Todo o tema — cores, raios de borda, fontes — é controlado por variáveis CSS definidas no seu arquivo globals.css.

Alterando Cores

Digamos que você queira mudar a cor primária da sua marca. Você não precisa ir para a configuração do Tailwind. Basta encontrar as variáveis CSS relevantes em globals.css e mudar seus valores.

As cores são definidas usando valores HSL (Hue, Saturation, Lightness), mas sem o wrapper hsl(). Por exemplo:CSS

:root {
  /* ... */
  --primary: 221.2 83.2% 53.3%;
  --primary-foreground: 210 40% 98%;
  /* ... */
}

.dark {
  /* ... */
  --primary: 217.2 91.2% 59.8%;
  --primary-foreground: 210 40% 98%;
  /* ... */
}

Para mudar sua cor primária para um verde vibrante, você pode usar um seletor de cores online para encontrar os valores HSL para o tom escolhido e atualizar as variáveis:CSS

/* Em globals.css */
:root {
  /* ... */
  --primary: 142.1 76.2% 36.3%; /* Nova Cor Primária Verde */
  --primary-foreground: 355.7 100% 97.3%; /* Uma cor clara contrastante para texto na cor primária */
  /* ... */
}

.dark {
  /* ... */
  --primary: 142.1 70.2% 46.3%; /* Um verde ligeiramente diferente para o modo escuro */
  --primary-foreground: 355.7 100% 97.3%;
  /* ... */
}

Depois de salvar este arquivo, cada componente que usa a cor "primary" (como <Button>) será instantaneamente atualizado em toda a sua aplicação para refletir esta nova cor verde. Isso é incrivelmente poderoso.

Alterando o Raio da Borda

O arredondamento dos cantos em componentes como cards e inputs é controlado por uma única variável CSS: --radius.CSS

/* Em globals.css */
:root {
  /* ... */
  --radius: 0.5rem; /* O valor padrão */
}

Se você preferir uma aparência mais nítida e quadrada, pode reduzir este valor:CSS

:root {
  --radius: 0.25rem; /* Menos arredondado */
}

Ou, para uma estética muito suave e arredondada, você pode aumentá-lo:CSS

:root {
  --radius: 1.5rem; /* Muito arredondado */
}

Essa única mudança de linha se propagará por todos os seus componentes, garantindo um raio de borda consistente em toda a sua UI.

Adicionando Novas Cores

Você não está limitado às cores fornecidas pelo comando init. Você pode facilmente adicionar suas próprias cores semânticas. Por exemplo, vamos adicionar uma cor de marca "special".

Defina as variáveis CSS em globals.css:CSS

/* Em globals.css */
:root {
  /* ... */
  --special: 320 86% 59%;
  --special-foreground: 330 100% 98%;
}
.dark {
  /* ... */
  --special: 320 80% 69%;
  --special-foreground: 330 100% 98%;
}

Exponha-as ao Tailwind em tailwind.config.js:JavaScript

// Em tailwind.config.js
// ...
extend: {
  colors: {
    // ...
    special: {
      DEFAULT: "hsl(var(--special))",
      foreground: "hsl(var(--special-foreground))",
    },
  },
},
// ...

Agora você pode usar essas cores em seus componentes com as classes utilitárias do Tailwind, como bg-special e text-special-foreground.

Construindo Layouts Responsivos

Os componentes do HeroUI são construídos com Tailwind CSS, o que significa que são inerentemente responsivos. Você pode usar os prefixos responsivos do Tailwind (sm:, md:, lg:, xl:) em qualquer classe utilitária para mudar o estilo de um componente em diferentes tamanhos de tela.

Vamos imaginar a construção de um layout de página simples com uma barra lateral visível no desktop, mas que colapsa no mobile. Embora o HeroUI forneça os componentes de baixo nível (Card, Button), você é responsável por compô-los em um layout maior.

Aqui está um exemplo de como você pode estruturar isso em um componente de página do Next.js:TypeScript

import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card";
import { Button } from "@/components/ui/button";

export default function DashboardPage() {
  return (
    <div className="flex min-h-screen flex-col md:flex-row">
      {/* Barra Lateral */}
      <aside className="w-full border-b bg-muted p-4 md:w-64 md:border-b-0 md:border-r">
        <h2 className="text-lg font-semibold">Navegação</h2>
        <nav className="mt-4 flex flex-row space-x-2 md:flex-col md:space-x-0 md:space-y-2">
          <Button variant="ghost" className="justify-start">Dashboard</Button>
          <Button variant="ghost" className="justify-start">Configurações</Button>
          <Button variant="ghost" className="justify-start">Perfil</Button>
        </nav>
      </aside>

      {/* Conteúdo Principal */}
      <main className="flex-1 p-8">
        <h1 className="text-4xl font-bold tracking-tight">Dashboard</h1>
        <p className="mt-2 text-muted-foreground">
          Bem-vindo ao seu dashboard.
        </p>
        <div className="mt-8 grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
          <Card>
            <CardHeader>
              <CardTitle>Receita</CardTitle>
            </CardHeader>
            <CardContent>
              <p className="text-3xl font-bold">$45,231.89</p>
            </CardContent>
          </Card>
          <Card>
            <CardHeader>
              <CardTitle>Assinaturas</CardTitle>
            </CardHeader>
            <CardContent>
              <p className="text-3xl font-bold">+2350</p>
            </CardContent>
          </Card>
          <Card>
            <CardHeader>
              <CardTitle>Usuários Ativos</CardTitle>
            </CardHeader>
            <CardContent>
              <p className="text-3xl font-bold">+573</p>
            </CardContent>
          </Card>
        </div>
      </main>
    </div>
  );
}

Neste exemplo:

Isso demonstra o princípio central: HeroUI fornece os primitivos estilizados (Card, Button), e você usa todo o poder do Tailwind CSS para organizá-los em layouts responsivos e complexos.

Implementando um Modo Escuro Perfeito

Um dos recursos mais elegantes do HeroUI é seu suporte integrado ao modo escuro. Como o comando init já configurou as variáveis de cor para os temas claro (:root) e escuro (.dark), implementá-lo é surpreendentemente simples.

A abordagem mais comum é usar o pacote next-themes, que lida com a troca de temas e persiste a escolha do usuário no armazenamento local.

Instale next-themes:Bash

npm install next-themes

Crie um Provedor de Tema:

Crie um novo arquivo, por exemplo, em components/theme-provider.tsx.TypeScript

"use client";

import * as React from "react";
import { ThemeProvider as NextThemesProvider } from "next-themes";
import { type ThemeProviderProps } from "next-themes/dist/types";

export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
  return <NextThemesProvider {...props}>{children}</NextThemesProvider>;
}

Embrulhe seu Layout Raiz com o Provedor:

No seu layout raiz do Next.js (app/layout.tsx), importe e use o ThemeProvider.TypeScript

import { ThemeProvider } from "@/components/theme-provider";
import type { Metadata } from "next";
import { Inter } from "next/font/google";
import "./globals.css";

const inter = Inter({ subsets: ["latin"] });

export const metadata: Metadata = {
  title: "Create Next App",
  description: "Generated by create next app",
};

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className={inter.className}>
        <ThemeProvider
          attribute="class"
          defaultTheme="system"
          enableSystem
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Os principais props aqui são:

Crie um Botão de Alternar Tema:

Agora, você só precisa de um elemento de UI para permitir que o usuário troque de tema.TypeScript

"use client";

import * as React from "react";
import { Moon, Sun } from "lucide-react";
import { useTheme } from "next-themes";
import { Button } from "@/components/ui/button";

export function ModeToggle() {
  const { setTheme, theme } = useTheme();

  const toggleTheme = () => {
    setTheme(theme === "light" ? "dark" : "light");
  };

  return (
    <Button variant="outline" size="icon" onClick={toggleTheme}>
      <Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
      <Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
      <span className="sr-only">Alternar tema</span>
    </Button>
  );
}

Este1 componente usa o hook useTheme do next-themes para verificar o tema atual e definir um novo. Os ícones de sol e lua rotativos proporcionam uma transição visual agradável. Basta colocar este componente <ModeToggle /> em algum lugar na sua UI (como um cabeçalho), e você terá um alternador de modo escuro totalmente funcional e persistente.

Parte 4: A CLI do HeroUI e Seu Fluxo de Trabalho Centrado em Componentes

O heroui-cli é mais do que apenas um instalador. É a ferramenta principal que você usará para gerenciar e expandir sua biblioteca de componentes. Seu principal propósito após a inicialização é adicionar novos componentes ao seu projeto.

Adicionando Componentes: O Fluxo de Trabalho Central

Digamos que você precise de um modal de diálogo para sua aplicação. Em vez de escrever um do zero, você pode pedir à CLI para adicionar o componente Dialog pré-construído e acessível do HeroUI.

O comando é simples:Bash

npx heroui-cli@latest add dialog

A CLI realizará as seguintes ações:

  1. Ela lê seu arquivo components.json para entender a estrutura do seu projeto (aliases de caminho, uso de TypeScript, etc.).
  2. Ela busca o código-fonte mais recente para o componente Dialog e quaisquer de suas dependências (por exemplo, Dialog pode depender de Button).
  3. Ela coloca os arquivos do componente diretamente no seu diretório de componentes, por exemplo: components/ui/dialog.tsx.
  4. Ela o informará sobre quaisquer outras dependências que você possa precisar instalar.

Agora, você tem um arquivo dialog.tsx em seu projeto. Você pode inspecionar seu código, aprender com ele e até mesmo modificá-lo. Se o Dialog padrão tiver uma transição que você não gosta, basta abrir o arquivo e mudar as classes do Tailwind que controlam a animação. Este nível de controle é a pedra angular da experiência HeroUI.

Você pode adicionar vários componentes de uma vez:Bash

npx heroui-cli@latest add card button input label

Este comando adicionará todos os quatro componentes e suas dependências ao seu projeto de uma só vez.

Entendendo a API da CLI: components.json

O arquivo components.json é o contrato entre seu projeto e a CLI do HeroUI. Vamos revisitar suas propriedades para entender como elas influenciam o comportamento da CLI.

Ao entender essa configuração, você pode até ajustar manualmente o comportamento da CLI se decidir refatorar a estrutura do seu projeto, por exemplo, movendo seu diretório de componentes de @/components para @/ui.

Conclusão: Construa do Seu Jeito com HeroUI

HeroUI representa uma mudança significativa na forma como os desenvolvedores podem pensar e usar bibliotecas de UI. Ele se afasta do modelo de caixa preta e tamanho único e se move em direção a uma experiência de desenvolvedor transparente, empoderadora e profundamente personalizável. Ao fornecer componentes sem estilo, acessíveis, diretamente como código-fonte, ele atinge o equilíbrio perfeito entre desenvolvimento rápido e design sob medida.

Os principais pontos fortes do HeroUI são claros:

HeroUI é para os construtores, os artesãos e as equipes que acreditam que sua interface de usuário é uma parte central da identidade de seu produto. Ele não lhe dá uma casa pronta; ele lhe dá os materiais da mais alta qualidade e uma oficina perfeitamente organizada para construir a casa dos seus sonhos. Para seu próximo projeto que exige um frontend único, polido e mantenível, não procure mais do que o HeroUI. Pode ser a ferramenta que o capacita a construir sua UI mais heroica até agora.

💡
Quer uma ótima ferramenta de Teste de API que gera documentação de API linda?

Quer uma plataforma integrada, Tudo-em-Um, para sua Equipe de Desenvolvimento trabalhar junta com máxima produtividade?

Apidog entrega todas as suas demandas e substitui o Postman por um preço muito mais acessível!
button

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar