Ícones Lucide React

Q: O que acontece se você definir a prop color e uma classe de cor de texto Tailwind em um ícone Lucide?

A prop explícita color substitui currentColor. A classe Tailwind (por exemplo, text-blue-500) define currentColor, mas a prop tem precedência. Use um ou outro, não ambos.

Q: Como tornar um ícone Lucide não quadrado (largura e altura diferentes)?

A prop size define width e height com o mesmo valor. Para dimensionamento não quadrado, passe as props width e height individualmente em vez de size.

Q: Qual tipo TypeScript você deve usar ao passar um ícone Lucide como prop?

LucideIcon tipa o próprio componente; LucideProps estende SVGProps.

Q: Como o exemplo da barra de ferramentas de ícones lida com o estado ativo e a acessibilidade?

Ele usa useState para rastrear qual ferramenta está ativa. Cada botão tem aria-label para leitores de tela e aria-pressed para indicar o estado do toggle. Ícones ativos recebem uma strokeWidth mais espessa (2,5 vs 2) e um fundo azul.

Q: Armadilha: Que risco a busca dinâmica de ícones de dados do CMS introduz?

icons[name] não fornece validação em tempo de compilação de que o nome do ícone existe. Um erro de digitação ou um ícone ausente retorna silenciosamente undefined. Crie uma lista de permissões (whitelist) de nomes de ícones permitidos para cenários controlados por CMS.

Q: Como o objeto icons é tipado no lucide-react?

Ele é tipado como Record. Isso permite buscas dinâmicas seguras em termos de tipo, mas ainda requer uma verificação de existência em tempo de execução, pois qualquer chave de string é aceita.

Receita

Instale o Lucide React, importe ícones individuais por nome e personalize-os com props ou classes Tailwind. Cada ícone é um módulo separado, então seu bundle inclui apenas os ícones que você realmente usa.

npm install lucide-react

// app/components/icon-demo.tsx
"use client";
 
import { Search, Menu, X, Settings, Bell } from "lucide-react";
 
export function IconDemo() {
  return (
    <div className="flex items-center gap-4">
      <Search size={24} color="currentColor" strokeWidth={2} />
      <Menu size={24} className="text-gray-600" />
      <X size={20} className="text-red-500" />
      <Settings size={24} strokeWidth={1.5} />
      <Bell size={24} className="text-blue-600" />
    </div>
  );
}

Exemplo de Trabalho

Uma barra de ferramentas com botões de ícone, estados de hover e rótulos de acessibilidade:

// app/components/icon-toolbar.tsx
"use client";
 
import { Bold, Italic, Underline, AlignLeft, AlignCenter, AlignRight, Link, Image } from "lucide-react";
import { useState } from "react";
 
interface ToolbarButton {
  icon: React.ElementType;
  label: string;
  action: string;
}
 
const tools: ToolbarButton[] = [
  { icon: Bold, label: "Bold", action: "bold" },
  { icon: Italic, label: "Italic", action: "italic" },
  { icon: Underline, label: "Underline", action: "underline" },
  { icon: AlignLeft, label: "Align Left", action: "align-left" },
  { icon: AlignCenter, label: "Align Center", action: "align-center" },
  { icon: AlignRight, label: "Align Right", action: "align-right" },
  { icon: Link, label: "Insert Link", action: "link" },
  { icon: Image, label: "Insert Image", action: "image" },
];
 
export function IconToolbar() {
  const [active, setActive] = useState<string | null>(null);
 
  return (
    <div className="flex items-center gap-1 rounded-lg border border-gray-200 bg-white p-2">
      {tools.map(({ icon: Icon, label, action }) => (
        <button
          key={action}
          onClick={() => setActive(active === action ? null : action)}
          aria-label={label}
          aria-pressed={active === action}
          className={`rounded p-2 transition-colors hover:bg-gray-100 ${
            active === action ? "bg-blue-100 text-blue-600" : "text-gray-600"
          }`}
        >
          <Icon size={18} strokeWidth={active === action ? 2.5 : 2} />
        </button>
      ))}
    </div>
  );
}

Análise Detalhada

Como Funciona

Lucide é um fork do Feather Icons com um conjunto de ícones expandido (mais de 1.400 ícones) e manutenção ativa.
Cada ícone é exportado como uma exportação nomeada de lucide-react, mas também está disponível como um módulo autônomo em lucide-react/dist/esm/icons/{nome-do-icone}.
Os ícones são renderizados como elementos SVG inline com padrões sensatos: tamanho 24x24, largura de traço de 2px, traço currentColor.
O tree-shaking funciona automaticamente com bundlers modernos (webpack 5, Vite, Turbopack) porque cada ícone é uma entrada de módulo ES separada.
Todos os ícones aceitam atributos SVG padrão e atributos HTML do React, incluindo className, style, onClick e atributos ARIA.

Variações

Renderização dinâmica de ícone a partir de um nome de string:

import { icons } from "lucide-react";
import type { LucideIcon } from "lucide-react";
 
interface DynamicIconProps {
  name: string;
  size?: number;
  className?: string;
}
 
export function DynamicIcon({ name, size = 24, className }: DynamicIconProps) {
  const IconComponent = icons[name as keyof typeof icons] as LucideIcon | undefined;
 
  if (!IconComponent) {
    return null;
  }
 
  return <IconComponent size={size} className={className} />;
}
 
// Uso: <DynamicIcon name="ArrowRight" size={20} className="text-blue-500" />

Observação: Importar o objeto icons inteiro anula o tree-shaking. Use a renderização dinâmica apenas quando realmente precisar dela (por exemplo, seleção de ícones controlada por CMS).

Componente wrapper de ícone personalizado:

import type { LucideIcon } from "lucide-react";
 
interface IconButtonProps {
  icon: LucideIcon;
  label: string;
  onClick: () => void;
  variant?: "default" | "danger" | "success";
}
 
const variantStyles = {
  default: "text-gray-600 hover:bg-gray-100",
  danger: "text-red-600 hover:bg-red-50",
  success: "text-green-600 hover:bg-green-50",
};
 
export function IconButton({ icon: Icon, label, onClick, variant = "default" }: IconButtonProps) {
  return (
    <button
      onClick={onClick}
      aria-label={label}
      className={`rounded-lg p-2 transition-colors ${variantStyles[variant]}`}
    >
      <Icon size={20} />
    </button>
  );
}

Notas TypeScript

Importe o tipo LucideIcon para tipar componentes de ícone passados como props.
Todos os componentes de ícone aceitam LucideProps, que estende SVGProps<SVGSVGElement> com size, color, strokeWidth e absoluteStrokeWidth.
O objeto icons é tipado como Record<string, LucideIcon>, permitindo buscas dinâmicas seguras em termos de tipo.

import type { LucideIcon, LucideProps } from "lucide-react";
 
// Tipa uma prop de ícone
interface Props {
  icon: LucideIcon;
  iconProps?: LucideProps;
}

Armadilhas Comuns

Importar de lucide-react com importações de barril como import * as icons agrupará todos os ícones (mais de 1.400 SVGs). Sempre use importações nomeadas para builds de produção.
A prop color define o atributo stroke do SVG, não fill. Ícones Lucide são baseados em traço, então fill não tem efeito visível na maioria dos ícones.
Se você usar className para definir a cor via Tailwind (por exemplo, text-blue-500), não defina também a prop color, pois a prop explícita substitui currentColor.
size define width e height simultaneamente. Para dimensionamento não quadrado, use as props width e height individualmente.
Importações dinâmicas usando icons[name] não fornecem validação em tempo de compilação de que o nome do ícone existe. Considere criar uma lista de permissões (whitelist) para cenários controlados por CMS.

Alternativas

Abordagem	Prós	Contras
Lucide React	Excelente tree-shaking, grande conjunto de ícones, manutenção ativa	O estilo apenas com traço pode não se adequar a todos os designs
React Icons	Múltiplas famílias de ícones em um único pacote	Tamanho de instalação maior, APIs inconsistentes entre famílias
Heroicons	Projeto oficial do Tailwind Labs, ótima integração com Tailwind	Conjunto de ícones menor (cerca de 300 ícones)
Componentes SVG personalizados	Controle total do design, zero dependências	Manutenção manual, sem descoberta de ícones

FAQs

Como instalar e importar um ícone Lucide em um componente React?

npm install lucide-react
 
import { Search } from "lucide-react";
 
export function MyComponent() {
  return <Search size={24} className="text-gray-600" />;
}

Quais são o tamanho, a largura do traço e a cor padrão para ícones Lucide?

O tamanho padrão é 24x24 pixels.
A largura do traço padrão é 2px.
A cor padrão é currentColor, que herda da propriedade color CSS pai.

Por que o Lucide React tem bom tree-shaking e como você pode quebrá-lo acidentalmente?

Cada ícone é uma entrada de módulo ES separada, então os bundlers incluem apenas os ícones que você importa por nome.
Importar o objeto icons inteiro (import { icons } from "lucide-react") agrupa todos os 1.400+ ícones e desabilita o tree-shaking.

Como renderizar um ícone Lucide dinamicamente a partir de um nome de string?

import { icons } from "lucide-react";
import type { LucideIcon } from "lucide-react";
 
const IconComponent = icons[name as keyof typeof icons] as LucideIcon | undefined;
if (IconComponent) return <IconComponent size={24} />;

Observação: isso importa todos os ícones e desabilita o tree-shaking.

O que acontece se você definir a prop `color` e uma classe de cor de texto Tailwind em um ícone Lucide?

A prop explícita color substitui currentColor.
A classe Tailwind (por exemplo, text-blue-500) define currentColor, mas a prop tem precedência.
Use um ou outro, não ambos.

Como criar um componente wrapper de botão de ícone reutilizável com estilos de variante?

import type { LucideIcon } from "lucide-react";
 
interface IconButtonProps {
  icon: LucideIcon;
  label: string;
  onClick: () => void;
  variant?: "default" | "danger";
}
 
export function IconButton({ icon: Icon, label, onClick, variant = "default" }: IconButtonProps) {
  return (
    <button onClick={onClick} aria-label={label}>
      <Icon size={20} />
    </button>
  );
}

Armadilha: Por que definir `fill` não tem efeito visível na maioria dos ícones Lucide?

Ícones Lucide são baseados em traço, não em preenchimento.
A prop color controla o atributo stroke, não fill.
Definir fill="red" em um ícone de traço não alterará sua aparência.

Como tornar um ícone Lucide não quadrado (largura e altura diferentes)?

A prop size define width e height com o mesmo valor.
Para dimensionamento não quadrado, passe as props width e height individualmente em vez de size.

Qual tipo TypeScript você deve usar ao passar um ícone Lucide como prop?

import type { LucideIcon, LucideProps } from "lucide-react";
 
interface Props {
  icon: LucideIcon;
  iconProps?: LucideProps;
}

LucideIcon tipa o próprio componente; LucideProps estende SVGProps<SVGSVGElement>.

Como o exemplo da barra de ferramentas de ícones lida com o estado ativo e a acessibilidade?

Ele usa useState para rastrear qual ferramenta está ativa.
Cada botão tem aria-label para leitores de tela e aria-pressed para indicar o estado do toggle.
Ícones ativos recebem uma strokeWidth mais espessa (2,5 vs 2) e um fundo azul.

Armadilha: Que risco a busca dinâmica de ícones de dados do CMS introduz?

icons[name] não fornece validação em tempo de compilação de que o nome do ícone existe.
Um erro de digitação ou um ícone ausente retorna silenciosamente undefined.
Crie uma lista de permissões (whitelist) de nomes de ícones permitidos para cenários controlados por CMS.

Como o objeto `icons` é tipado no lucide-react?

Ele é tipado como Record<string, LucideIcon>.
Isso permite buscas dinâmicas seguras em termos de tipo, mas ainda requer uma verificação de existência em tempo de execução, pois qualquer chave de string é aceita.

Links Relacionados

Receita

npm install lucide-react

// app/components/icon-demo.tsx
"use client";
 
import { Search, Menu, X, Settings, Bell } from "lucide-react";
 
export function IconDemo() {
  return (
    <div className="flex items-center gap-4">
      <Search size={24} color="currentColor" strokeWidth={2} />
      <Menu size={24} className="text-gray-600" />
      <X size={20} className="text-red-500" />
      <Settings size={24} strokeWidth={1.5} />
      <Bell size={24} className="text-blue-600" />
    </div>
  );
}

Exemplo de Trabalho

Uma barra de ferramentas com botões de ícone, estados de hover e rótulos de acessibilidade:

// app/components/icon-toolbar.tsx
"use client";
 
import { Bold, Italic, Underline, AlignLeft, AlignCenter, AlignRight, Link, Image } from "lucide-react";
import { useState } from "react";
 
interface ToolbarButton {
  icon: React.ElementType;
  label: string;
  action: string;
}
 
const tools: ToolbarButton[] = [
  { icon: Bold, label: "Bold", action: "bold" },
  { icon: Italic, label: "Italic", action: "italic" },
  { icon: Underline, label: "Underline", action: "underline" },
  { icon: AlignLeft, label: "Align Left", action: "align-left" },
  { icon: AlignCenter, label: "Align Center", action: "align-center" },
  { icon: AlignRight, label: "Align Right", action: "align-right" },
  { icon: Link, label: "Insert Link", action: "link" },
  { icon: Image, label: "Insert Image", action: "image" },
];
 
export function IconToolbar() {
  const [active, setActive] = useState<string | null>(null);
 
  return (
    <div className="flex items-center gap-1 rounded-lg border border-gray-200 bg-white p-2">
      {tools.map(({ icon: Icon, label, action }) => (
        <button
          key={action}
          onClick={() => setActive(active === action ? null : action)}
          aria-label={label}
          aria-pressed={active === action}
          className={`rounded p-2 transition-colors hover:bg-gray-100 ${
            active === action ? "bg-blue-100 text-blue-600" : "text-gray-600"
          }`}
        >
          <Icon size={18} strokeWidth={active === action ? 2.5 : 2} />
        </button>
      ))}
    </div>
  );
}

Análise Detalhada

Como Funciona

Lucide é um fork do Feather Icons com um conjunto de ícones expandido (mais de 1.400 ícones) e manutenção ativa.
Cada ícone é exportado como uma exportação nomeada de lucide-react, mas também está disponível como um módulo autônomo em lucide-react/dist/esm/icons/{nome-do-icone}.
Os ícones são renderizados como elementos SVG inline com padrões sensatos: tamanho 24x24, largura de traço de 2px, traço currentColor.
O tree-shaking funciona automaticamente com bundlers modernos (webpack 5, Vite, Turbopack) porque cada ícone é uma entrada de módulo ES separada.
Todos os ícones aceitam atributos SVG padrão e atributos HTML do React, incluindo className, style, onClick e atributos ARIA.

Variações

Renderização dinâmica de ícone a partir de um nome de string:

import { icons } from "lucide-react";
import type { LucideIcon } from "lucide-react";
 
interface DynamicIconProps {
  name: string;
  size?: number;
  className?: string;
}
 
export function DynamicIcon({ name, size = 24, className }: DynamicIconProps) {
  const IconComponent = icons[name as keyof typeof icons] as LucideIcon | undefined;
 
  if (!IconComponent) {
    return null;
  }
 
  return <IconComponent size={size} className={className} />;
}
 
// Uso: <DynamicIcon name="ArrowRight" size={20} className="text-blue-500" />

Observação: Importar o objeto icons inteiro anula o tree-shaking. Use a renderização dinâmica apenas quando realmente precisar dela (por exemplo, seleção de ícones controlada por CMS).

Componente wrapper de ícone personalizado:

import type { LucideIcon } from "lucide-react";
 
interface IconButtonProps {
  icon: LucideIcon;
  label: string;
  onClick: () => void;
  variant?: "default" | "danger" | "success";
}
 
const variantStyles = {
  default: "text-gray-600 hover:bg-gray-100",
  danger: "text-red-600 hover:bg-red-50",
  success: "text-green-600 hover:bg-green-50",
};
 
export function IconButton({ icon: Icon, label, onClick, variant = "default" }: IconButtonProps) {
  return (
    <button
      onClick={onClick}
      aria-label={label}
      className={`rounded-lg p-2 transition-colors ${variantStyles[variant]}`}
    >
      <Icon size={20} />
    </button>
  );
}

Notas TypeScript

Importe o tipo LucideIcon para tipar componentes de ícone passados como props.
Todos os componentes de ícone aceitam LucideProps, que estende SVGProps<SVGSVGElement> com size, color, strokeWidth e absoluteStrokeWidth.
O objeto icons é tipado como Record<string, LucideIcon>, permitindo buscas dinâmicas seguras em termos de tipo.

import type { LucideIcon, LucideProps } from "lucide-react";
 
// Tipa uma prop de ícone
interface Props {
  icon: LucideIcon;
  iconProps?: LucideProps;
}

Armadilhas Comuns

Importar de lucide-react com importações de barril como import * as icons agrupará todos os ícones (mais de 1.400 SVGs). Sempre use importações nomeadas para builds de produção.
A prop color define o atributo stroke do SVG, não fill. Ícones Lucide são baseados em traço, então fill não tem efeito visível na maioria dos ícones.
Se você usar className para definir a cor via Tailwind (por exemplo, text-blue-500), não defina também a prop color, pois a prop explícita substitui currentColor.
size define width e height simultaneamente. Para dimensionamento não quadrado, use as props width e height individualmente.
Importações dinâmicas usando icons[name] não fornecem validação em tempo de compilação de que o nome do ícone existe. Considere criar uma lista de permissões (whitelist) para cenários controlados por CMS.

Alternativas

Abordagem	Prós	Contras
Lucide React	Excelente tree-shaking, grande conjunto de ícones, manutenção ativa	O estilo apenas com traço pode não se adequar a todos os designs
React Icons	Múltiplas famílias de ícones em um único pacote	Tamanho de instalação maior, APIs inconsistentes entre famílias
Heroicons	Projeto oficial do Tailwind Labs, ótima integração com Tailwind	Conjunto de ícones menor (cerca de 300 ícones)
Componentes SVG personalizados	Controle total do design, zero dependências	Manutenção manual, sem descoberta de ícones

FAQs

Como instalar e importar um ícone Lucide em um componente React?

npm install lucide-react
 
import { Search } from "lucide-react";
 
export function MyComponent() {
  return <Search size={24} className="text-gray-600" />;
}

Quais são o tamanho, a largura do traço e a cor padrão para ícones Lucide?

O tamanho padrão é 24x24 pixels.
A largura do traço padrão é 2px.
A cor padrão é currentColor, que herda da propriedade color CSS pai.

Por que o Lucide React tem bom tree-shaking e como você pode quebrá-lo acidentalmente?

Cada ícone é uma entrada de módulo ES separada, então os bundlers incluem apenas os ícones que você importa por nome.
Importar o objeto icons inteiro (import { icons } from "lucide-react") agrupa todos os 1.400+ ícones e desabilita o tree-shaking.

Como renderizar um ícone Lucide dinamicamente a partir de um nome de string?

import { icons } from "lucide-react";
import type { LucideIcon } from "lucide-react";
 
const IconComponent = icons[name as keyof typeof icons] as LucideIcon | undefined;
if (IconComponent) return <IconComponent size={24} />;

Observação: isso importa todos os ícones e desabilita o tree-shaking.

O que acontece se você definir a prop `color` e uma classe de cor de texto Tailwind em um ícone Lucide?

A prop explícita color substitui currentColor.
A classe Tailwind (por exemplo, text-blue-500) define currentColor, mas a prop tem precedência.
Use um ou outro, não ambos.

Como criar um componente wrapper de botão de ícone reutilizável com estilos de variante?

import type { LucideIcon } from "lucide-react";
 
interface IconButtonProps {
  icon: LucideIcon;
  label: string;
  onClick: () => void;
  variant?: "default" | "danger";
}
 
export function IconButton({ icon: Icon, label, onClick, variant = "default" }: IconButtonProps) {
  return (
    <button onClick={onClick} aria-label={label}>
      <Icon size={20} />
    </button>
  );
}

Armadilha: Por que definir `fill` não tem efeito visível na maioria dos ícones Lucide?

Ícones Lucide são baseados em traço, não em preenchimento.
A prop color controla o atributo stroke, não fill.
Definir fill="red" em um ícone de traço não alterará sua aparência.

Como tornar um ícone Lucide não quadrado (largura e altura diferentes)?

A prop size define width e height com o mesmo valor.
Para dimensionamento não quadrado, passe as props width e height individualmente em vez de size.

Qual tipo TypeScript você deve usar ao passar um ícone Lucide como prop?

import type { LucideIcon, LucideProps } from "lucide-react";
 
interface Props {
  icon: LucideIcon;
  iconProps?: LucideProps;
}

LucideIcon tipa o próprio componente; LucideProps estende SVGProps<SVGSVGElement>.

Como o exemplo da barra de ferramentas de ícones lida com o estado ativo e a acessibilidade?

Ele usa useState para rastrear qual ferramenta está ativa.
Cada botão tem aria-label para leitores de tela e aria-pressed para indicar o estado do toggle.
Ícones ativos recebem uma strokeWidth mais espessa (2,5 vs 2) e um fundo azul.

Armadilha: Que risco a busca dinâmica de ícones de dados do CMS introduz?

icons[name] não fornece validação em tempo de compilação de que o nome do ícone existe.
Um erro de digitação ou um ícone ausente retorna silenciosamente undefined.
Crie uma lista de permissões (whitelist) de nomes de ícones permitidos para cenários controlados por CMS.

Como o objeto `icons` é tipado no lucide-react?

Ele é tipado como Record<string, LucideIcon>.
Isso permite buscas dinâmicas seguras em termos de tipo, mas ainda requer uma verificação de existência em tempo de execução, pois qualquer chave de string é aceita.

Ícones Lucide React

Buscar na documentação

Ícones Lucide React