React hooks and providers for the ENSNode API. This package provides a React-friendly interface to the ENSNode SDK with automatic caching, loading states, and error handling. TanStack Query is handled automatically - no setup required unless you want custom configuration.
Learn more about ENSNode from the ENSNode docs.
npm install @ensnode/ensnode-react @ensnode/ensnode-sdkNote: @tanstack/react-query is a peer dependency but you don't need to interact with it directly unless you want advanced query customization.
Wrap your app with the ENSNodeProvider:
import { ENSNodeProvider, createConfig } from "@ensnode/ensnode-react";
const config = createConfig({ url: "https://api.alpha.ensnode.io" });
function App() {
return (
<ENSNodeProvider config={config}>
<YourApp />
</ENSNodeProvider>
);
}That's it! No need to wrap with QueryClientProvider or create a QueryClient - it's all handled automatically. Each ENSNode endpoint gets its own isolated cache for proper data separation.
import { useRecords } from "@ensnode/ensnode-react";
function DisplayNameRecords() {
const { data, isLoading, error } = useRecords({
name: "vitalik.eth",
selection: {
addresses: [60], // ETH CoinType
texts: ["avatar", "com.twitter"],
},
});
if (isLoading) return <div>Loading...</div>;
if (error) return <div>Error: {error.message}</div>;
return (
<div>
<h3>Resolved Records for vitalik.eth</h3>
{data.records.addresses && (
<p>ETH Address: {data.records.addresses["60"]}</p>
)}
{data.records.texts && (
<div>
<p>Avatar: {data.records.texts.avatar}</p>
<p>Twitter: {data.records.texts["com.twitter"]}</p>
</div>
)}
</div>
);
}import { mainnet } from 'viem/chains';
import { usePrimaryName } from "@ensnode/ensnode-react";
function DisplayPrimaryName() {
const { data, isLoading, error } = usePrimaryName({
address: "0x179A862703a4adfb29896552DF9e307980D19285",
chainId: mainnet.id,
accelerate: true, // Attempt Protocol Acceleration
});
if (isLoading) return <div>Loading...</div>;
if (error) return <div>Error: {error.message}</div>;
return (
<div>
<h3>Primary Name (for Mainnet)</h3>
<p>{data.name ?? 'No Primary Name'}</p>
</div>
);
}import { mainnet } from 'viem/chains';
import { usePrimaryNames } from "@ensnode/ensnode-react";
function DisplayPrimaryNames() {
const { data, isLoading, error } = usePrimaryNames({
address: "0x179A862703a4adfb29896552DF9e307980D19285",
});
if (isLoading) return <div>Loading...</div>;
if (error) return <div>Error: {error.message}</div>;
return (
<div>
{Object.entries(data.names).map(([chainId, name]) => (
<div key={chainId}>
<h3>Primary Name (Chain Id: {chainId})</h3>
<p>{name}</p>
</div>
))}
</div>
);
}The provider component that supplies ENSNode configuration to all child components.
interface ENSNodeProviderProps {
config: ENSNodeConfig;
queryClient?: QueryClient;
queryClientOptions?: QueryClientOptions;
}config: ENSNode configuration objectqueryClient: Optional TanStack Query client instance (requires manual QueryClientProvider setup)queryClientOptions: Optional Custom options for auto-created QueryClient (only used when queryClient is not provided)
Helper function to create ENSNode configuration with defaults.
const config = createConfig({
url: "https://api.alpha.ensnode.io",
});Hook that resolves records for an ENS name (Forward Resolution), via ENSNode, which implements Protocol Acceleration for indexed names.
The returned name field, if set, is guaranteed to be a normalized name. If the name record returned by the resolver is not normalized, null is returned as if no name record was set.
name: The ENS Name whose records to resolveselection: Selection of Resolver records to resolveaddresses: Array of coin types to resolve addresses fortexts: Array of text record keys to resolve
trace: (optional) Whether to include a trace in the response (default: false)accelerate: (optional) Whether to attempt Protocol Acceleration (default: false)query: (optional) TanStack Query options for customization
const { data, isLoading, error, refetch } = useRecords({
name: "example.eth",
selection: {
addresses: [60], // ETH
texts: ["avatar", "description", "url"],
},
});Hook that resolves the primary name of the provided address on the specified chainId, via ENSNode, which implements Protocol Acceleration for indexed names. If the chainId-specific Primary Name is not defined, but the address specifies a valid ENSIP-19 Default Name, the Default Name will be returned. You may query the Default EVM Chain Id (0) in order to determine the address's Default Name directly.
The returned Primary Name, if set, is guaranteed to be a Normalized Name. If the primary name set for the address is not normalized, null is returned as if no primary name was set.
address: The Address whose Primary Name to resolvechainId: The chain id within which to query the address' ENSIP-19 Multichain Primary Nametrace: (optional) Whether to include a trace in the response (default: false)accelerate: (optional) Whether to attempt Protocol Acceleration (default: false)query: (optional) TanStack Query options for customization
const { data, isLoading, error, refetch } = usePrimaryName({
address: "0x179A862703a4adfb29896552DF9e307980D19285",
chainId: 10, // Optimism
accelerate: true, // Attempt Protocol Acceleration
});Hook that resolves the primary names of the provided address on the specified chainIds, via ENSNode, which implements Protocol Acceleration for indexed names. For each Primary Name, if the chainId-specific Primary Name is not defined, but the address specifies a valid ENSIP-19 Default Name, the Default Name will be returned. You may not query the Default EVM Chain Id (0) directly, and should rely on the aforementioned per-chain defaulting behavior.
Each returned Primary Name, if set, is guaranteed to be a Normalized Name. If the primary name set for the address on any chain is not normalized, null is returned for that chain as if no primary name was set.
address: The Address whose Primary Names to resolvechainIds: (optional) Array of chain ids to query the address' ENSIP-19 Multichain Primary Names (default: all ENSIP-19 supported chains)trace: (optional) Whether to include a trace in the response (default: false)accelerate: (optional) Whether to attempt Protocol Acceleration (default: false)query: (optional) TanStack Query options for customization
const { data, isLoading, error, refetch } = usePrimaryNames({
address: "0x179A862703a4adfb29896552DF9e307980D19285",
});The ENSNodeProvider automatically creates and manages a QueryClient for you. Cache keys include the ENSNode endpoint URL, so different endpoints (mainnet vs testnet) maintain separate caches. You can customize the QueryClient without importing TanStack Query:
// Simple setup - no TanStack Query knowledge needed
<ENSNodeProvider
config={config}
queryClientOptions={{
defaultOptions: {
queries: {
staleTime: 1000 * 60 * 10, // 10 minutes
gcTime: 1000 * 60 * 60, // 1 hour
retry: 5,
},
},
}}
>
<App />
</ENSNodeProvider>If you need full control over TanStack Query, you can provide your own QueryClient:
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 1000 * 60 * 10, // 10 minutes
gcTime: 1000 * 60 * 60, // 1 hour
retry: 5,
},
},
});
<QueryClientProvider client={queryClient}>
<ENSNodeProvider config={config} queryClient={queryClient}>
<App />
</ENSNodeProvider>
</QueryClientProvider>;TanStack Query v5+ is used internally. Hook return types are TanStack Query's UseQueryResult for full compatibility, but you don't need to interact with TanStack Query directly unless you want advanced customization.
Queries only execute if all required variables are provided:
const [address, setAddress] = useState("");
// only executes when address is not null
const { data } = usePrimaryName({
address: address || null,
chainId: 1,
accelerate: true, // Attempt Protocol Acceleration
});You can also conditionally enable/disable queries based on your own logic:
const [showPrimaryName, setShowPrimaryName] = useState(false);
// will not execute until `showPrimaryName` is true
const { data } = usePrimaryName({
address: "0x179A862703a4adfb29896552DF9e307980D19285",
chainId: 1,
accelerate: true, // Attempt Protocol Acceleration
query: { enabled: showPrimaryName },
});ENS supports Multichain Primary Names, and ENSNode supports
resolving the Primary Name of an address within the context of a specific chainId.
function ShowMultichainPrimaryNames({ address }: { address: Address }) {
const mainnet = usePrimaryName({ address, chainId: 1 });
const optimism = usePrimaryName({ address, chainId: 10 });
const polygon = usePrimaryName({ address, chainId: 137 });
return (
<div>
<div>Mainnet: {mainnet.data?.records.name || "None"}</div>
<div>Optimism: {optimism.data?.records.name || "None"}</div>
<div>Polygon: {polygon.data?.records.name || "None"}</div>
</div>
);
}Use the error and isError result parameters to handle error states in your application.
const { data, error, isError } = useRecords({ name: "vitalik.eth" });
if (isError) {
return <div>Failed to resolve: {error.message}</div>;
}