SNS React

React Query hooks for the Solana Name Service JavaScript SDK v4. The package provides a focused set of read helpers with stable cache keys and safe record handling.

Installation

Install SNS React with its peers:

npm install @bonfida/sns-react @bonfida/spl-name-service@^4.0.0 @solana/web3.js@^1.98.2 @tanstack/react-query@^5.0.0 react

SNS React supports React 18 and 19. The SNS JS SDK is a peer dependency so the application and hooks use one compatible v4 SDK instance.

Setup

Create a TanStack Query client near the application root:

import type { PropsWithChildren } from "react";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const queryClient = new QueryClient();

export function AppProviders({ children }: PropsWithChildren) {
  return (
    <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
  );
}

Pass a web3.js Connection to each hook. SNS React does not create a global RPC client or wallet provider.

Quick Start

Resolve A Domain

import { useResolve } from "@bonfida/sns-react";
import { Connection } from "@solana/web3.js";

const connection = new Connection("https://your-rpc-endpoint.example");

function Resolve() {
  const target = useResolve(connection, "example.sns");

  if (target.isPending) return <p>Loading...</p>;
  if (target.isError) return <p>{target.error.message}</p>;
  return <p>{target.data.toBase58()}</p>;
}

Use useSafeResolve instead when the JavaScript SDK's conditional SRS/SNS consistency verification is required.

Read Verified Records

import { Record } from "@bonfida/spl-name-service/record";
import { useRecords } from "@bonfida/sns-react";
import type { Connection } from "@solana/web3.js";

function Records({ connection }: { connection: Connection }) {
  const records = useRecords(
    connection,
    "example.sns",
    [Record.Url, Record.Email],
    { deserialize: true },
  );

  return (
    <ul>
      {records.data?.map((record, index) => (
        <li key={index}>{record?.deserializedContent ?? "Unavailable"}</li>
      ))}
    </ul>
  );
}

useRecords preserves request order. An entry is undefined when the account is missing or fails a required verification check.

Domain Inputs

| Hook | Input | Notes | | ------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | useResolve, useSafeResolve, useRecords, useProfilePic | Full domain such as example.sns | useSafeResolve delegates to JS SDK safe resolution and compares targets only when SRS-backed .sol resolution is enabled; other hooks inherit JS v4 domain support. | | useSubdomains | TLD-trimmed SNS parent such as example | Passed to v4 getSnsDomainKeySync. Do not include .sns. | | useSnsDomainsForOwner, usePrimaryDomain | Wallet PublicKey | Nullish input disables the query. | | useReverseLookup | Domain account PublicKey | Nullish input disables the query. |

High-level .sol reads use the JS SDK compatibility path only before finalized slot 452825395. At or after that slot they throw UnsupportedTldError. SNS React does not extend that support.

Record Safety

JS SDK v4 getMultipleRecords verifies record staleness and Right of Association (ROA). SNS React returns a record only when:

result.verified.staleness === true && result.verified.roa !== false;

verified.roa can be absent when the record type has no applicable ROA verifier. That is not a failed check. verified.roa === false is rejected.

useProfilePic uses the same checks and returns verified, deserialized content or null.

API Reference

useResolve

Resolves a full domain to its effective owner with v4 resolve.

useResolve(connection, domain, queryOptions?)

useSafeResolve

Resolves a full domain through JS SDK safeResolve. When SRS-backed .sol resolution is enabled, the .sol and corresponding .sns targets must match. Mismatches and other SDK failures are available through the query result's error and isError fields.

useSafeResolve(connection, domain, queryOptions?)

useSnsDomainsForOwner

Returns sorted v4 SnsDomain[] values with { domain, key }. Results include directly registry-owned top-level domains with valid reverse records. Tokenized domains and subdomains are not included.

useSnsDomainsForOwner(connection, ownerPublicKey, queryOptions?)

usePrimaryDomain

Returns the native v4 { domain, reverse, stale } result. A missing primary domain returns null; RPC and other SDK errors remain query errors.

usePrimaryDomain(connection, ownerPublicKey, queryOptions?)

useSubdomains

Derives a parent account from a TLD-trimmed SNS name and returns its human-readable subdomains.

useSubdomains(connection, "example", queryOptions?)

useReverseLookup

Returns the reverse name for a domain account key.

useReverseLookup(connection, domainKey, queryOptions?)

useRecords

Fetches, optionally deserializes, verifies, and filters multiple v4 records.

useRecords(
  connection,
  domain,
  records,
  { deserialize?: boolean },
  queryOptions?,
)

useProfilePic

Returns safe Record.Pic content or null.

useProfilePic(connection, domain, queryOptions?)

Documentation

• Developer documentation
• SNS React v4 changelog
• JS SDK v4 README
• SDK monorepo overview
• SNS guide

License

SNS React is licensed under the MIT License.