> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brandfetch.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Brandfetch returns real company logos, brand data, and brand context. It does not design, generate, or edit logos.
> To show a logo in a user interface, use the Logo API as an image URL in an <img> tag, such as https://cdn.brandfetch.io/domain/{domain}?c={CLIENT_ID}. The client ID is public and belongs in frontend code. Never download, proxy, re-host, or optimize these images on a server, because requests that look programmatic are redirected with automated_traffic. In Next.js, this means next/image needs a custom loader or the unoptimized prop.
> To turn a company name that a user types into a domain, use the Brand Search API with the same client ID, and keep only the domain the user picks.
> For colors, fonts, downloadable logo files, and company data as JSON, call the Brand API from a server with the header Authorization: Bearer {API_KEY}, reading the key from an environment variable and never exposing it to the browser. Prefer typed routes such as /v2/brands/domain/{domain} and /v2/brands/ticker/{ticker} over the auto-detect route /v2/brands/{identifier}.
> Use the Brand Context API for a written summary of what a company does, who it sells to, and how it sounds, and the Transaction API to identify the merchant behind a card or bank transaction label.
> When a request fails, branch on the x-bf-error header code rather than on the status code or the message text. Every code, and what to do about it, is listed at https://docs.brandfetch.com/concepts/errors.
> Requests for brandfetch.com are free on the Brand API and Brand Context API, so use that domain in tests and examples.
> Brand API responses can be cached for up to 30 days, while Logo API images must be hotlinked rather than stored and Brand Search results must not be stored at all. See https://docs.brandfetch.com/concepts/caching.
> If the user has no credentials yet, https://brandfetch.com/auth.md explains how they get a client ID and an API key. An agent without an account can pay $0.10 per Brand API, Brand Context API, or Transaction API request with x402 or MPP, as described at https://docs.brandfetch.com/agents/pay-per-request.

# Logos in dark mode

> Keep company logos visible on dark backgrounds with the Logo API's theme option: request the light version, switch with prefers-color-scheme or your app's theme toggle, and handle brands that only have one version.

A company logo that looks right on a white page often disappears on a dark one, because most wordmarks are drawn in black or a deep brand color. The [Logo API](https://docs.brandfetch.com/logo-api/overview.md) serves two versions of each logo through the `theme` option, so the fix is to request the version that matches your background and switch between the two when your app's theme changes.

Preview

## Which theme to request

The `theme` value names the color of the logo rather than the color of the background, which is the opposite of what many people expect, so a dark page needs `theme/light`:

| Background | Request | What you get |
| - | - | - |
| Light | `theme/dark` | The logo in the brand's usual dark colors |
| Dark | `theme/light` | A light version, which for most wordmarks is all white |

```text theme={null}
https://cdn.brandfetch.io/domain/nike.com/theme/dark/logo?c=BRANDFETCH_CLIENT_ID
https://cdn.brandfetch.io/domain/nike.com/theme/light/logo?c=BRANDFETCH_CLIENT_ID
```

A URL without `theme` returns the version made for light backgrounds, so existing logo URLs only need a change where they sit on a dark surface.

## Follow the system theme

When your site follows the visitor's operating system setting, a `<picture>` element does the switching without any JavaScript. The browser requests only the version that matches, and it swaps the image as soon as the system theme changes:

```html theme={null}
<picture>
  <source
    media="(prefers-color-scheme: dark)"
  />
  <img
    src="https://cdn.brandfetch.io/domain/nike.com/h/64/theme/dark/logo?c=BRANDFETCH_CLIENT_ID"
    alt="Nike logo"
    height="32"
  />
</picture>
```

Request twice the height you display, as with `h/64` for a 32-pixel logo here, so the logo stays sharp on high-density screens.

## Follow your app's theme toggle

Apps with their own light and dark switch usually mark the theme with a class on the `<html>` element, and a `<picture>` media query can't see that class because it only reads the system setting. The simplest approach in that case is to render both versions and let CSS show the right one:

```html theme={null}
<img class="logo-on-light" src="https://cdn.brandfetch.io/domain/nike.com/h/64/theme/dark/logo?c=BRANDFETCH_CLIENT_ID" alt="Nike logo" height="32" />
<img class="logo-on-dark" src="https://cdn.brandfetch.io/domain/nike.com/h/64/theme/light/logo?c=BRANDFETCH_CLIENT_ID" alt="Nike logo" height="32" />
```

```css theme={null}
.logo-on-dark { display: none; }
.dark .logo-on-light { display: none; }
.dark .logo-on-dark { display: inline; }
```

With Tailwind, the same thing is `dark:hidden` on the first image and `hidden dark:inline` on the second. Hiding an image with CSS doesn't stop the browser from downloading it, so every logo costs two requests this way. For long lists, pick a single URL from your theme state instead, as the component in the next section does.

## When a brand has no light version

Most well-known brands have both versions, but some only have one, and Plausible and ING, for example, have no light logo at the time of writing. A request for a version that doesn't exist returns the default [fallback](https://docs.brandfetch.com/logo-api/parameters.md#fallback), which is the Brandfetch logo, so check whether the light version exists before deciding which URL to render.

The [Brand API](https://docs.brandfetch.com/brand-api/overview.md) answers that question in one request. Its `logos` array lists every logo the brand has along with its `theme`, where `light` marks a logo made for dark backgrounds, so a brand has a light version when one of its `logo` entries has that theme. The Brand API needs your secret key, so make the call on your server, and since a brand's logos rarely change, store the result with the company record or cache it rather than calling on every page view:

```ts brand.ts theme={null}
export async function hasLightLogo(domain: string): Promise<boolean> {
  const res = await fetch(`https://api.brandfetch.io/v2/brands/domain/${domain}`, {
    headers: { Authorization: `Bearer ${process.env.BRANDFETCH_API_KEY}` },
  });
  if (!res.ok) return false;

  const brand = await res.json();
  return brand.logos.some((logo) => logo.type === "logo" && logo.theme === "light");
}
```

Whenever the light version exists, request it, since it's the version the brand drew for dark backgrounds. Only when it's missing does it make sense to turn the regular logo white with a CSS filter:

```css theme={null}
.logo-fallback { filter: brightness(0) invert(1); }
```

The filter paints every visible pixel white, which works well for simple one-color wordmarks but has some risks. A logo built from several colored shapes loses its inner detail and becomes one flat white silhouette, a logo drawn on a filled background turns into a solid white block, and the brand's own colors disappear, which some brand guidelines don't allow. That's why the filter belongs in the fallback path only, after the check, rather than on every logo in dark mode.

With the answer known before anything renders, the component that shows the logo needs no state or error handling. It picks the URL from `hasLight` and from `dark`, which comes from whatever holds your theme, such as `resolvedTheme === "dark"` from `next-themes`:

```tsx BrandLogo.tsx theme={null}
const CLIENT_ID = "BRANDFETCH_CLIENT_ID";

const logoUrl = (domain: string, theme: "light" | "dark") =>
  `https://cdn.brandfetch.io/domain/${domain}/h/64/theme/${theme}/logo?c=${CLIENT_ID}`;

type Props = { domain: string; hasLight: boolean; dark: boolean };

export function BrandLogo({ domain, hasLight, dark }: Props) {
  const whiten = dark && !hasLight; // no light version, so turn the regular logo white

  return (
    <img
      src={logoUrl(domain, dark && hasLight ? "light" : "dark")}
      alt={`${domain} logo`}
      height={32}
      style={whiten ? { filter: "brightness(0) invert(1)" } : undefined}
    />
  );
}
```

With Tailwind, the same filter is `brightness-0 invert`. If you don't use the Brand API, adding `fallback/404` to the `theme/light` URL makes the request fail when that version is missing, which you can catch with the image's `onError` handler, though the logo then has to load once before your page knows which version to show.

## Icons in dark mode

Where a logo only needs to identify the company, as in a list, a table, or an avatar, the square `icon` type avoids the problem altogether. Icons are the images brands use as profile pictures, so they usually come with their own background color and read clearly on light and dark pages alike, and a slightly rounded corner helps them sit on either surface:

```html theme={null}
<img
  src="https://cdn.brandfetch.io/domain/nike.com/w/64/h/64/fallback/lettermark/icon?c=BRANDFETCH_CLIENT_ID"
  alt="Nike logo"
  width="32"
  height="32"
  style="border-radius: 8px"
/>
```

For a grid of customer or partner logos in both themes, see [Logo walls](https://docs.brandfetch.com/use-cases/logo-wall.md), which combines the theme switch with sizing that keeps logos of different shapes looking even.

## FAQ

> [accordion] How do I show a company logo on a dark background?
>
> Add `theme/light` to the Logo API URL, as in `https://cdn.brandfetch.io/domain/nike.com/theme/light/logo?c=BRANDFETCH_CLIENT_ID`, which returns the version of the logo made for dark backgrounds.

> [accordion] What's the difference between theme/light and theme/dark?
>
> The value describes the logo, not the background. `theme/dark` is a dark logo for light backgrounds, and `theme/light` is a light logo for dark backgrounds.

> [accordion] Why does the Brandfetch logo show up instead of the company's logo in dark mode?
>
> The brand has no light version, so the request returned the default fallback. Check the Brand API's `logos` array for a logo with `theme: "light"` before rendering, and when there isn't one, show the regular logo turned white with `filter: brightness(0) invert(1)`, as in the [component above](#when-a-brand-has-no-light-version).

> [accordion] How do I switch logos when the user changes theme?
>
> Use a `<picture>` element with a `prefers-color-scheme: dark` source when your site follows the system setting. When your app has its own theme toggle, pick the URL from your theme state, or render both versions and hide one with CSS.

> [accordion] Can I get a white version of a company logo?
>
> For most brands, yes. `theme/light` returns the version for dark backgrounds, which for most wordmarks is all white. A few brands don't have one, and the Brand API's `logos` array tells you when that's the case. For those, a CSS filter can turn the regular logo white, though it flattens multicolor logos, so use it only as a fallback.

## Related

> [card] [Logo API parameters](https://docs.brandfetch.com/logo-api/parameters.md)
>
> Theme, type, size, and fallback options for every logo URL

> [card] [Logo walls](https://docs.brandfetch.com/use-cases/logo-wall.md)
>
> Customer and partner logo grids that work in both themes


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.