# Coloque um logo de empresa no seu app — receitas prontas para copiar e colar > Snippets práticos para as formas comuns nas quais um logo acaba: uma tag ``, um componente React, uma Next.js Image, um slot de avatar Tailwind, um elemento `` consciente de modo escuro, um fallback de imagem OG e uma URL assinada no servidor. Todo snippet funciona contra o endpoint público `https://api.clearlogo.dev`. > > Todos os exemplos assumem que você tem uma chave de navegador (para código de cliente) ou uma chave de servidor (para código de backend). [Crie uma chave](https://clearlogo.dev/login?lang=pt) no painel. ## 1. HTML simples Integração mais rápida possível — cole a URL em uma tag ``. ```html GitHub ``` Defina `size` para corresponder à dimensão renderizada para que o navegador não desperdice largura de banda escalando um ativo maior. ## 2. Componente React Um pequeno componente reutilizável cobre a maioria das necessidades de UI do produto. ```tsx type CompanyLogoProps = { domain: string; size?: 32 | 48 | 64 | 96 | 128; alt?: string; }; const BROWSER_KEY = process.env.NEXT_PUBLIC_CLEARLOGO_KEY!; export function CompanyLogo({ domain, size = 64, alt }: CompanyLogoProps) { return ( {alt ); } ``` `loading="lazy"` e `decoding="async"` evitam que listas longas (CRMs, diretórios, tabelas de contas) bloqueiem a renderização. ## 3. Next.js `` Adicione o host da API a `next.config.js` uma vez, depois use o componente `` otimizado em qualquer lugar. ```js // next.config.js module.exports = { images: { remotePatterns: [ { protocol: "https", hostname: "api.clearlogo.dev" }, ], }, }; ``` ```tsx import Image from "next/image"; export function CompanyLogo({ domain, size = 64 }: { domain: string; size?: number }) { return ( {`${domain} ); } ``` Peça `size * 2` para nitidez retina em displays HiDPI. Use `unoptimized` se quiser que a negociação de WebP da API flua para o cliente; remova se quiser que o Next.js trate a negociação de formato em si. ## 4. Slot de avatar Tailwind Coloque o logo em um slot de UI fixo que permaneça visualmente consistente entre marcas. ```tsx
{name}
{domain}
``` `object-contain` mais um tamanho de slot fixo é a forma mais confiável para tabelas e listas. Emparelhe com o parâmetro `content=80` para que o logo nunca toque a borda do slot. ## 5. Logo consciente de modo escuro Use `` com `prefers-color-scheme` para trocar variantes escuras/claras no tempo de renderização, sem JavaScript ou rerenders por logo. ```html GitHub ``` Envolvido como um componente React: ```tsx export function CompanyLogo({ domain, size = 64 }: { domain: string; size?: number }) { const base = `https://api.clearlogo.dev/logo/${domain}?size=${size}&content=80&token=${BROWSER_KEY}`; return ( {`${domain} ); } ``` A API volta para a variante clara quando nenhuma versão escura existe, então é sempre seguro pedir `theme=dark`. Para mudanças de tema no nível do app (não no nível do SO), conduza a URL da fonte do seu estado de tema em vez de `prefers-color-scheme`. ## 6. Renderização de lista com placeholder Para listas longas, renderize um placeholder imediato para que slots vazios não piscassem. ```tsx function LogoCell({ domain }: { domain: string }) { const [loaded, setLoaded] = useState(false); return (
setLoaded(true)} className={`h-full w-full object-contain transition-opacity ${ loaded ? "opacity-100" : "opacity-0" }`} />
); } ``` ## 7. Fallback de erro com a primeira letra Se a API não conseguir encontrar um logo para um domínio, renderize um avatar de letra determinístico em vez disso. ```tsx function LogoOrFallback({ domain, name }: { domain: string; name: string }) { const [errored, setErrored] = useState(false); if (errored) { return (
{name[0]?.toUpperCase() ?? "?"}
); } return ( {`${name} setErrored(true)} /> ); } ``` O fallback nunca faz requisição de rede, então até linhas frias permanecem ágeis. ## 8. Fallback de imagem Open Graph Incorpore um logo em seu próprio card OG gerado dinamicamente via fetch do lado do servidor. ```ts // app/og/route.ts (Next.js, Edge runtime) import { ImageResponse } from "next/og"; export const runtime = "edge"; export async function GET(request: Request) { const { searchParams } = new URL(request.url); const domain = searchParams.get("domain") ?? "example.com"; const logoUrl = `https://api.clearlogo.dev/logo/${domain}?size=256&content=80&token=YOUR_SERVER_KEY`; return new ImageResponse( (
{domain}
), { width: 1200, height: 630 }, ); } ``` Use uma chave de **servidor** aqui, não uma chave de navegador — funções Edge são no lado do servidor, e uma chave de servidor sobrevive headers de origem sem restrições. ## 9. Assinatura de backend para UIs sensíveis Quando você não quer a URL pública (por exemplo, ferramentas de admin interno), faça proxy através de seu backend. ```ts // app/api/logo/[domain]/route.ts (Next.js) export async function GET( request: Request, { params }: { params: { domain: string } }, ) { const upstream = await fetch( `https://api.clearlogo.dev/logo/${params.domain}?size=128&content=80`, { headers: { Authorization: `Bearer ${process.env.CLEARLOGO_SERVER_KEY}` } }, ); return new Response(upstream.body, { headers: { "Content-Type": upstream.headers.get("Content-Type") ?? "image/png", "Cache-Control": "public, max-age=86400, s-maxage=86400", }, }); } ``` Sem chave de API no código-fonte da página, e você controla caching no seu próprio CDN. ## 10. Helper TypeScript Um único helper mantém a construção de URL consistente em toda a base de código. ```ts type LogoOptions = { size?: 16 | 32 | 48 | 64 | 96 | 128 | 192 | 256 | 512 | 1024; content?: number; // 50–100, step 5 theme?: "light" | "dark"; format?: "png" | "webp" | "jpeg"; }; export function logoUrl(domain: string, opts: LogoOptions = {}): string { const params = new URLSearchParams({ size: String(opts.size ?? 64), content: String(opts.content ?? 80), token: process.env.NEXT_PUBLIC_CLEARLOGO_KEY!, }); if (opts.theme) params.set("theme", opts.theme); if (opts.format) params.set("format", opts.format); return `https://api.clearlogo.dev/logo/${encodeURIComponent(domain)}?${params}`; } ``` `encodeURIComponent` protege contra caracteres incomuns em domínios e torna o helper seguro para chamar com entrada não confiável. ## 11. Preconnect para aquecer a conexão cedo Para painéis que renderizam dezenas de logos acima da dobra, o primeiro request paga por DNS, TCP e TLS. Adicione um único `` ao seu head do documento para que a conexão esteja pronta antes do primeiro `` — todo logo subsequente obtém uma vantagem sem excesso de preload por URL. ```html ``` ```tsx // Next.js import Head from "next/head"; export function ClearLogoPreconnect() { return ( ); } ``` `preconnect` resolve DNS e abre o handshake TCP/TLS imediatamente; `dns-prefetch` é um fallback barato para navegadores que ignoram o preconnect. Duas dicas no total, independentemente de quantos logos a página renderiza. Prefira isto a `` por logo — preloads são pesados, contam contra orçamentos de largura de banda, e não ajudam se a URL renderizada acaba sendo um pouco diferente (tamanho, tema, token) da pré-carregada. ## Perguntas Frequentes ### Qual receita devo começar? Para um único logo, a receita `` simples é suficiente. Para listas e tabelas, comece com o slot de avatar Tailwind + padrão de lazy-load. ### Preciso de uma chave para testar? Não. O endpoint funciona anonimamente para navegação de baixo volume. Adicione uma chave de navegador antes de enviar para produção para que a requisição seja adequadamente atribuída e contada contra seu plano. ### Qual tamanho devo pedir? Combine o tamanho renderizado em CSS, depois peça `2x` isso para nitidez retina. Não peça `1024` para um slot de 32 pixels — custa largura de banda e não parece melhor. ### Como lido com modo escuro sem JavaScript? Use um elemento `` com uma `` portada por `media="(prefers-color-scheme: dark)"`. O navegador escolhe a URL correta no tempo de renderização — nenhum hook React, nenhum rerender por logo, nenhuma sobrecarga por linha até em listas longas. ### Como mostro um fallback quando a API não retorna logo? Ouça `onError` na `` e troque por um avatar de letra ou um ícone genérico. A receita de fallback de erro acima é a forma de produção. ### Posso usar uma chave de navegador de uma renderização no lado do servidor? Você pode — mas uma chave de servidor é um ajuste melhor porque envia a requisição via `Authorization: Bearer …` em vez de confiar em verificações de origem. Para Next.js Server Components, rotas OG ou proxies de backend, use uma chave de servidor. ### Como faço cache de logos no meu próprio CDN? Use a receita de assinatura de backend acima. A resposta upstream inclui `Cache-Control` de longa duração, para que você possa definir os mesmos headers no seu proxy e deixar seu CDN fazer o resto.