> brandicons_

API Documentation

Simple, powerful, and designed for developers

React component

Recommended
neocoder/react-brandicons

The official drop-in component. Renders an <img>, polls the x-brandicons-state header, and auto-upgrades the placeholder once the real icon arrives — no reload needed.

stripe.com
vercel.com
linear.app
figma.com

Live <BrandIcon /> — same component, same API key

import { BrandIcon } from "react-brandicons";


export function CompanyLogo() {
    return (
        <BrandIcon
            domain="stripe.com"
            apiKey="YOUR_API_KEY"
            size="medium"
            loadingPlaceholder="@loader-spin"
            placeholder="@empty"
        />
    );
}
bun add react-brandiconsnpm i react-brandiconspnpm add react-brandicons

Quick Start

Use the following URL pattern to fetch brand icons:

https://cdn.brandicons.dev/icons/{domain}/{size}?key=YOUR_API_KEY

Size (path segment):

  • small — 32×32
  • medium — 64×64 (default)
  • large — 128×128
  • vector — SVG when available

Optional placeholders:

  • ?p= — shown when the icon is definitively not found
  • ?pl= — shown while we're still searching

Reference a built-in (e.g. @image-off, @loader-spin, @globe) or one of your own uploaded names. Twelve built-ins are available by default.

Or use @letter to draw a square with the domain's initials. Pick a palette that fits your site — @letter-pastel, @letter-vibrant, or muted by default — or pass your own color as @letter:0ea5e9.

Set nothing and you get @empty — a thin neutral X that reads on light and dark pages. Every built-in can be themed: add -light or -dark (e.g. @globe-dark), or set your own colors with @globe:ffffff:1f2937 (background then line; none background = no fill).

Backgrounds for transparent logos:

  • ?bg=auto — bakes our contrast-safe tile into the image so the logo stays visible on colored or dark surfaces
  • ?bg=0ea5e9 — force a color (6-digit hex, no #) to match your UI

Opt-in: leave it off and the icon is served as-is (transparent), so it composes with your own rounded containers and cards.

Example:

<img src="https://cdn.brandicons.dev/icons/spotify.com/medium?key=YOUR_API_KEY&p=@empty&pl=@loader-spin&bg=auto" alt="Spotify" />

How Icon Discovery Works

Brandicons uses an intelligent discovery system to find and cache brand icons:

1

Loading state

On the first request for a new domain we serve your ?pl= placeholder and trigger a background search. Response carries x-brandicons-state: loading with a 10-second TTL.

2

Found — icon cached

The worker stores the icon globally on our CDN. Subsequent requests return the real icon (no state header) — typically within seconds.

3

Not found — graceful fallback

If we can't discover an icon, we serve your ?p= placeholder with x-brandicons-state: not-found and a 24-hour TTL.

Auto-upgrade with react-brandicons

The official component reads x-brandicons-state from a HEAD request and refreshes the image when the real icon arrives — no reload needed.

Usage & Caching

API Keys:

Each key is locked to a single domain (e.g. example.com + www.example.com). Keys are public by design — safe to use in <img> tags and client-side code.

Monthly Quota:

Each plan includes a monthly request quota. All requests (cache hits and misses) count toward it. No per-second rate limiting — icons are served directly from CDN edge nodes.

Caching:

Icons are cached globally on the CDN after first discovery. Subsequent requests for the same domain resolve in ~20ms in the browser from the nearest edge.

Frequently Asked Questions

Everything you need to know about BrandIcons and how it simplifies brand icon integration

What is BrandIcons and how does it work?
BrandIcons is a simple API service that provides brand icons for any domain. Just use our URL format with a domain name and get the corresponding brand icon. We automatically discover and serve icons from websites and related sources.
How do I use the BrandIcons API?
Use the URL format https://cdn.brandicons.dev/icons/{domain}/{size}?key={YOUR_API_KEY}. Optional ?p= sets a not-found placeholder and ?pl= sets a loading placeholder — both accept built-ins like @image-off and @loader-spin or your own uploaded names.
What icon sizes are available?
Five values for the size path segment: ico, small (32×32), medium (64×64, default), large (128×128), and vector (SVG when available). Choose what fits your layout.
Can I show a custom loading icon while you search?
Yes. Add ?pl=@loader-spin (animated SVG) or ?pl=@loader (static) to the URL — or use the loadingPlaceholder prop on the react-brandicons component. Once we've discovered the real icon, the placeholder is replaced automatically.
What happens when an icon can't be found?
By default you get @empty — a thin neutral X that works on light and dark pages (use @empty-light or @empty-dark to match your theme). You can also set ?p= to a built-in like @image-off, one of your own uploads, or @letter — a square with the domain's initials and a color picked from the domain. For @letter, choose @letter-pastel, @letter-vibrant, or the muted default, or pass your own color as @letter:0ea5e9 (6-digit hex, no #).
Is there a React component?
Yes — install react-brandicons. It renders an <img>, polls the x-brandicons-state header on a HEAD request, and refreshes the image when the icon arrives. Twelve built-in placeholders ship with it (@globe, @image-off, @loader-spin, …).
What's included in the free Community plan?
The Community plan is free forever and includes 500,000 requests per month, 2 API keys, all icon sizes, twelve built-in placeholders, and the global CDN. In exchange, your production site must display a visible attribution link back to BrandIcons (see the next question for details). Want to skip attribution? Any paid plan removes the requirement.
What's the attribution requirement on the Community plan?
Add a visible link with the anchor text "Icons by BrandIcons" pointing to https://brandicons.dev on your production site — directly beside or below your logo grid, in the footer alongside other credits, or on an About/Credits page. The link must pass referrer data (no rel="nofollow", no rel="noreferrer") and must be on a publicly accessible URL (not staging or localhost). The exact snippet: <a href="https://brandicons.dev">Icons by BrandIcons</a>. Any paid plan removes this requirement.
How do you find icons for domains without websites?
Our intelligent discovery system uses AI analysis and web research to find icons for domains that don't have active web servers. We search related websites, company profiles, and use advanced matching algorithms to locate the most appropriate brand icons.
How does API key domain binding work?
For security, API keys can be bound to specific domains. This means your key will only work when called from your registered domains, preventing unauthorized usage and protecting your quota from external access.