Docs — BrandIcons

API Documentation

Simple, powerful, and designed for developers

React component

Recommended

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.

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="@image-off"
        />
    );
}

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.

Example:

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

How Icon Discovery Works

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

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.

Found — icon cached

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

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.

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.