Next.js Integration

The xmatter package provides React components for rendering Xmatter icons in Next.js applications. There are two variants: a server component and a client component with different tradeoffs.

npm add xmatter

RemotePattern

Both server and client components use next/image under the hood. Configure remotePatterns in your next.config.ts to allow image optimization from xmatter.org.

import { RemotePattern } from "xmatter/next";

const nextConfig = {
  images: {
    remotePatterns: [RemotePattern],
  },
};

Server Component

xmatter/next/server provides an async server component that uses XmatterClient to check existence before rendering. If the address doesn't exist, it renders the fallback without making an icon request.

import { XmatterClient } from "xmatter/client";
import { XmatterIcon } from "xmatter/next/server";

const xmatter = new XmatterClient("eip155");

export default async function Page() {
  const frontmatter = await xmatter.getFrontmatter("1", "0xc02...");
  if (!frontmatter) return notFound();

  return (
    <XmatterIcon
      client={xmatter}
      chainId="1"
      address="0xc02..."
      width={64}
      height={64}
      alt={`${frontmatter.name} Icon`}
      fallback={<div className="size-16 rounded-full bg-gray-300" />}
    />
  );
}

The server component calls client.getIconUrl() which checks the prefix index before constructing the URL. This means missing addresses are caught without making an icon request.

Client Component

xmatter/next/client provides a client component that renders icons directly by constructing the URL. It does not check existence first.

"use client";
import { XmatterIcon } from "xmatter/next/client";

export function TokenIcon() {
  return (
    <XmatterIcon
      namespace="eip155"
      chainId="1"
      address="0xc02..."
      width={64}
      height={64}
      alt="WETH Icon"
      fallback={<div className="size-16 rounded-full bg-gray-300" />}
    />
  );
}

Using xmatter/next/client, icons are loaded directly without checking existence first. Missing addresses will result in 404 requests to xmatter.org and count against the rate limit. Use the server component if you can, as it checks existence via the prefix index and avoids unnecessary 404 requests.

Server vs Client