# TokenLogo

Shows a token logo by contract address or symbol.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/TokenLogo.tsx)

Figma: [Elements/Logo](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-2546)

## Overview

A token logo renders a stablecoin's artwork, found by contract address or symbol, with its brand colors. Its `alt` is empty unless set, which suits a logo beside the token name.

## Examples

### Basic

```tsx
import { style, TokenLogo } from '@tempoxyz/ds'

export function Demo() {
  return (
    <TokenLogo.Provider>
      <div {...styles.row()}>
        <TokenLogo address="0x20c0000000000000000000000000000000000000" />
        pathUSD
      </div>
    </TokenLogo.Provider>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TokenLogo/Basic.tsx)

### Size

Set `size` to `small` (16px), `medium` (20px, default), or `large` (32px).

```tsx
import { style, TokenLogo } from '@tempoxyz/ds'

const tokens = [
  ['pathUSD', '0x20c0000000000000000000000000000000000000'],
  ['USDC.e', '0x20c000000000000000000000b9537d11c60e8b50'],
  ['EURC.e', '0x20c0000000000000000000001621e21f71cf12fb'],
  ['USDT0', '0x20c00000000000000000000014f22ca97301eb73'],
  ['frxUSD', '0x20c0000000000000000000003554d28269e0f3c2'],
] as const

export function Demo() {
  return (
    <TokenLogo.Provider>
      <div {...styles.grid()}>
        {tokens.map(([label, address]) => (
          <div key={address} {...styles.row()}>
            {(['small', 'medium', 'large'] as const).map((size) => (
              <TokenLogo address={address} key={size} size={size} />
            ))}
            {label}
          </div>
        ))}
      </div>
    </TokenLogo.Provider>
  )
}

namespace styles {
  export const grid = style({ display: 'grid', gap: '12' })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TokenLogo/Size.tsx)

### Symbol

Pass `symbol` instead of `address` to resolve the token through the token list.

```tsx
import { style, TokenLogo } from '@tempoxyz/ds'

export function Demo() {
  return (
    <TokenLogo.Provider>
      <div {...styles.row()}>
        <TokenLogo size="large" symbol="pathUSD" />
        By symbol: pathUSD
      </div>
    </TokenLogo.Provider>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TokenLogo/Symbol.tsx)

### Fallback

An unknown address or symbol renders a placeholder.

```tsx
import { style, TokenLogo } from '@tempoxyz/ds'

export function Demo() {
  return (
    <TokenLogo.Provider>
      <div {...styles.grid()}>
        <div {...styles.row()}>
          <TokenLogo address="0x0000000000000000000000000000000000000001" size="large" />
          Unknown address (service placeholder)
        </div>
        <div {...styles.row()}>
          <TokenLogo size="large" symbol="UNKNOWN" />
          Unknown symbol (fallback)
        </div>
      </div>
    </TokenLogo.Provider>
  )
}

namespace styles {
  export const grid = style({ display: 'grid', gap: '12' })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/TokenLogo/Fallback.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { TokenLogo } from '@tempoxyz/ds'

<TokenLogo.Provider>
  <TokenLogo />
</TokenLogo.Provider>
```

## Guidelines

### When to Use

* Show a token's logo beside its symbol in balance lists, token selectors, payment reviews, and activity rows.

### When Not to Use

* Use [Token](/docs/components/token) to show which token an amount is in, and to let a person change it.
* Use [Identicon](/docs/components/identicon) for an account address.
* Use [Avatar](/docs/components/avatar) for people and organizations.
* Use [IconTile](/docs/components/icon-tile) for a feature or category icon.
* Use [NetworkLogo](/docs/components/network-logo) for the chain a token lives on.
* Use [AssetChip](/docs/components/asset-chip) to list the assets a row supports.

### Pair the Icon With the Symbol

Many token icons look alike, and an unknown token can copy a well-known icon.

**Do:** Show the symbol beside each token icon.

```tsx
/**
 * Do example for "Pair the Icon With the Symbol" on the TokenLogo page.
 * Show the symbol beside each token icon.
 * @module
 */
import { style, TokenLogo } from '@tempoxyz/ds'

const tokens = [
  ['pathUSD', '0x20c0000000000000000000000000000000000000'],
  ['USDC.e', '0x20c000000000000000000000b9537d11c60e8b50'],
  ['EURC.e', '0x20c0000000000000000000001621e21f71cf12fb'],
] as const

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <TokenLogo.Provider>
      <div {...styles.list()}>
        {tokens.map(([symbol, address]) => (
          <div key={address} {...styles.row()}>
            <TokenLogo address={address} />
            <span {...styles.symbol()}>{symbol}</span>
          </div>
        ))}
      </div>
    </TokenLogo.Provider>
  )
}

namespace styles {
  export const list = style({ display: 'grid', gap: '12' })

  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })

  export const symbol = style({ color: 'content.primary', typography: 'body.b2Strong' })
}
```

**Don't:** Ask people to tell tokens apart by icon alone.

```tsx
/**
 * Don't example for "Pair the Icon With the Symbol" on the TokenLogo page.
 * Don't ask people to tell tokens apart by icon alone.
 * @module
 */
import { style, TokenLogo } from '@tempoxyz/ds'

const addresses = [
  '0x20c0000000000000000000000000000000000000',
  '0x20c000000000000000000000b9537d11c60e8b50',
  '0x20c0000000000000000000001621e21f71cf12fb',
] as const

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <TokenLogo.Provider>
      <div {...styles.row()}>
        {addresses.map((address) => (
          <TokenLogo address={address} key={address} />
        ))}
      </div>
    </TokenLogo.Provider>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })
}
```

### Prefer the Address

* **Address (address):** Use it when you have it. It loads the image directly and names one contract.
* **Symbol (symbol):** Resolves through the token list first, which adds a request. Different tokens can share a symbol.
* **Lists (TokenLogo.Provider):** Wrap lists so tokens share one lookup per symbol and a default `chainId`.

Pass `resolveSrc` or `resolveAddress` to `TokenLogo.Provider` to load icons or addresses from your own source.

### Show Unknown Tokens as Unknown

A gray circle renders while an icon loads or after it fails.

**Do:** Show the address in a [Hex](/docs/components/hex) beside the symbol of a token that isn't on the
list.

```tsx
/**
 * Do example for "Show Unknown Tokens as Unknown" on the TokenLogo page.
 * Show the address in a Hex beside the symbol of a token that isn't on the list.
 * @module
 */
import { Hex, style, TokenLogo } from '@tempoxyz/ds'

const address = '0x20c00000000000000000000098a3f2c1e5d70b44'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <TokenLogo address={address} />
      <div {...styles.text()}>
        <span {...styles.symbol()}>USDC</span>
        <Hex size="small" value={address} />
      </div>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12', minWidth: '0' })

  export const symbol = style({ color: 'content.primary', typography: 'body.b2Strong' })

  export const text = style({ display: 'grid', gap: '4', minWidth: '0' })
}
```

**Don't:** Show only the symbol. Any token can claim it.

```tsx
/**
 * Don't example for "Show Unknown Tokens as Unknown" on the TokenLogo page.
 * Don't show only the symbol. Any token can claim it.
 * @module
 */
import { style, TokenLogo } from '@tempoxyz/ds'

const address = '0x20c00000000000000000000098a3f2c1e5d70b44'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <TokenLogo address={address} />
      <span {...styles.symbol()}>USDC</span>
    </div>
  )
}

namespace styles {
  export const row = style({ alignItems: 'center', display: 'flex', gap: '12' })

  export const symbol = style({ color: 'content.primary', typography: 'body.b2Strong' })
}
```

### Match Size to the Context

* **Small (16px):** Inline beside an amount.
* **Medium (20px):** The default, and the logo in a [Token](/docs/components/token).
* **Large (32px):** In asset rows and token pickers.

## Accessibility

A token logo renders a native `<img>`, decorative by default. It is not interactive and takes no focus.

### Semantics

* **Root (img):** Has empty alt text by default, so screen readers skip it beside a visible name.
* **Loading and Errors:** Renders a gray circle while loading or after an error. Text must identify the token.
* **Data Status (data-status):** Reports `loading`, `loaded`, or `error` for styling. Screen readers don't announce it.

### Your Responsibilities

* **Name a Standalone Icon (alt):** If the icon stands alone, such as in an icon-only selector, pass the token name.

## Related

[Amount](/docs/components/amount)

Use for token amounts.

[Token](/docs/components/token)

Use for a token pill that labels or picks a token.

[AssetChip](/docs/components/asset-chip)

Use for listing the assets a row supports.

[NetworkLogo](/docs/components/network-logo)

Use for the chain a token lives on.

[Identicon](/docs/components/identicon)

Use for account addresses.

[Avatar](/docs/components/avatar)

Use for people and organizations.

[Select](/docs/components/select)

Use for token selectors.

[Blockchain Values](/docs/patterns/blockchain-values)

Covers tokens and addresses.
