Heroicons

Q: Quais são as três variantes de Heroicons e seus caminhos de importação?

Outline: @heroicons/react/24/outline -- 24x24, traços de 1,5px, para navegação e barras de ferramentas. Solid: @heroicons/react/24/solid -- 24x24, preenchido, para estados ativos e ênfase. Mini: @heroicons/react/20/solid -- 20x20, preenchido, para uso em linha com texto e botões.

Q: Como você controla o tamanho e a cor de um Heroicon?

Heroicons não aceitam props de size ou color. Use classes Tailwind: className="h-6 w-6 text-blue-500". Isso os torna a biblioteca de ícones mais nativa do Tailwind.

Q: Como o exemplo NavBar alterna entre ícones outline e solid?

Ele compara o pathname atual (de usePathname()) com o href de cada link. Se a rota corresponder, ele renderiza a variante Solid; caso contrário, a variante Outline. aria-current="page" é definido no link ativo para acessibilidade.

Q: Como adicionar uma animação de rotação a um Heroicon?

Como a estilização é inteiramente via className, as utilidades de animação do Tailwind funcionam diretamente.

Q: Qual tipo TypeScript você deve usar para um Heroicon passado como prop?

Não há uma exportação de tipo HeroIcon dedicada do pacote.

Q: Por que os Heroicons dependem de currentColor e o que pode dar errado?

Todos os Heroicons usam currentColor para seu traço ou preenchimento. Se o elemento pai não tiver uma cor de texto explícita, o ícone herda qualquer cor definida mais acima no DOM. Sempre defina a cor de texto correta no pai ou diretamente no ícone com uma classe Tailwind.

Receita

Instale o @heroicons/react para usar o conjunto oficial de ícones do Tailwind Labs. Os Heroicons vêm em três variantes: Outline (24px, traço de 1,5px), Solid (24px, preenchido) e Mini (20px, preenchido).

npm install @heroicons/react

// app/components/heroicon-demo.tsx
"use client";
 
import { MagnifyingGlassIcon, Cog6ToothIcon } from "@heroicons/react/24/outline";
import { HomeIcon, BellIcon } from "@heroicons/react/24/solid";
import { ChevronDownIcon } from "@heroicons/react/20/solid";
 
export function HeroiconDemo() {
  return (
    <div className="flex items-center gap-4">
      <MagnifyingGlassIcon className="h-6 w-6 text-gray-500" />
      <Cog6ToothIcon className="h-6 w-6 text-gray-500" />
      <HomeIcon className="h-6 w-6 text-blue-600" />
      <BellIcon className="h-6 w-6 text-yellow-500" />
      <ChevronDownIcon className="h-5 w-5 text-gray-400" />
    </div>
  );
}

Exemplo Funcional

Uma barra de navegação que usa ícones outline para estados padrão e ícones solid para a rota ativa:

// app/components/nav-bar.tsx
"use client";
 
import { usePathname } from "next/navigation";
import Link from "next/link";
import {
  HomeIcon as HomeOutline,
  MagnifyingGlassIcon as SearchOutline,
  BellIcon as BellOutline,
  UserIcon as UserOutline,
} from "@heroicons/react/24/outline";
import {
  HomeIcon as HomeSolid,
  MagnifyingGlassIcon as SearchSolid,
  BellIcon as BellSolid,
  UserIcon as UserSolid,
} from "@heroicons/react/24/solid";
 
interface NavLink {
  href: string;
  label: string;
  outlineIcon: React.ElementType;
  solidIcon: React.ElementType;
}
 
const navLinks: NavLink[] = [
  { href: "/", label: "Home", outlineIcon: HomeOutline, solidIcon: HomeSolid },
  { href: "/search", label: "Search", outlineIcon: SearchOutline, solidIcon: SearchSolid },
  { href: "/notifications", label: "Notifications", outlineIcon: BellOutline, solidIcon: BellSolid },
  { href: "/profile", label: "Profile", outlineIcon: UserOutline, solidIcon: UserSolid },
];
 
export function NavBar() {
  const pathname = usePathname();
 
  return (
    <nav className="fixed bottom-0 left-0 right-0 border-t border-gray-200 bg-white">
      <div className="mx-auto flex max-w-md items-center justify-around py-2">
        {navLinks.map(({ href, label, outlineIcon: OutlineIcon, solidIcon: SolidIcon }) => {
          const isActive = pathname === href;
          const Icon = isActive ? SolidIcon : OutlineIcon;
 
          return (
            <Link
              key={href}
              href={href}
              aria-label={label}
              aria-current={isActive ? "page" : undefined}
              className={`flex flex-col items-center gap-1 px-3 py-1 ${
                isActive ? "text-blue-600" : "text-gray-500 hover:text-gray-700"
              }`}
            >
              <Icon className="h-6 w-6" />
              <span className="text-xs">{label}</span>
            </Link>
          );
        })}
      </div>
    </nav>
  );
}

Mergulho Profundo

Como Funciona

Os Heroicons são organizados em três caminhos de importação que correspondem às três variantes:
- @heroicons/react/24/outline -- Ícones 24x24 com traços de 1,5px, ideais para navegação e barras de ferramentas.
- @heroicons/react/24/solid -- Ícones preenchidos 24x24, ótimos para estados ativos e ênfase.
- @heroicons/react/20/solid -- Ícones preenchidos 20x20 (Mini), projetados para uso em linha com texto, botões e elementos de formulário.
Diferente do Lucide, os Heroicons não possuem props de size ou color. Você controla dimensões e cor inteiramente através de className (ex: h-6 w-6 text-blue-500).
Isso torna os Heroicons a biblioteca de ícones mais nativa do Tailwind. Cada propriedade visual é uma classe utilitária.
O tree-shaking funciona por ícone, pois cada ícone é uma exportação nomeada de seu caminho de variante.

Variações

Quando usar cada variante:

Variante	Caminho de Importação	Tamanho	Caso de Uso
Outline	`24/outline`	24x24	Barras de navegação, barras de ferramentas, configurações
Solid	`24/solid`	24x24	Estados ativos, ações primárias, ênfase
Mini	`20/solid`	20x20	Em linha com texto, dentro de botões, campos de formulário

Botão de ícone com texto:

import { PlusIcon } from "@heroicons/react/20/solid";
 
export function AddButton() {
  return (
    <button className="inline-flex items-center gap-1.5 rounded-md bg-blue-600 px-3 py-2 text-sm font-medium text-white hover:bg-blue-700">
      <PlusIcon className="h-5 w-5" />
      Add Item
    </button>
  );
}

Ícone animado:

import { ArrowPathIcon } from "@heroicons/react/24/outline";
 
export function RefreshButton({ isLoading }: { isLoading: boolean }) {
  return (
    <button aria-label="Refresh" className="p-2">
      <ArrowPathIcon
        className={`h-5 w-5 text-gray-600 ${isLoading ? "animate-spin" : ""}`}
      />
    </button>
  );
}

Notas TypeScript

Todos os componentes Heroicon são tipados como React.ForwardRefExoticComponent<React.SVGProps<SVGSVGElement>>.
Eles aceitam todos os atributos SVG padrão mais className, style e atributos ARIA.
Não há um tipo HeroIcon dedicado exportado. Use React.ComponentType<React.SVGProps<SVGSVGElement>> para tipar props de ícones.

type HeroIcon = React.ComponentType<React.SVGProps<SVGSVGElement>>;
 
interface MenuItem {
  icon: HeroIcon;
  label: string;
}

Armadilhas

Os Heroicons não aceitam props de size ou color. Definir size={24} falhará silenciosamente. Use className="h-6 w-6" em vez disso.
As variantes outline e solid de 24px usam os mesmos nomes de componentes (ex: HomeIcon). Você deve criar um alias para um ao importar ambas as variantes no mesmo arquivo.
Os ícones Mini são 20x20, não 16x16. Se precisar de ícones de 16px, reduza o tamanho com h-4 w-4, mas esteja ciente de que o peso visual pode não ser otimizado para esse tamanho.
Heroicons v2 (a versão atual) tem nomes de ícones diferentes do v1. Se estiver migrando, verifique as mudanças nos nomes dos ícones.
Como os Heroicons dependem de currentColor, certifique-se de que o elemento pai tenha a cor de texto correta definida.

Alternativas

Abordagem	Prós	Contras
Heroicons	Integração perfeita com Tailwind, oficial do Tailwind Labs	Conjunto menor (cerca de 300 ícones)
Lucide React	Conjunto maior de ícones, props de tamanho e cor	Requer configuração adicional de props
React Icons (Hi2)	Acesso aos Heroicons junto com outras famílias	Pacote maior, dependência indireta
Phosphor Icons	Múltiplos pesos (thin, light, regular, bold, fill, duotone)	Não é do ecossistema Tailwind

FAQs

Quais são as três variantes de Heroicons e seus caminhos de importação?

Outline: @heroicons/react/24/outline -- 24x24, traços de 1,5px, para navegação e barras de ferramentas.
Solid: @heroicons/react/24/solid -- 24x24, preenchido, para estados ativos e ênfase.
Mini: @heroicons/react/20/solid -- 20x20, preenchido, para uso em linha com texto e botões.

Como você controla o tamanho e a cor de um Heroicon?

Heroicons não aceitam props de size ou color.
Use classes Tailwind: className="h-6 w-6 text-blue-500".
Isso os torna a biblioteca de ícones mais nativa do Tailwind.

Armadilha: O que acontece se você passar `size={24}` para um componente Heroicon?

Falha silenciosamente. A prop não é reconhecida.
Heroicons só aceitam atributos SVG padrão e className.
Use className="h-6 w-6" em vez disso.

Como usar as variantes outline e solid do mesmo ícone em um arquivo?

import { HomeIcon as HomeOutline } from "@heroicons/react/24/outline";
import { HomeIcon as HomeSolid } from "@heroicons/react/24/solid";

Você deve criar um alias para uma importação, pois ambas as variantes compartilham o mesmo nome de componente.

Quando você deve usar a variante Mini (20px) em vez de Outline ou Solid?

Use ícones Mini em linha com texto, dentro de botões e em elementos de formulário.
Ícones Mini são 20x20 e otimizados para contextos de exibição menores.
Outline e Solid em 24x24 são melhores para barras de navegação e barras de ferramentas.

Como o exemplo NavBar alterna entre ícones outline e solid?

Ele compara o pathname atual (de usePathname()) com o href de cada link.
Se a rota corresponder, ele renderiza a variante Solid; caso contrário, a variante Outline.
aria-current="page" é definido no link ativo para acessibilidade.

Como adicionar uma animação de rotação a um Heroicon?

<ArrowPathIcon
  className={`h-5 w-5 ${isLoading ? "animate-spin" : ""}`}
/>

Como a estilização é inteiramente via className, as utilidades de animação do Tailwind funcionam diretamente.

Qual tipo TypeScript você deve usar para um Heroicon passado como prop?

type HeroIcon = React.ComponentType<React.SVGProps<SVGSVGElement>>;
 
interface MenuItem {
  icon: HeroIcon;
  label: string;
}

Não há uma exportação de tipo HeroIcon dedicada do pacote.

Armadilha: Os nomes dos ícones Heroicons v1 e v2 são compatíveis?

Não. Heroicons v2 tem nomes de ícones diferentes do v1.
Se estiver migrando do v1, verifique as mudanças nos nomes dos ícones nas notas de lançamento da v2.0.0.

Por que os Heroicons dependem de `currentColor` e o que pode dar errado?

Todos os Heroicons usam currentColor para seu traço ou preenchimento.
Se o elemento pai não tiver uma cor de texto explícita, o ícone herda qualquer cor definida mais acima no DOM.
Sempre defina a cor de texto correta no pai ou diretamente no ícone com uma classe Tailwind.

É seguro redimensionar ícones Mini para 16x16?

Você pode aplicar h-4 w-4, mas o peso visual pode não ser otimizado para esse tamanho.
Ícones Mini são projetados para 20x20. Redimensionar para um tamanho menor pode parecer muito pesado ou perder detalhes.

Links Relacionados

Receita

npm install @heroicons/react

// app/components/heroicon-demo.tsx
"use client";
 
import { MagnifyingGlassIcon, Cog6ToothIcon } from "@heroicons/react/24/outline";
import { HomeIcon, BellIcon } from "@heroicons/react/24/solid";
import { ChevronDownIcon } from "@heroicons/react/20/solid";
 
export function HeroiconDemo() {
  return (
    <div className="flex items-center gap-4">
      <MagnifyingGlassIcon className="h-6 w-6 text-gray-500" />
      <Cog6ToothIcon className="h-6 w-6 text-gray-500" />
      <HomeIcon className="h-6 w-6 text-blue-600" />
      <BellIcon className="h-6 w-6 text-yellow-500" />
      <ChevronDownIcon className="h-5 w-5 text-gray-400" />
    </div>
  );
}

Exemplo Funcional

Uma barra de navegação que usa ícones outline para estados padrão e ícones solid para a rota ativa:

// app/components/nav-bar.tsx
"use client";
 
import { usePathname } from "next/navigation";
import Link from "next/link";
import {
  HomeIcon as HomeOutline,
  MagnifyingGlassIcon as SearchOutline,
  BellIcon as BellOutline,
  UserIcon as UserOutline,
} from "@heroicons/react/24/outline";
import {
  HomeIcon as HomeSolid,
  MagnifyingGlassIcon as SearchSolid,
  BellIcon as BellSolid,
  UserIcon as UserSolid,
} from "@heroicons/react/24/solid";
 
interface NavLink {
  href: string;
  label: string;
  outlineIcon: React.ElementType;
  solidIcon: React.ElementType;
}
 
const navLinks: NavLink[] = [
  { href: "/", label: "Home", outlineIcon: HomeOutline, solidIcon: HomeSolid },
  { href: "/search", label: "Search", outlineIcon: SearchOutline, solidIcon: SearchSolid },
  { href: "/notifications", label: "Notifications", outlineIcon: BellOutline, solidIcon: BellSolid },
  { href: "/profile", label: "Profile", outlineIcon: UserOutline, solidIcon: UserSolid },
];
 
export function NavBar() {
  const pathname = usePathname();
 
  return (
    <nav className="fixed bottom-0 left-0 right-0 border-t border-gray-200 bg-white">
      <div className="mx-auto flex max-w-md items-center justify-around py-2">
        {navLinks.map(({ href, label, outlineIcon: OutlineIcon, solidIcon: SolidIcon }) => {
          const isActive = pathname === href;
          const Icon = isActive ? SolidIcon : OutlineIcon;
 
          return (
            <Link
              key={href}
              href={href}
              aria-label={label}
              aria-current={isActive ? "page" : undefined}
              className={`flex flex-col items-center gap-1 px-3 py-1 ${
                isActive ? "text-blue-600" : "text-gray-500 hover:text-gray-700"
              }`}
            >
              <Icon className="h-6 w-6" />
              <span className="text-xs">{label}</span>
            </Link>
          );
        })}
      </div>
    </nav>
  );
}

Mergulho Profundo

Como Funciona

Os Heroicons são organizados em três caminhos de importação que correspondem às três variantes:
- @heroicons/react/24/outline -- Ícones 24x24 com traços de 1,5px, ideais para navegação e barras de ferramentas.
- @heroicons/react/24/solid -- Ícones preenchidos 24x24, ótimos para estados ativos e ênfase.
- @heroicons/react/20/solid -- Ícones preenchidos 20x20 (Mini), projetados para uso em linha com texto, botões e elementos de formulário.
Diferente do Lucide, os Heroicons não possuem props de size ou color. Você controla dimensões e cor inteiramente através de className (ex: h-6 w-6 text-blue-500).
Isso torna os Heroicons a biblioteca de ícones mais nativa do Tailwind. Cada propriedade visual é uma classe utilitária.
O tree-shaking funciona por ícone, pois cada ícone é uma exportação nomeada de seu caminho de variante.

Variações

Quando usar cada variante:

Variante	Caminho de Importação	Tamanho	Caso de Uso
Outline	`24/outline`	24x24	Barras de navegação, barras de ferramentas, configurações
Solid	`24/solid`	24x24	Estados ativos, ações primárias, ênfase
Mini	`20/solid`	20x20	Em linha com texto, dentro de botões, campos de formulário

Botão de ícone com texto:

import { PlusIcon } from "@heroicons/react/20/solid";
 
export function AddButton() {
  return (
    <button className="inline-flex items-center gap-1.5 rounded-md bg-blue-600 px-3 py-2 text-sm font-medium text-white hover:bg-blue-700">
      <PlusIcon className="h-5 w-5" />
      Add Item
    </button>
  );
}

Ícone animado:

import { ArrowPathIcon } from "@heroicons/react/24/outline";
 
export function RefreshButton({ isLoading }: { isLoading: boolean }) {
  return (
    <button aria-label="Refresh" className="p-2">
      <ArrowPathIcon
        className={`h-5 w-5 text-gray-600 ${isLoading ? "animate-spin" : ""}`}
      />
    </button>
  );
}

Notas TypeScript

Todos os componentes Heroicon são tipados como React.ForwardRefExoticComponent<React.SVGProps<SVGSVGElement>>.
Eles aceitam todos os atributos SVG padrão mais className, style e atributos ARIA.
Não há um tipo HeroIcon dedicado exportado. Use React.ComponentType<React.SVGProps<SVGSVGElement>> para tipar props de ícones.

type HeroIcon = React.ComponentType<React.SVGProps<SVGSVGElement>>;
 
interface MenuItem {
  icon: HeroIcon;
  label: string;
}

Armadilhas

Os Heroicons não aceitam props de size ou color. Definir size={24} falhará silenciosamente. Use className="h-6 w-6" em vez disso.
As variantes outline e solid de 24px usam os mesmos nomes de componentes (ex: HomeIcon). Você deve criar um alias para um ao importar ambas as variantes no mesmo arquivo.
Os ícones Mini são 20x20, não 16x16. Se precisar de ícones de 16px, reduza o tamanho com h-4 w-4, mas esteja ciente de que o peso visual pode não ser otimizado para esse tamanho.
Heroicons v2 (a versão atual) tem nomes de ícones diferentes do v1. Se estiver migrando, verifique as mudanças nos nomes dos ícones.
Como os Heroicons dependem de currentColor, certifique-se de que o elemento pai tenha a cor de texto correta definida.

Alternativas

Abordagem	Prós	Contras
Heroicons	Integração perfeita com Tailwind, oficial do Tailwind Labs	Conjunto menor (cerca de 300 ícones)
Lucide React	Conjunto maior de ícones, props de tamanho e cor	Requer configuração adicional de props
React Icons (Hi2)	Acesso aos Heroicons junto com outras famílias	Pacote maior, dependência indireta
Phosphor Icons	Múltiplos pesos (thin, light, regular, bold, fill, duotone)	Não é do ecossistema Tailwind

FAQs

Quais são as três variantes de Heroicons e seus caminhos de importação?

Outline: @heroicons/react/24/outline -- 24x24, traços de 1,5px, para navegação e barras de ferramentas.
Solid: @heroicons/react/24/solid -- 24x24, preenchido, para estados ativos e ênfase.
Mini: @heroicons/react/20/solid -- 20x20, preenchido, para uso em linha com texto e botões.

Como você controla o tamanho e a cor de um Heroicon?

Heroicons não aceitam props de size ou color.
Use classes Tailwind: className="h-6 w-6 text-blue-500".
Isso os torna a biblioteca de ícones mais nativa do Tailwind.

Armadilha: O que acontece se você passar `size={24}` para um componente Heroicon?

Falha silenciosamente. A prop não é reconhecida.
Heroicons só aceitam atributos SVG padrão e className.
Use className="h-6 w-6" em vez disso.

Como usar as variantes outline e solid do mesmo ícone em um arquivo?

import { HomeIcon as HomeOutline } from "@heroicons/react/24/outline";
import { HomeIcon as HomeSolid } from "@heroicons/react/24/solid";

Você deve criar um alias para uma importação, pois ambas as variantes compartilham o mesmo nome de componente.

Quando você deve usar a variante Mini (20px) em vez de Outline ou Solid?

Use ícones Mini em linha com texto, dentro de botões e em elementos de formulário.
Ícones Mini são 20x20 e otimizados para contextos de exibição menores.
Outline e Solid em 24x24 são melhores para barras de navegação e barras de ferramentas.

Como o exemplo NavBar alterna entre ícones outline e solid?

Ele compara o pathname atual (de usePathname()) com o href de cada link.
Se a rota corresponder, ele renderiza a variante Solid; caso contrário, a variante Outline.
aria-current="page" é definido no link ativo para acessibilidade.

Como adicionar uma animação de rotação a um Heroicon?

<ArrowPathIcon
  className={`h-5 w-5 ${isLoading ? "animate-spin" : ""}`}
/>

Como a estilização é inteiramente via className, as utilidades de animação do Tailwind funcionam diretamente.

Qual tipo TypeScript você deve usar para um Heroicon passado como prop?

type HeroIcon = React.ComponentType<React.SVGProps<SVGSVGElement>>;
 
interface MenuItem {
  icon: HeroIcon;
  label: string;
}

Não há uma exportação de tipo HeroIcon dedicada do pacote.

Armadilha: Os nomes dos ícones Heroicons v1 e v2 são compatíveis?

Não. Heroicons v2 tem nomes de ícones diferentes do v1.
Se estiver migrando do v1, verifique as mudanças nos nomes dos ícones nas notas de lançamento da v2.0.0.

Por que os Heroicons dependem de `currentColor` e o que pode dar errado?

Todos os Heroicons usam currentColor para seu traço ou preenchimento.
Se o elemento pai não tiver uma cor de texto explícita, o ícone herda qualquer cor definida mais acima no DOM.
Sempre defina a cor de texto correta no pai ou diretamente no ícone com uma classe Tailwind.

É seguro redimensionar ícones Mini para 16x16?

Você pode aplicar h-4 w-4, mas o peso visual pode não ser otimizado para esse tamanho.
Ícones Mini são projetados para 20x20. Redimensionar para um tamanho menor pode parecer muito pesado ou perder detalhes.

Heroicons

Buscar na documentação

Heroicons